save code

2026-06-13 23:04:37 +08:00
parent d8a6e53979
commit 2c669fa7e5
2 changed files with 766 additions and 0 deletions
@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+"旷视五接口" — a FastAPI facial analysis API service providing 5 endpoints for face measurement, hair growth simulation (C-end and B-end), user feature extraction, and hairline PNG generation. Currently a **Mock v1**: all endpoints return hardcoded sample data; real ML logic is pending.
+
+- **Base URL (prod)**: `https://hair.xiangsilian.com`
+- **Swagger docs**: `https://hair.xiangsilian.com/docs`
+- **Internal**: uvicorn on `127.0.0.1:8000` behind nginx reverse proxy
+
+## Commands
+
+```bash
+# Development server
+./venv/bin/uvicorn app:app --host 127.0.0.1 --port 8000 --reload
+
+# Or via the start script
+./start.sh
+
+# Production (systemd)
+sudo systemctl restart hair
+sudo systemctl status hair
+journalctl -u hair -f
+
+# Install dependencies (uses Tencent Cloud PyPI mirror)
+./venv/bin/pip install -r requirements.txt
+```
+
+## Architecture
+
+**Single-file app** — `app.py` (~555 lines) contains the entire server: FastAPI app creation, Pydantic models, all 5 endpoint handlers, and health check routes. There are no separate routers, services, or middleware modules.
+
+### Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | `/api/v1/face/measure` | 四庭七眼 measurement + annotated PNG |
+| POST | `/api/v1/hair/grow` | C-end hair growth (user-facing) |
+| POST | `/api/v1/hair/grow-b` | B-end hair growth (doctor/operator, with marked image) |
+| POST | `/api/v1/face/features` | User facial feature analysis |
+| POST | `/api/v1/hairline/generate` | Hairline PNG generation |
+| GET | `/health` | Health check (excluded from OpenAPI schema) |
+| GET | `/` | Service info (excluded from OpenAPI schema) |
+
+### Image input convention (all endpoints)
+
+Every endpoint accepts images via **exactly one** of three mutually exclusive fields:
+- `image_file` — multipart file upload (≤ 1 MB)
+- `image_url` — HTTP/HTTPS URL string
+- `image_base64` — base64 string with `data:image/...;base64,` prefix
+
+Endpoint 3 (B-end) has **two** sets of image params: `marked_image_*` (the marked-up image) and `original_image_*` (the original photo). Each set follows the same three-way exclusive rule independently.
+
+### Unified response structure
+
+```json
+{"code": 0, "message": "success", "request_id": "mock-request-id", "data": {...}}
+```
+
+Error codes: 1001–1008 (see `app.py` docstring or `docs/接口文档.md`).
+
+### Key code patterns
+
+- `ok(data)` / `err(code, msg)` — helper functions at module level that build the standard response envelope
+- `ImageJsonBody` — Pydantic model for JSON-based image params (URL/base64); form-upload endpoints use FastAPI `Form()` / `File()` parameters directly
+- `SAMPLE_IMAGE_URL` — `https://hair.xiangsilian.com/static/sample.jpg`, returned as the image URL in all mock responses
+- Static files (`/static/*`) are mounted via `app.mount("/static", StaticFiles(directory="static"), name="static")`
+- All 5 POST endpoints use `multipart/form-data` with both `File` and `Form` fields — there are no JSON-body POST endpoints despite `ImageJsonBody` being defined (it exists for the OpenAPI schema but the actual handlers use `Form()` for all params)
+
+### Deployment
+
+- **Process manager**: systemd (`hair.service` → `ExecStart` runs uvicorn directly from venv)
+- **Reverse proxy**: nginx (`nginx/hair.conf`) proxies port 80 → `127.0.0.1:8000` for `hair.xiangsilian.com`
+- **Python**: venv at `./venv`, dependencies in `requirements.txt`
+- **PyPI mirror**: Tencent Cloud (`mirrors.cloud.tencent.com`), configured in `pip.conf`
+
+### Documentation
+
+- `docs/接口文档.md` — complete API documentation (inputs, outputs, examples, error codes)
+- `docs/旷视具体需求.md` — original requirements spec (converted from `.docx`)
+- The FastAPI app's `description` docstring in `app.py` is an additional source of API docs visible in Swagger UI