AI 玩具专利生成工作流 · 编排逻辑

0 · 目录

1 · 顶层一图：4 阶段串行 + 平行视频

整个工作流是一条带 gate 的状态机，一个 GenSession 串起所有阶段的产物。横向四个图片包严格串行，包内单图4 并发 + 拓扑排序，文案 / 视频在 characterSpec 锁定后即可触发，但前端按"四包完成后再开"做 UX 引导。

┌─────────── A. 输入入口 ───────────┐
│  idea   POST /api/generate         │──┐
│  remix  POST /api/projects/from-…  │  │  → GenSession 落盘（data/sessions/）
│  replicate / extend ↑              │  │
└────────────────────────────────────┘  │
                                        ▼
                        ┌──── B. 九宫格选中 ────┐
                        │ POST /api/select      │
                        │ 选中图复制到 selected/│
                        └───────────┬───────────┘
                                    ▼
                ┌──── C. 角色锁定（gate #1）────┐
                │ POST /api/character/lock      │  → CharacterSpec
                │   (replicate/extend 走 strict)│  + cleanReferenceImageUrl
                └───────────┬──────────────────┘     (L1 白底净化锚图)
                            ▼
       ┌────────── D. 四个图片包（严格串行）──────────┐
       │  ① patent ▶ ② accessories ▶ ③ production ▶  │
       │      ④ marketing                              │
       │   gate #2：前一包 status='complete' 才解锁   │
       │   gate #3：同 session+image+kind 并发锁      │
       │   包内：拓扑排序 + 4 并发 + 增量回写         │
       └───────────┬──────────────────────────────────┘
                   ▼  （前端 UX：四包齐了再开下一段）
       ┌────────── E. 文案 18 模板 ──────────┐
       │  POST /api/text/generate            │
       │  gate：characterSpec 必须存在        │
       └─────────────────────────────────────┘
       ┌────────── F. 视频 5 模板（Seedance）─────────┐
       │  POST /api/video/generate（异步任务）         │
       │  GET  /api/video/status/[taskId]（轮询 15s）  │
       │  锚图优先级：mkt_white_front → patent_front   │
       │              → cleanReferenceImageUrl → L0    │
       └──────────────────────────────────────────────┘
                   ▼
            导出（已落地：ZIP；路线图：PDF）

2 · 数据真源与冻结版本

各包模板规模与根锚

规模来源 PACK_TEMPLATE_SUMMARY（src/lib/templates.ts:1101）。宣发包末尾 5 条 video_* 是分镜板（图片），与 VIDEO_TEMPLATES 的真实视频任务同名但不同源。

3 · 阶段 A：输入 → 候选图

3.1 三种输入模式（ProjectInputMode）

3.2 上传 role → 专利槽位映射（extend 模式）

src/app/api/projects/from-upload/route.ts:19

命中预填槽的 pack asset 不会调 GPT，直接复用上传 URL（packGenerator.ts:326-356）。

3.3 Provider 选择

// src/lib/providers.ts:10
export function detectProvider(): Provider {
  return process.env.OPENAI_API_KEY ? 'gpt' : 'mock';
}

• gpt：图片生图走 POST {GPT_API_BASE}/images/generations 或 /images/edits；文本结构化走 /responses + format: json_object
• mock：返回 SVG 占位图（笑脸 + 渐变背景），仅用于跑通流程，不能生产用
• 视频不 mock：Seedance 缺 Key 时直接 503

4 · 阶段 B：九宫格选中

POST /api/select（src/app/api/select/route.ts）支持 action: 'select' | 'reject' | 'reset'。select 时把图从 data/generated/ 复制到 data/selected/ 并把新 URL 写回 img.meta.selectedUrl。

前端键盘约定（src/components/PromptPanel.tsx）：1-9 选中，Shift+1-9 打叉。被打叉的图保留可见，不会进入后续阶段，但仍在 audit DB 留痕。

5 · 阶段 C：角色锁定（CharacterSpec + L1 锚图）

