feat(接口99): 人脸特殊点检测 + 网关转发路由；文档同步至当前代码

- worker: POST /api/v1/face/special-points，60 个固定编号关键点（6组）
  + 5 个发际线特殊点（沿指定关键点方向射线步进，与 BiSeNet 头发 mask 首次相交；
  双射线取中点，left_left=mid(333→332, 298→284) 与右侧镜像）
- 网关: 同路径盲转发路由（调用频率低，维持转发不占网关依赖；
  响应无 *_base64 字段，改写逻辑天然跳过）
- 测试页 static/test_interface99.html：分组着色小点 + 点ID标注（可开关）
  + 发际线点大圆标签 + JSON 展示
- 文档: CLAUDE.md 重写至当前架构；实现说明/接口文档补接口 9~12/99 契约；
  网关待改动补 §7(9/10已加) §8(11/12待加) §9(接口99部署步骤)

docs/实现说明.md

@@ -12,13 +12,15 @@
 
 ```
 客户端 ──HTTPS──> 外网网关(gateway/)  ──HTTP(X-Internal-Token)──> worker(GPU 机, app.py)
-                     │ 薄代理 + 落盘改URL                          │ 跑算法(本地模型/ComfyUI)
-                     └ 接口4 本机直接调豆包(不转发)                 └ 接口1/2/3/5/6/7
+                     │ 薄代理 + 落盘改URL                          │ 跑算法(本地模型/ComfyUI/change_hair)
+                     └ 接口4 本机直接调豆包(不转发)                 └ 接口1/2/3/5/6/7/9/10/11/12/99 + 工具路由
 ```
 
-- **worker**（`app.py` + `face_analysis/` + `hairline/`）：跑真正的算法，**纯本地、无外网依赖**。
-  对 `/api/*` 校验 `X-Internal-Token`（密码在 `worker_config.json` 的 `accept_passwords`）；
-  `/health` 模型就绪才返回 200。监听 **8187**（`./start.sh` 控制开关，`./run_worker.sh` 热重载）。
+- **worker**（`app.py` + `face_analysis/` + `hairline/`）：跑真正的算法，除 ComfyUI/change_hair 走本机
+  回环外无外网依赖。对 `/api/*` 校验 `X-Internal-Token`（密码在 `worker_config.json` 的 `accept_passwords`）；
+  `/health` 模型就绪才返回 200。监听 **8187**（systemd `hair-worker.service`，也可 `./run_worker.sh` 手动起）。
+  另有 worker 本机的工具路由：`/api/swapHair/v1`、`/hairColor/v2`（CORS 代理转发 change_hair:8801）、
+  `/api/v1/redraw`（直接 ComfyUI 重绘）、`/api/v1/debug/*`（免鉴权调试）。
 - **网关**（`gateway/`）：薄反向代理，健康检查/派发/鉴权/把 worker 的 `*_base64` 落盘改成 `*_url`。
   唯一例外是**接口4 在网关本机直接实现**（调外网豆包，不转发 worker）。
 - **图片三选一**：所有接口图片入参 `image_file`/`image_url`/`image_base64` 严格三选一（接口3 是 `marked_image_*`）。
@@ -33,7 +35,10 @@
 | 2 | `results[].image_base64` / `results[].grown_image_base64`(可空) | `results[].image_url` / `results[].grown_image_url` |
 | 3 | `hair_growth_image_base64`(可空) | `hair_growth_image_url` |
 | 5 | `hairline_images[].image_{middle,high,low}_base64` / `grown_image_base64`(可空) | `hairline_images[].image_{middle,high,low}_url` / `grown_image_url` |
-| 7 | `results[].image_base64` / `results[].grown_image_base64`(可空) | `results[].image_url` / `results[].grown_image_url` |
+| 9 | `steps_common.*_base64`、`bisenet|segformer.{hair,closed_region,final_overlay,mask}_mask_base64` 等 | 同名 `*_url` |
+| 10 | `steps_common.*_base64`、`bisenet|segformer.{base_mask,contour,band_overlay,mask}_base64` 等 | 同名 `*_url` |
+| 11 | `steps.{input,baseline,hair_mask,mask_overlay,mask,swap_raw,alpha,final}_base64` | `steps.*_url` |
+| 12 | `steps.{input,final,redraw_band_overlay,redraw_full,redraw_band,redraw_c}_base64` | `steps.*_url` |
 | 4 | （网关本机产出，无图片字段，`features` 为 JSON 字符串） | — |
 
 > 实现建议：递归遍历 data，凡 key 以 `_base64` 结尾就落盘改 `_url`，自动覆盖嵌套/新增字段。
