84 lines
3.9 KiB
Markdown
84 lines
3.9 KiB
Markdown
# 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
|