From a86125246e182cbd22884a4b26c979ea397fe14f Mon Sep 17 00:00:00 2001
From: xsl <youmiss@163.com>
Date: Mon, 15 Jun 2026 23:44:41 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=BD=91=E5=85=B3=E4=BE=A7=E6=94=B9?=
 =?UTF-8?q?=E5=8A=A8=E6=B8=85=E5=8D=95(JPG=E8=90=BD=E7=9B=98=E6=89=A9?=
 =?UTF-8?q?=E5=B1=95=E5=90=8D=E5=97=85=E6=8E=A2=E7=AD=89)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

汇总 worker 近期变更里与网关有关的点供网关侧应用：
- [功能必需] base64→url 落盘按内容嗅探扩展名(PNG/JPG)，因接口2/3/5 改 JPG(已在 forward.py 改)
- [建议] 生发接口超时≥120s
- [确认] 递归改写覆盖数组内字段/可空 null
- [可选] OpenAPI 表单 gender/grow-b 声明
- 已完成项：接口4 网关实现/200状态/接口3去original

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/网关待改动.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 docs/网关待改动.md

diff --git a/docs/网关待改动.md b/docs/网关待改动.md
new file mode 100644
index 0000000..d72ee0b
--- /dev/null
+++ b/docs/网关待改动.md
@@ -0,0 +1,55 @@
+# 网关侧改动清单（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`，已改）：
+```python
+# 原：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`](实现说明.md) §1；契约以 [`接口文档.md`](接口文档.md) 为准。