hair/CLAUDE.md

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

# 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

{"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