Genarrative/docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md

拼图填表式创作流程改造 2026-04-29

背景

拼图创作入口不再使用 Agent 对话收集题材锚点。新流程让玩家填写作品名称、作品描述、画面描述三类信息，其中画面描述只服务首关画面生成与关卡画面语义，不再作为作品详情页的作品描述。画面描述支持上传参考图。玩家确认后直接进入草稿生成进度页，后续草稿生成、首图生成、正式图选择、结果页编辑和发布沿用现有后端编排。

入口表单

2026-04-30 初始表单草稿保存补充

1. 玩家在创作页点击“拼图”入口时，前端必须立即创建一个新的拼图 Agent session，并同步生成一条 publicationStatus = draft 的拼图作品卡；此时不触发 compile_puzzle_draft，不生成图片，不进入生成进度页。

2. 新 session 的 seedText 允许为空；SpacetimeDB 侧用空锚点和空表单草稿初始化，不得把默认题材文案写入玩家草稿字段。

3. 初始表单输入自动保存到 session 的 draft_json 与 puzzle_work_profile 投影。保存字段只包含 workTitle、workDescription、pictureDescription、可推断标签和一个 generationStatus = idle 的默认关卡；草稿设置阶段默认关卡名称必须为空，不得写入“第一关”“第1关”或作品名称作为默认值。参考图只保存在当前前端会话内，不落入 SpacetimeDB。

4. 玩家在生成草稿前退出，再次从创作中心点击这条拼图草稿时，必须恢复到填表页，并回填之前自动保存的作品名称、作品描述和画面描述；只有执行 compile_puzzle_draft 且生成结果页草稿后，草稿入口才进入结果页。

5. 表单自动保存走 save_puzzle_form_draft action，不消耗陶泥币，不生成图片，不改变 stage = collecting_anchors；生成草稿按钮仍单独触发 compile_puzzle_draft 并进入进度页。

6. 点击拼图入口始终创建新草稿，不复用上一次未完成 session；恢复旧草稿只通过“我的创作”中的草稿卡进入。

7. 若 Maincloud 仍运行旧 wasm，缺少 save_puzzle_form_draft procedure，前端提交生成或生成失败页重试时不得继续复用空 seedText 的表单 session，必须用当前表单 payload 新建带真实 seed 的 session 再执行 compile_puzzle_draft。

8. api-server 也要兼容旧 wasm：save_puzzle_form_draft 缺失时，自动保存 action 降级返回当前 session；compile_puzzle_draft 前置保存缺失且当前 session 为空 seed 时，创建一条带表单 seed 的替代 session 后继续编译，避免再次暴露 No such procedure。

9. 正式修复仍是发布最新 SpacetimeDB wasm。当前 Maincloud xushi-p4wfr 的迁移操作员表为空，但旧库引导密钥来自旧 wasm，本次临时生成的新引导密钥无法授权导出迁移，需使用已有迁移操作员 token 或数据库 owner 重新授权后发布；禁止为绕过冲突直接清库，除非明确接受数据丢失。

10. 作品名称为必填字段，保存到 workTitle，兼容写入旧 seedText，同时作为作品级 workTitle 的真相源。

11. 作品描述为必填字段，保存到 workDescription，作为作品详情页、作品列表和发布资料中的 summary 真相源。

12. 画面描述为必填字段，保存到 pictureDescription，只作为首关画面生成 prompt、首关 pictureDescription 和关卡命名输入，不再覆盖作品描述。

13. 参考图为可选字段，保存到 referenceImageSrc。表单支持本地图片上传为 Data URL；草稿首图生成时直接传入现有拼图图生图接口。

14. 表单确认后前端先创建拼图 session，再立即执行 compile_puzzle_draft，并传入 promptText = pictureDescription、referenceImageSrc。

15. 表单提交 payload 需要在前端创作流程中暂存，生成进度页失败重试时必须继续携带同一份作品名称、作品描述、画面描述与参考图。

16. 生成进度页的“当前拼图信息”必须优先读取这份表单 payload，而不是读取 session 中旧 Agent 锚点或编译后的关卡名，避免用户确认后看到的标题、作品描述、画面描述发生漂移。

17. compile_puzzle_draft action 必须显式携带 workTitle、workDescription、pictureDescription、promptText 与 referenceImageSrc。seedText 只作为 SpacetimeDB 旧表结构兼容载体，不能成为前端生成页展示和失败重试的唯一来源。

