feat(gateway): 接入42和72并为42/52/72启用可刷新令牌

docs/接口42-52-72网关鉴权.md

@@ -0,0 +1,35 @@
+# 42、52、72 号接口网关鉴权
+
+| 接口 | 方法与路径 | 执行位置 |
+|---|---|---|
+| 42 | `POST /api/v1/face/features-42` | 网关按接口 52 的规则扶正裁切，再用接口 4 的分析结果和 Ft/Zy 判定生成特征 |
+| 52 | `POST /api/v1/hairline/generate-52` | 网关转发至 worker |
+| 72 | `POST /api/v1/face/b-end-points` | 网关转发至 worker，底图与标注层转成 URL |
+
+客户端调用这三个接口时，在原请求上添加 `Authorization: Bearer <access_token>`。缺少、过期、签名无效或误用刷新令牌时，返回 HTTP 401 和业务码 `1009`。网关验证通过后，52 和 72 继续使用独立的 `X-Internal-Token` 转发至 worker，客户端令牌不会传给 worker。
+
+## 登录
+
+`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 改写流程。
+
+网关测试页为 `/static/test_interface42.html`、`/static/test_interface52.html` 和 `/static/test_interface72.html`，页面先登录再提交，访问令牌到期时自动刷新。