hair/docs/网关待改动.md

网关侧改动清单（worker 近期变更引发）

给网关开发：以下是 worker/契约近期变化里与网关有关的点。标 ✅ 的我已在本仓库 gateway/ 改好（你 review/拉取即可）；标 🔲 的是建议你确认或改。功能必需只有第 1 条。

---

1. ✅【功能必需】base64→URL 落盘扩展名按内容嗅探（支持 JPG）

背景：接口 2/3/5 的返回图改成了 JPG（体积约小 9×），接口 1 标注图仍是 PNG（含透明）。 网关把 *_base64 落盘时若硬编码 .png，JPG 会被存成 .png（内容是 JPG、扩展名错）。

改动（gateway/forward.py 的 rewrite_base64_to_url，已改）：

# 原：filename = f"{uuid.uuid4().hex}.png"
ext = "png" if img_bytes[:8] == b"\x89PNG\r\n\x1a\n" else "jpg"   # 按内容嗅探
filename = f"{uuid.uuid4().hex}.{ext}"

这样接口1 存 .png、接口2/3/5 存 .jpg，对外 URL 后缀也就正确。若你的网关是独立部署/独立代码，按上面这两行改一下即可。

---

2. 🔲【建议】生发接口超时调大

接口 2（一次 N 张 Flux，~18s）/ 3（~6s） 经 ComfyUI 同步出图较慢。 gateway/config.json 的 dispatch.request_timeout_seconds 建议 ≥ 120，否则网关会先超时换 worker 重试。

---

3. 🔲【确认】base64→URL 通用改写仍覆盖这些场景

• 数组里的图片字段：接口2 results[].image_base64 / results[].grown_image_base64、 接口5 hairline_images[].image_base64 在数组元素内——改写要递归进数组（你现有的递归实现已覆盖）。
• 可空字段：接口2/3 的生发图（ComfyUI 没起/失败时）*_base64 为 null → 保留 null、不落盘。

---

4. 🔲【可选·仅影响 /docs】OpenAPI 表单声明

纯文档展示，不影响转发功能（网关是盲转发）。若想让网关 /docs 准确：

• 接口2 /hair/grow、接口5 /hairline/generate 入参新增必填 gender（male/female）。
• 接口3 /hair/grow-b 入参只剩 marked_image_*（已去掉 original_image_*）。
• （gateway/app.py 里的 _*_FORMS 字典当前未被路由引用，所以不改也不影响实际行为。）

---

已经做好、无需再动的

• 接口4 在网关本机实现（调豆包，不转发 worker）——已完成；config 里配 ark。
• 接口4 业务错误 HTTP 状态已统一为 200（与其余接口一致）。
• 接口3 去 original / best_hairline——网关盲转发，无需改（映射表里也没有 best_hairline）。

---

对外字段映射总表见 实现说明.md §1；契约以 接口文档.md 为准。