18. 入口不再展示拼图 Agent 聊天气泡、快捷补齐或多锚点卡片；新建拼图时必须清空旧 session，只有从当前生成进度页返回表单时保留本轮内容。

锚点映射

拼图模式锚点收口为三个玩家输入源：

新字段	落地字段	说明
作品名称	themePromise.value、workTitle、旧 levelName 兼容字段、creatorIntent.themePromise	作为作品名称与题材承诺真相源
作品描述	workDescription、旧 summary 兼容字段	作为作品详情页描述、列表描述和发布描述真相源
画面描述	visualSubject.value、levels[0].pictureDescription、首图 promptText	作为首关画面主体、首图生成 prompt 和首关关卡命名输入

兼容旧结构时仍保留 visualMood、compositionHooks、tagsAndForbidden 字段，但它们不再由 Agent 问答收集：

1. visualMood 固定标记为系统推断，值为“清晰、适合拼图切块”。
2. compositionHooks 固定标记为系统推断，值为“主体轮廓、色块分区、局部细节”。
3. tagsAndForbidden 根据拼图标题和画面描述生成 3 到 6 个题材标签；禁忌只保留通用图像约束，不写入 UI。

生成进度页的“当前拼图信息”只展示玩家输入锚点：作品名称、作品描述、画面描述。题材标签仅作为草稿结果页内容展示，不在进度页混入旧五锚点结构。

草稿数据结构

拼图草稿从单关卡字段升级为作品级信息与关卡列表并存：

1. PuzzleResultDraft.workTitle：作品名称，旧 levelName 只作为兼容字段同步为当前主关卡名称或作品名称。
2. PuzzleResultDraft.workDescription：作品描述，旧 summary 只作为兼容字段同步为作品描述。
3. PuzzleResultDraft.themeTags：作品标签，仍限制 3 到 6 个。
4. PuzzleResultDraft.levels[]：关卡列表。每个关卡包含 levelId、levelName、pictureDescription、candidates、selectedCandidateId、coverImageSrc、coverAssetId、generationStatus。
5. 首次草稿生成时必须创建一个默认关卡，levelId = puzzle-level-1，pictureDescription = 表单画面描述，草稿设置阶段 levelName 为空；首图生成后可由后端根据画面描述和图片语义生成关卡名称并写入该关卡。
6. 关卡名称由后端基于画面描述和图片语义输入生成；无可用语义时按题材标签与序号兜底，禁止继续直接使用作品名称作为关卡名称。
7. 旧草稿或旧作品缺少 levels 时，读取层必须由旧 levelName、summary、coverImageSrc、candidates 补出一个兼容关卡，避免历史草稿无法打开。

后端编译

1. CreatePuzzleAgentSessionRequest 新增 workTitle、workDescription、pictureDescription 与 referenceImageSrc，但不改 SpacetimeDB 表结构。
2. api-server 创建 session 时把作品名称、作品描述和画面描述合成 seedText 传入 SpacetimeDB；SpacetimeDB reducer 只做确定性锚点生成，不接触图片或外部服务。
3. compile_puzzle_draft_with_initial_cover 新增首图 prompt 和参考图参数。若前端传入画面描述，则首图生成直接使用这段文本；若传入参考图，则走现有 DashScope 图生图链路；生成结果写入默认第一关。
4. 首图文生图 prompt 由 api-server 拼接固定拼图约束后统一压缩到 500 字符以内，避免玩家长画面描述触发 DashScope 参数非法；进度页和结果页仍展示玩家原始画面描述，不展示压缩后的内部 prompt。
5. 图片生成仍在 api-server 内完成，遵守 SpacetimeDB reducer 不做网络 I/O 的约束。
6. 参考图以 Data URL 进入 POST /api/runtime/puzzle/agent/sessions 和 POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions，这两条路由必须单独放宽 JSON body 上限；不要放大全局默认 body limit。
7. 前端仍应优先压缩参考图；后端 body 上限只用于容纳合理尺寸的单张参考图，超大原图不应直接落入 SpacetimeDB 或作为作品字段持久化。
8. 作品更新接口 PUT /api/runtime/puzzle/works/{profileId} 必须支持作品信息和关卡列表一起写入，前端自动保存不得只写旧单关字段。
9. StartPuzzleRunRequest 新增可选 levelId。详情页或草稿结果页单独体验某关时传入目标关卡，后端从作品/草稿的 levels 中选取该关卡生成运行态。
10. ExecutePuzzleAgentActionRequest 必须保留 pictureDescription 字段。表单直达生成时，compile_puzzle_draft 优先用 pictureDescription 作为首图 prompt，再回退到旧 promptText；避免生成页展示的是玩家画面描述，但后端实际用作品名称或旧摘要出图。
11. compile_puzzle_draft 中的图片上游失败不得映射成 400 BAD_REQUEST。DashScope 返回 InvalidParameter 或任务失败时，api-server 统一按 502 UPSTREAM_ERROR 暴露，并在 details.message 中保留“拼图图片生成失败：...”的业务原因，避免生成页只显示“请求参数不合法”。
12. compile_puzzle_draft 前置陶泥币预扣失败不得映射成 400 BAD_REQUEST。余额不足返回 409 CONFLICT，SpacetimeDB procedure 不可用、绑定不匹配、钱包服务异常等统一按 502 UPSTREAM_ERROR 暴露，并在 details.message 中保留真实钱包错误。
13. 生成拼图作品草稿动作涉及的表单 seed prompt 与首图 prompt 来源选择统一收口在 server-rs/crates/api-server/src/prompt/puzzle/draft.rs；puzzle.rs 只负责调用 SpacetimeDB、计费、图片服务和持久化，不再直接拼草稿 prompt 文本。