5.1 两条路径

5.2 CharacterSpec 字段（src/lib/types.ts:76）

15 个语义字段 + 3 个图像引用 + lockedAt。详见 CHARACTER_SPEC_FIELDS（templates.ts:58）。关键三项：

• sourceImageId / sourceImageUrl — L0（用户选中或上传的图）
• cleanReferenceImageUrl — L1（净化后的白底锚图，是后续所有 pack 生成的根锚）
• negativePrompt — 写入每张 pack 图的 prompt 后缀，防角色漂移

5.3 strict 净化的关键约束（节选）

src/lib/packGenerator.ts:171-200

• 多宫格 / 品牌手册 / 包装展示 → 只抽取最大最清楚的单一主角色，不保留版式 / 分割线 / 标题 / 包装平铺
• 必须保留：玩具本体的设计标识、衣服图案、帽标、面罩声波图案等用户上传的原创品牌符号
• 背景纯白，去水印 / 价格 / 网页 UI
• 不改五官、配色、配件位置、材质纹理

6 · 阶段 D：四个图片包串行

6.1 三道 gate

6.2 包内编排（generateAssetPack，packGenerator.ts:276）

sortTemplatesByAnchor(getPackTemplates(kind))   // 拓扑排序
        │
        ▼
取/建 CharacterSpec → cleanupCharacterAnchor  // 兜底确保 L1 存在
        │
        ▼
existingPack 合并：从断点续生（按 templateId 去重）
        │
        ▼
takeReadyTemplate()  // 依赖已就绪的模板进入候选
        │
        ▼
inFlight ≤ PACK_ASSET_CONCURRENCY (=4)        // 并发槽
        │
        ▼
对每张模板：
  · 若命中 preFilledSlot → 直接复用上传图，不调 GPT
  · 否则 generateAssetImage()：
      · anchorImageUrl = anchorAsset.url   // L3：基于已生成根模板
                       ?? L1.cleanReferenceImageUrl  // L2：用净化锚图
                       ?? L0.url
      · GPT images/edits 真正的图生图（读 anchor 字节 → multipart）
      · data: 开头则落盘到 data/packs/{packId}_{assetId}.{ext}
        │
        ▼
async onProgress(pack) → persistPackProgress (每张都回写 session JSON)
        │
        ▼
全部就绪后 pack.status = 'complete'，写 ExportManifest 到 data/exports/

6.3 派生层级（ToyAsset.derivationLevel）

代码里 derivationLevel 只被赋值 2（无 anchorAsset）或 3（有 anchorAsset）。0/1 出现在类型定义中，运行时由 L0 图片本身和 cleanReferenceImageUrl 隐式承担。

6.4 单张重做（POST /api/assets/[assetId]/regenerate）

6.5 增量回写与断点续跑

onProgress 在每张生成完成后 reload session JSON、用最新 pack 替换旧版本（按 kind + sourceImageId 匹配），再写回。generateAssetPack 启动时会取出未完成的 existingPack，按已落地的 templateId 跳过、只生成剩余项 → 断网或失败可重试。

7 · 阶段 E：文案模板（18 条）

7.1 路由

POST /api/text/generate，body {sessionId, templateIds?}。后端唯一 gate：session.characterSpec 必须存在（text/generate/route.ts:18），不强制四包完成。

7.2 实现

src/lib/textGenerator.ts

• 未传 templateIds 时生成全部 18 条；传了则只生成子集
• 一次 GPT /responses JSON 调用，要求返回 {items: [{templateId, content}]}
• 未配 GPT Key 时每条用 fallbackContent() 生成占位稿，标注"未配置文本模型时生成占位稿"
• 结果按 templateId 去重后写入 session.textAssets[]

7.3 18 条文案模板按 kind 分组

8 · 阶段 F：视频任务（Seedance）

8.1 五条视频模板（VIDEO_TEMPLATES）

8.2 提交 + 轮询