@@ -47,7 +52,7 @@
 
 ---
 
-## 2. 五个接口实现简述
+## 2. 各接口实现简述
 
 ### 接口1 四庭七眼测量 `/api/v1/face/measure`（worker）
 - **做什么**：正面照 → 四庭(顶/上/中/下庭) + 七眼(眼宽/脸宽/间距) 的 cm 与占比、5 个关键点坐标、一张透明底标注 PNG。
@@ -65,10 +70,10 @@
 ### 接口2 C端生发 `/api/v1/hair/grow`（worker）—— 预览 + 生发图
 - **做什么**：正面照 + `gender`(必填) + `hair_style`(必填，逗号分隔多选，如 `1,2,3`) → 指定发际线类型 **N 组**：**预览图**(发际线叠在照片上) + **生发后图**(植发3个月效果)。
 - **怎么实现**（`hairline/`）：移植 head3d——MediaPipe(Tasks) + SegFormer 分割 + 17 锚点射线检测 → 502 点 mesh，
-  按 `face_ext.obj` 的 UV 把发际线贴图渲染到额头(预览)。生发：黑贴图渲染遮罩 → 调本机 **ComfyUI 8182** 的
+  按 `face_ext.obj` 的 UV 把发际线贴图渲染到额头(预览)。原生生发：黑贴图渲染遮罩 → 调本机 **ComfyUI 8188** 的
   `add_hair.json`(Flux-2) 出图。**关键坑**：obj 是重排序，需 `INDEX_MAP_468` 把 MP 序→OBJ 序。
   返回 `results[].image_base64` + `grown_image_base64`。
-- `hair_style` 映射：female 1=ellipse 2=flower 3=heart 4=straight 5=wave 6=bigflower 7=clasicalflower；male 1=ellipse 2=inverse_arc 3=m 4=straight 5=heart 6=Softpetal 7=wave。female 1..5 走「换发型(change_hair)」+Flux-2 重绘管线；female 6/7 与 male 全部走原生发(ComfyUI add_hair)管线。
+- `hair_style` 映射：female 1=ellipse 2=flower 3=heart 4=straight 5=wave 6=bigflower 7=clasicalflower；male 1=ellipse 2=inverse_arc 3=m 4=straight 5=heart 6=Softpetal 7=wave。female 1..5 走「换发型(change_hair)」+Flux-2 重绘管线（`generate_grow_results_swap`，复用接口12 final 的 `_V2_FINAL_DEFAULTS`，长边默认压到 `REDRAW_MAX_SIDE`=1024 再放大回原尺寸）；female 6/7 与 male 全部走原生发(ComfyUI add_hair)管线。可选参数 `flux_model`（切换 Flux unet，.gguf 自动配 UnetLoaderGGUF + 配套 qwen CLIP）、`redraw_max_side`（0=不缩图）。
 
 ### 接口7 C端生发 v2 `/api/v1/hair/grow-v2`（worker）—— 接口2同款，add_hair2 工作流
 - **做什么**：与接口 2 完全一致（正面照 + `gender` + `hair_style` 逗号分隔多选 → N 组预览+生发图）。
@@ -92,20 +97,50 @@
 - **做什么**：入参同接口2（`gender` + 多选 `hair_style` 必填）。对每个选中发型 → `middle`/`high`/`low` 三档发际线叠图 + 生发图 + 首个选中发型的面部中间点坐标。
 - **怎么实现**：复用接口2 的 502 点渲染管线，三档分别用 `hairline_texture[/_high|/_low]` 同名贴图渲染叠图；生发同接口2（ComfyUI inpaint），**黑模板固定取 `hairline_texture_black/`（middle）**，每发型 1 张生发图。`best_hairline_center_point`=眉心 x × 首个选中发型 middle 档发际线 y。
 