结果页

拼图草稿结果页分为两个 Tab：

1. 拼图关卡列表：默认展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、生成或重新生成画面，并在已有正式图后支持关卡测试。
2. 作品信息：展示并编辑作品名称、作品描述、作品标签。

2026-04-30 关卡列表卡片交互补充

1. 关卡列表卡片的删除按钮与关卡名称放在同一信息行，按钮固定在卡片右下角；不得再单独占用一整条底部分隔栏。
2. 关卡图片、序号与名称区域仍作为打开关卡详情的主点击区；删除按钮只触发删除，不进入详情。

2026-04-30 关卡详情面板交互补充

1. 关卡详情面板内容区按移动端优先的单列顺序展示：关卡名称 -> 画面图 -> 画面描述。其中画面图只在该关卡已有正式图时出现；新建关卡或画面为空的关卡不展示空图占位模块。
2. 画面生成主按钮固定吸底，始终位于关卡详情面板底部操作区。若当前关卡还没有正式图，按钮文案为“生成画面”；已有正式图后，按钮文案为“重新生成画面”。
3. 关卡已有正式图后，底部操作区在生成按钮上方新增单独的关卡测试入口，原“体验该关”文案收口为“关卡测试”。无正式图时不展示该入口。
4. 底部吸底操作区只承载动作按钮，不默认写玩法说明或规则解释，避免压缩移动端编辑空间。
5. 关卡详情面板内触发生成画面时，前端必须把当前编辑态完整 levelsJson 随 generate_puzzle_images action 一起提交。这样新建关卡在自动保存完成前立即生成，也能由后端写回目标关卡。
6. api-server 处理 generate_puzzle_images 时，若 action 带有 levelsJson，必须用这份关卡快照覆盖本次生成的草稿关卡视图后再定位 levelId。若请求明确传入 levelId 但关卡列表中不存在该关卡，必须返回错误，不得静默回退第一关。
7. 历史拼图素材入口只在已有正式图的 画面图 区域右下角展示，不再放在 画面描述 输入区；本地上传参考图入口仍保留在画面描述输入区右下角。
8. 历史拼图素材列表必须由服务端按当前登录账号过滤，只返回 asset_kind = puzzle_cover_image 且 owner_user_id = 当前账号 的资产；不得依赖前端过滤，也不得展示其他账号素材。

画面描述区域不再展示候选图实际 prompt 或“请生成一张适合……”之类内部提示词模块。参考图入口保留在画面描述编辑区域内，便于重新生成时继续带入。结果页编辑关卡画面描述时只同步该关卡 pictureDescription；作品描述只在作品信息 Tab 编辑，作品详情页不得再回退使用画面描述。

验收

1. 从拼图创作入口只能看到作品名称、作品描述、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择。
3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图；作品详情页展示玩家作品描述。
4. 结果页包含“拼图关卡”和“作品信息”两个 Tab；关卡列表默认至少一关，支持新增、删除和进入关卡详情。
5. 关卡详情页支持生成或重新生成画面；已有正式图后显示吸底“关卡测试”入口。
6. 发布、作品测试、自动保存作品名称、作品描述、作品标签和关卡列表仍可用。