POST /api/video/generate              GET /api/video/status/[taskId]
       │                                       ▲
       ▼                                       │  前端每 15 s 轮询
generateSeedanceVideo()                        │  最多 30 次
   ↓                                           │
POST {SEEDANCE_API_BASE}                       │
   /contents/generations/tasks                 │
   ↓ task_id, status='submitted'               │
保存到 session.videoTasks[]      ──────────────┘
       │
       ▼
status='succeeded' 时 videoUrl 用 saveRemoteVideo() 拉到 data/videos/，
返回 /api/video-file/{filename} 本地路径

8.3 锚图优先级（page.tsx:580-589）

1. mkt_white_front — 宣发白底正面图（最稳定）
2. patent_front — 专利主视图
3. characterSpec.cleanReferenceImageUrl — L1 净化锚图
4. 当前选中意向图 L0

8.4 PUBLIC_APP_URL 注入

Seedance 需要从公网拉参考图，所以 publicUrlOrUndefined() 把 /api/img/... 用 PUBLIC_APP_URL（生产 = https://ai-toy.kang-kang.com）转成绝对 URL。localhost / 127.0.0.1 / 私有 IP 一律丢弃。

8.5 视频任务去重

每次新提交按 templateId 去重覆盖（video/generate/route.ts:46），保证 5 个模板各最多一个最新任务。fix: dedupe suffixed video tasks（7abbb7d）专门处理 video_turntable_60s 等带后缀的真实成片回流到默认模板卡。

9 · 横切：持久化、审计、鉴权、轮询

9.1 八个存储桶（src/lib/storage.ts）

9.2 审计：SQLite + 兜底 JSONL

src/lib/auditDb.ts。每个 API 路由的关键节点（started / completed / failed / blocked / saved）都调 recordEvent()，落到 data/app.db。Docker 镜像内置 sqlite3；非 Docker 本地缺 sqlite3 时降级写 data/audit-fallback.jsonl，不阻断流程。

每张图也通过 upsertImageAsset() 写入 image_assets 表，包含 bucket / width / height / sizeBytes / kind / templateId / origin，是 /api/gallery/[sessionId] 的真源。

9.3 鉴权（src/middleware.ts）

• Cookie 名：WEB_AUTH_COOKIE_NAME（默认 ai_toy_session）
• HMAC-SHA256 签名 body.signature，body 是 base64url 编码的 {u, exp}
• 公开路径：/login / /_next/ / /api/auth/ / /api/img/ / /favicon.ico / /robots.txt / /sitemap.xml
• 未鉴权：HTML 路径 302 到 /login?next=...；非 HTML API 返回 401 {error: 'unauthorized'}
• /api/img/* 故意保持公开 —— Seedance 必须能从公网拉参考图

9.4 轮询节奏（前端）

10 · 编排约束与"规约 vs 实现"差异

11 · 已落地导出 / 未落地路线

11.1 已落地

• ExportManifest JSON：每包生成结束自动写 data/exports/{sessionId}_{kind}_{version}_manifest.json，含 files[]（asset_id, templateId, filename, url, anchor, derivation, checklist）
• ZIP 下载：GET /api/packs/download?sessionId=&kind=，纯 Node Buffer 拼装 ZIP（含 CRC32），文件名 {characterSlug}_{kind}_{N}张.zip，按 templateId 顺序编号 01_xxx.png

11.2 未落地（RULES.md 路线）

• PNG 高清导出 + PDF 合订：ExportManifest 已预留 exportTargets: ['zip', 'pdf', 'manifest-json']，只实现了 zip + manifest，pdf 未生成
• Seedance 任务轮询 UI：现状是被动 15s 间隔静默 refresh，没有进度条 / 失败重试按钮的完整 UI

12 · 关键 API 速查

附录 · 文件锚点

— 文档生成基于 commit e519627。结构性改动后请重跑 npm run docs:orchestration（如已配脚本）或重新执行 docs/orchestration.html 的生成命令。