+### 接口9 头发遮罩 `/api/v1/head/mask`（worker）
+- **做什么**：人像照 → 头发遮罩 + 全流程分步可视化。
+- **怎么实现**（`face_analysis/head_mask.py`）：MediaPipe 底部分割线（21/68/104/69/108/151/337/299/333/298/251 连线，21/251 水平延伸）→ 线以上为上半区 → BiSeNet 与 SegFormer 双路头发分割、逐列向下填充到分割线得闭合区域（头发+额头）→ 外缘朝 151 内缩 `erode_cm`(默认1.2cm，虹膜标定) → 最终遮罩。返回 `steps_common` + `bisenet`/`segformer` 两组各四张图。
+
+### 接口10 头部外缘膨胀带 `/api/v1/head/band`（worker）
+- **做什么**：在接口9 基准遮罩基础上，沿头部外缘生成一条膨胀带遮罩。
+- **怎么实现**（`face_analysis/head_band.py`）：取基准遮罩外轮廓、去掉贴底分割线段 → 膨胀成总宽 `dilate_cm`(默认2cm) 的带子 → 裁到分割线以上。返回 `base_mask`/`contour`/`band_overlay`/`mask` 分步图。
+
+### 接口11 发际线生发 `/api/v1/hairline/grow`（worker）—— 不含重绘
+- **做什么**：发际线偏高/头发稀少正脸图 + `hairline_id`（= change_hair `hair_id`，如 `chang_tuoyuan`）→ 压低发际线图 + 全步骤可视化。
+- **怎么实现**（`face_analysis/hairline_grow.py`，算法见 `发际线增强算法.md`）：① 接口9 遮罩（`seg_model` 选 bisenet/segformer）→ ② 调 change_hair 生成该发际线类型图（`swap_mode=ext_mask` 把遮罩传给 webui 精确重绘 / `as_is` 用其内部遮罩；`gen_backend` 可换 hairgrow 区域生发 inpaint）→ ③ 严格按遮罩贴回 → ④ 接缝融合 `blend_method`（multiband 默认 / seamless / two_stage / feather / alpha_gradient，可选 Reinhard `color_match`）。返回 `steps.{input,baseline,hair_mask,mask_overlay,mask,swap_raw,alpha,final}`。
+
+### 接口12 发际线带重绘 `/api/v1/hairline/grow_v2[_final[_v2]]`（worker）
+- **做什么**：接口11 的下游重绘阶段——先跑接口11 拿 ④final，再取发际线重绘带（外推 `band_lo_mult×push`~`band_hi_mult×push`，默认 0.5×~1.5×）作遮罩，用 **Flux-2（ComfyUI，`0716add-hair-api.json`，reference-latent 保色）** 重绘，产出两版：`redraw_full`（整帧美颜+整帧重绘）与 `redraw_band`（band 内加发、band 外 final 结构 + `beauty_alpha` 融入全脸美颜）。
+- **三个变体**：`grow_v2` 全参数暴露（接口11 参数 + `comfyui_prompt`/`beauty_alpha`/`band_lo_mult`/`band_hi_mult`）；`grow_v2_final` / `grow_v2_final_v2` 精简生产版——仅图片 + `hairline_id`，其余固化 `_V2_FINAL_DEFAULTS`（push=0.8cm / two_stage / color_match=关 / beauty_alpha=0.6 等），两者后端计算完全一致（同一次输出含 A/B 两版），差异只是测试页展示哪版。接口2 女性 1..5 的生发图即复用此管线。
+- ⚠️ 依赖 ComfyUI(:8188)；重绘失败在 `data.redraw.c_error` 报告。
+
+### 接口99 人脸特殊点 `/api/v1/face/special-points`（worker）
+- **做什么**：人脸照 → 60 个固定编号 MediaPipe 关键点（6 组：eyebrow/eye/mouth/nose_midline/cheek/face_edge）+ 5 个发际线特殊点，原图像素坐标 JSON（字段 `<组名>_<点ID>`，如 `eyebrow_107`）。
+- **怎么实现**（`face_analysis/special_points.py`）：MediaPipe 单例取关键点；发际线点=接口1 方案B 的 BiSeNet 头发 mask 上沿指定关键点方向（如 151→10）射线步进取首个头发像素，双射线的（right/right_right/left/left_left）取中点。无图片字段，网关纯盲转发。
+- 测试页：`static/test_interface99.html`（canvas 可视化 + JSON，worker 本机直连）。
+
 ---
 
 ## 3. 部署 / 环境要点
 
