# 客户端网关鉴权

| 接口 | 方法与路径 | 执行位置 |
|---|---|---|
| 11 | `POST /api/v1/face/measure-11` | 网关转发至 worker 的接口 1，沿用四庭七眼测量及标注图 |
| 22 | `POST /api/v1/hair/grow-22` | 网关转发至 Worker，发际线预览和生发图转成 URL |
| 42 | `POST /api/v1/face/features-42` | 网关按接口 52 的规则扶正裁切，再用接口 4 的分析结果和 Ft/Zy 判定生成特征 |
| 52 | `POST /api/v1/hairline/generate-52` | 网关转发至 worker |
| 61 | `POST /api/v1/face/measure-61` | 网关转发至 worker 的接口 6，沿用去顶庭的测量及标注图 |
| 72 | `POST /api/v1/face/b-end-points` | 网关转发至 worker，底图与标注层转成 URL |

客户端调用这些接口时，在原请求上添加 `Authorization: Bearer <access_token>`。缺少、过期、签名无效或误用刷新令牌时，返回 HTTP 401 和业务码 `1009`。网关验证通过后，11、22、52、61、72 通过现有 worker 池转发。11 和 61 沿用 1 和 6 的图片参数、响应字段及标注图 URL，Bearer 令牌只在网关校验。

## 登录

`POST /api/v1/auth/login`，请求体为 JSON，包含 `username` 和 `password`。当前用户名为 `yonghe`，密码使用约定的服务端固定值。

成功时 HTTP 200、`code=0`，`data` 包含：

| 字段 | 值 |
|---|---|
| `access_token` | 访问令牌 |
| `token_type` | `Bearer` |
| `expires_in` | 900 秒 |
| `refresh_token` | 刷新令牌 |
| `refresh_expires_in` | 604800 秒，即 7 天 |

## 刷新

`POST /api/v1/auth/refresh`，请求体为 `{"refresh_token":"登录返回的刷新令牌"}`。成功后返回新的 `access_token`、`token_type` 和 `expires_in`。登录时的刷新令牌可以在原有效期内继续使用。到期后重新登录。登录或刷新失败时，响应包含 `code`、`message`、`request_id` 和 `data: null`。

## 网关配置

在 `main` 的网关环境中设置 `HAIR_API_TOKEN_SECRET`，或在未跟踪的 `gateway/config.json` 中设置 `api_token_secret`。使用独立且稳定的至少 32 字节随机值。签名密钥缺失时，签发或刷新返回 HTTP 503 和业务码 `1007`。更换签名密钥会使已签发令牌失效。

网关保留原有 Ark、MediaPipe 与 BiSeNet 配置，42 的裁切还使用 Pillow。部署 72 前，确认所有可接收该请求的 worker 已部署含 72 号的版本（例如 `ubuntu3090_debug` 的 `c9a47a7` 或后续版本）。52、72 沿用现有 worker 池与图片 URL 改写流程。

部署接口 22 前，确认 Worker 池的主备节点均包含接口 22（例如 `ubuntu3090_debug` 上的 `b84a506` 或后续版本）。Worker 启用 IP 白名单时，配置网关直连地址。

网关测试页为 `/static/test_interface11.html`、`/static/test_interface22.html`、`/static/test_interface42.html`、`/static/test_interface52.html`、`/static/test_interface61.html` 和 `/static/test_interface72.html`。页面可登录、手动刷新令牌并提交图片，访问令牌到期时自动刷新。「测试鉴权」调用 `GET /api/v1/auth/check`，验证无令牌请求返回 HTTP 401、有效令牌请求返回 HTTP 200。