# 人衣图生成 admin 工具 — 现状与待办

独立于主线换装跳舞直播间任务序列（T1-T39，见 `dev-plan*.md`）之外的一个
standalone 工具：`admin-dressgen.html`（新建任务）+
`admin-dressgenlist.html`（任务列表）+ `admin-dressgendetail.html`（任务
详情）。输入人物定妆照（全身/脸部 × 正/侧/背，传几张算几张，至少 1
张）+ 1 张新衣服图，依次生成这位人物穿新衣服的全身正/侧/背 3 张图。
2026-09-03 当天从头做到这里，记录一下现状，避免下次接着做时重新踩一遍
已经踩过的坑。

---

## 1. 已完成

- **异步任务队列**（不是同步阻塞接口——最早的同步版本真的把前端代理
  拖到 502 超时过一次）：`POST /api/admin/dressgen` 立即返回
  `status:"queued"` 的任务行，`runDressGenViews()`（server.js）在响应
  发出后 fire-and-forget 依次（不并发）跑 3 个视角，每一步都写回
  `dressGenRecords`（`dress-gen.json`），前端轮询 `GET
  /api/admin/dressgen/:id` 看进度。
- **重试**：`POST /api/admin/dressgen/:id/retry`（整体重试，只重跑没成
  功的视角）、`POST /api/admin/dressgen/:id/retry/:view`（单张重试，
  可选带 `{prompt}` 覆盖那一张的 prompt）——都复用任务自己存的图片/
  prompt，不用重新上传、不用重新填 prompt。两个重试接口都额外接受可选
  `{provider}` 覆盖，手动把某个任务/某一张换供应商重跑。
- **两个供应商都已接入并验证成功**：
  - GPT Image 2（万界方舟）：`https://maas-openapi.wanjiedata.com
    /api/v1/images/edits`，`model:"GPT Image 2"`（带空格，写错会被 WAF
    拦 410 或报 unauthorized），`rejectUnauthorized:false`（万界这个
    host 的证书链在这台机器上验证不过，`-k`），300s 超时，60-180秒/张。
  - Seedream v4（wavespeed.ai 的 `bytedance/seedream-v4/edit`）：上传
    `POST /api/v3/media/upload/binary` → 提交 `POST /api/v3/{model}` →
    轮询 `GET /api/v3/predictions/{id}/result`，约 30 秒/张，$0.027/次，
    无 TLS 证书问题、无内容审核。`.env` 已配置 `WAVESPEED_API_KEY`。
  - **默认行为（2026-09-03 当天二次确认的产品决策，覆盖了更早的"不做
    自动切换"那版）**：新任务默认用 image2；某一视角 image2 失败（不
    区分技术故障还是审核拒绝）→ 自动改用 wavespeed 重试一次，成功的话
    该视角 `viewProvider[view]` 记为 `"wavespeed"`，前端详情页会显示
    "实际使用: Seedream v4"。手动重试接口仍可传 `{provider}` 强制指定。
    **这条决策的取舍写在 `server.js` 里 `WAVESPEED_API_KEY` 声明上方的
    注释里，包含为什么会改主意——下次改这块之前先看那段注释。**
- **17 个自动化测试全过**（`dressgen-generate.test.js`：任务创建即时
  返回、轮询到终态、per-view 自定义 prompt、单视角失败不拖累其它两个、
  整体/单视角重试（含 provider 覆盖）、非法路径防护、wavespeed 供应商
  路径、image2→wavespeed 自动降级等）。
- **前端拆成三个页面**（原来是"新建+列表"揉在一张页面里，"详情"按钮在
  宽表格右侧、窄窗口下需要横向滚动才能看到，容易被当成"消失了"）：
  - `admin-dressgen.html`：新建任务表单，提交后跳到该任务的详情页。
  - `admin-dressgenlist.html`：任务列表，操作列（详情/重试/删除）用
    `position: sticky; right: 0` 钉住，横向滚动时始终可见；所有缩略图
    （人物参考图/衣服图/生成结果）点击可放大预览（一个简单的
    lightbox，点哪张放大哪张，点遮罩关闭）。
  - `admin-dressgendetail.html`：单任务详情（原 `admin-dressgen-task.
    html` 改名），生成结果图也支持点击放大，每张视角显示"实际使用"的
    供应商。
  - 其它 admin 页面导航栏的"人衣图生成"链接都改指向
    `admin-dressgenlist.html`（列表作为默认落地页，列表页右上角
    "+新建任务" 去创建页）。

## 2. 待办

- [ ] 生成结果目前是完全独立的列表（`dress-gen.json`），不会进
      `characters.json`/`garments.json`（人物库/衣服库）。**现状确认
      （2026-09-03）：人物库现在每个人物只有单张 `imageUrl`，不是"一个
      人物对应多张可复用资产图"的模型**——`characters.json` 唯一一条
      种子记录也只有一个 `imageUrl` 字段，没有相册/资产列表这回事。
      "存为新人物"要做成什么形态（人物库本身要不要先改成多资产模型、
      用 dressgen 的哪张视角图当定妆照等）还没定，做之前需要先对齐。

## 3. 已完成（第二批，2026-09-03 当天晚些时候）

- **任务僵死检测**：`server.js` 的 `resumeDressgenTasks()`，进程启动时
  （`resumeGenerations()`/`resumeDressupGenerations()` 旁边）扫一遍
  `dressGenRecords`，把仍停在 `queued`/`generating` 的视角标记为
  `failed`（错误信息"进程重启，任务丢失，请点重试"，前端详情页会照常
  显示），并按 T8 `generationJobs` 同款逻辑重算整条任务的 `status`。
  没有可恢复的 in-flight 请求 id（image2/wavespeed 调用是
  `runDressGenViews` 里直接 await 的 HTTP 往返，进程一退什么都不剩），
  所以是标失败而不是真的续跑——用户点"重试"即可，跟真实生成失败的
  体验一致。测试：`dressgen-generate.test.js` 里专门起了一个独立
  cwd/mock（mock 故意不响应，制造一个真实卡在 generating 的视角），
  `SIGKILL` 模拟崩溃，重新起一个指向同一份 `dress-gen.json` 的进程，
  断言恢复后的状态。
- **列表分页**：`GET /api/admin/dressgen` 现在接受 `?page=&pageSize=`
  （默认 `pageSize=20`，上限 100），按 `createdAt` 倒序（最新的在前）
  切片，返回 `{items, total, page, pageSize}`（之前是裸数组，前端自己
  `.reverse()`——这是个破坏性的响应格式变更，前端和测试已同步改掉）。
  `admin-dressgenlist.html` 加了"上一页/下一页"，操作列还是 sticky，
  互不冲突。

## 3. 相关文件

- `server.js`：`IMAGE2_*`/`WAVESPEED_*` 常量、`generateDressImage`/
  `generateDressImageViaImage2`/`generateDressImageViaWavespeed`/
  `runDressGenViews`（含自动降级分支）/`dressGenImageAbsPaths`、
  `/api/admin/dressgen*` 路由
- `dressup-store.js`：`dressGenRecords`
- `dress-gen.json`：数据文件
- `admin-dressgen.html`（新建）/ `admin-dressgenlist.html`（列表）/
  `admin-dressgendetail.html`（详情）：前端
- `dressgen-generate.test.js`：测试
- `.env`：`IMAGE2_API_KEY` / `IMAGE2_API_BASE` / `WAVESPEED_API_KEY` /
  `WAVESPEED_API_BASE`