-**worker（GPU 机）**
-- Python **3.12**（系统 3.13 无 mediapipe/torch wheel）；venv 在 `./venv`，依赖 `requirements.txt`。
-- `numpy<2`(1.26.4)，`scikit-image==0.24.0`（**别升 0.25+，会顶 numpy≥2 顶崩 mediapipe**）。
-- ⚠️ 本机 **RTX 5090(sm_120)**，pinned `torch 2.2.2(cu121)` 只到 sm_90 → GPU 算子报 "no kernel image"，
-  代码已自动**回退 CPU**（BiSeNet/SegFormer CPU 推理可用）。要用 5090 GPU 需换 torch cu128(≥2.7)。
+**worker（GPU 机，本机 = gpu_worker 角色）**
+- Python **3.10.12**（本机 venv 在 `./venv`）；`numpy<2`(1.26.4)，`scikit-image==0.24.0`
+  （**别升 0.25+，会顶 numpy≥2 顶崩 mediapipe**）。
+- 本机 **RTX 4090**：venv 实装 `torch 2.7.1+cu128`，CUDA 可用（BiSeNet/SegFormer GPU 推理）。
+  `requirements.txt` 里 pinned 的 `torch 2.2.2(cu121)` 及 5090 注释是旧机（sm_120 无 cu121 kernel、
+  自动回退 CPU）的记录，本机以 venv 实际版本为准。
 - 模型权重/字体见 [`../OFFLINE_ASSETS.md`](../OFFLINE_ASSETS.md)；BiSeNet/SegFormer/face_landmarker.task 本地。
-- 生发接口依赖本机 **ComfyUI(8188)**（Flux-2，它自带支持 5090 的 torch）；worker 只调其 HTTP API，不跑 Flux。
-  ComfyUI 开了 **HTTP Basic Auth**（user `admin` + 密码）；密码放 `password.txt`(不入 git) /
-  `worker_config.json.comfyui_password` / 环境变量 `COMFYUI_PASSWORD`，URL 用 `COMFYUI_URL`。
-- `worker_config.json`(不入 git)：`accept_passwords`(鉴权) + 鉴权头 `X-Internal-Token`。
+- 生发接口依赖本机 **ComfyUI(8188)**（Flux-2，systemd `comfyui.service`，`--cache-classic --fast`）；
+  worker 只调其 HTTP API，不跑 Flux。ComfyUI 开了 **HTTP Basic Auth**（user `admin` + 密码）；
+  密码放 `password.txt`(不入 git) / `worker_config.json.comfyui_password` / 环境变量 `COMFYUI_PASSWORD`，
+  URL 用 `COMFYUI_URL`。默认模型 flux-2-klein-9b Q4_K_M GGUF（接口2 `flux_model` 参数可切）。
+- 换发型依赖本机 **change_hair**（`/home/ubuntu/change_hair`，三进程 webui:57860(sdwebui) →
+  photo_service:32678(py310/kohya) → hair_service_sd:8801(my_hair)，`start_all.sh start|stop|status`，
+  也有 systemd `change_hair-{webui,photo,hair}.service`）。不跑时接口2女1..5、接口11/12、
+  swapHair/hairColor 代理不可用。
+- `worker_config.json`(不入 git)：`accept_passwords`(鉴权) + `comfyui_password`；鉴权头 `X-Internal-Token`。
+- systemd 单元：`hair-worker.service`(8187) / `comfyui.service`(8188)，仓库根有副本；手动启停用
+  `./run_worker.sh` / `./stop_worker.sh`。
 
 **网关机**
 - 很轻：FastAPI/uvicorn/httpx + **接口4 的 `volcengine-python-sdk[ark]`**（或直接 httpx 调，OpenAI 兼容）。