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

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

背景

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

2026-05-03 后入口进一步收口为画面描述直创：入口表单只保留画面描述、参考图和图片模型选择；作品名称、作品描述、作品标签全部进入结果页补全。若本文件早期段落仍提到入口必填作品名称或作品描述，以 PUZZLE_PICTURE_ONLY_CREATION_AND_AI_TAGS_2026-05-03.md 为准。

首访新手引导隐藏

2026-05-12 起，平台首访不再自动进入 puzzle-onboarding 新手引导步骤。前端应直接停留在平台入口；旧新手引导面板、生成接口和保存接口暂时保留为休眠代码，后续只有在产品明确恢复时才重新打开分流开关。

首访隐藏不写入 genarrative.puzzle-onboarding.first-visit.v1，避免把“引导未展示”误记录成玩家已主动完成或跳过。

入口表单

2026-05-03 画面描述直创补充

1. 入口表单只展示 画面描述、参考图和图片模型选择；画面描述 是唯一必填字段。
2. 表单自动保存只保存 pictureDescription，不再保存入口作品名称、作品描述或推断标签。
3. 点击“生成草稿”后进入生成进度页，步骤固定为“编译首关草稿 -> 生成首关画面 -> 写入正式草稿”。
4. 生成进度页“当前拼图信息”只展示画面描述；不得展示空作品名称、空作品描述或旧五锚点结构。
5. 结果页打开后，作品名称默认使用首关名称，作品描述与作品标签保持为空，等待用户在作品信息 Tab 补全或触发 AI 标签生成。

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关”或作品名称作为默认值。生成前的参考图只保存在当前前端会话内；一旦用于首图生成并成功返回，后端必须把该参考图写入首关 pictureReference，供结果页后续重新生成继续复用。

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

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

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

7. 若运行中的旧 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。如果目标库的迁移操作员表为空，但旧库引导密钥来自旧 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. 前端仍应优先压缩参考图，入口上传图和裁剪图统一压到单边 1024 以内；后端 body 上限只用于容纳合理尺寸的单张参考图，超大原图不应直接落入 SpacetimeDB 或作为作品字段持久化，后端解析后会拒绝超过 8MB 字节的参考图。
8. aiRedraw = true 且存在 referenceImageSrc 时，api-server 必须走 VectorEngine POST /v1/images/edits multipart 图生图接口；无参考图或入口页 aiRedraw = false 时不走图生图，关闭 AI 重绘会直接应用上传图为首关正式图。
9. 作品更新接口 PUT /api/runtime/puzzle/works/{profileId} 必须支持作品信息和关卡列表一起写入，前端自动保存不得只写旧单关字段。
10. StartPuzzleRunRequest 新增可选 levelId。详情页或草稿结果页单独体验某关时传入目标关卡，后端从作品/草稿的 levels 中选取该关卡生成运行态。
11. ExecutePuzzleAgentActionRequest 必须保留 pictureDescription 字段。表单直达生成时，compile_puzzle_draft 优先用 pictureDescription 作为首图 prompt，再回退到旧 promptText；避免生成页展示的是玩家画面描述，但后端实际用作品名称或旧摘要出图。
12. compile_puzzle_draft 中的图片上游失败不得映射成 400 BAD_REQUEST。DashScope 返回 InvalidParameter 或任务失败时，api-server 统一按 502 UPSTREAM_ERROR 暴露，并在 details.message 中保留“拼图图片生成失败：...”的业务原因，避免生成页只显示“请求参数不合法”。
13. compile_puzzle_draft 前置光点预扣失败不得映射成 400 BAD_REQUEST。余额不足返回 409 CONFLICT，SpacetimeDB procedure 不可用、绑定不匹配、钱包服务异常等统一按 502 UPSTREAM_ERROR 暴露，并在 details.message 中保留真实钱包错误。
14. 生成拼图作品草稿动作涉及的表单 seed prompt 与首图 prompt 来源选择统一收口在 server-rs/crates/api-server/src/prompt/puzzle/draft.rs；puzzle.rs 只负责调用 SpacetimeDB、计费、图片服务和持久化，不再直接拼草稿 prompt 文本。

结果页

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

1. 拼图关卡列表：默认展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、生成或重新生成画面，并在已有正式图后支持关卡测试。
2. 作品信息：展示并编辑作品名称、作品描述、作品标签。
3. UI：展示并编辑拼图运行态 UI 背景提示词。compile_puzzle_draft 草稿编译完成首图和背景音乐后，api-server 会基于作品名称、作品描述、标签和首关信息自动生成首关 9:16 UI 背景图；结果页继续支持用户修改提示词并通过 generate_puzzle_ui_background 重新生成。图片生成在 api-server 中读取 public/ui-previews/puzzle-image-compact-ui-2026-05-08.png 作为非拼图 UI 背景参考图，并调用 VectorEngine gpt-image-2-all 的 9:16 图片生成链路。生成结果写入首关 levels_json 的 uiBackgroundPrompt、uiBackgroundImageSrc、uiBackgroundImageObjectKey，不新增 SpacetimeDB 表字段。
4. 音乐：编辑并生成背景音乐，音乐资产暂存到首关 levels_json[0].backgroundMusic。

2026-05-12 UI 背景生成补充

1. UI 背景图只生成拼图棋盘以外的运行态背景与 UI 容器层次，提示词必须要求中央正方形拼图区和外部 UI 背景之间有明确描边、容器或留白边界。
2. UI 背景图不得生成文字、水印、按钮文字、数字、拼图碎片、完整拼图图像或教程浮层，避免与真实拼图图块和运行态 HUD 混淆。
3. 结果页 UI Tab 支持直接修改提示词并重新生成；点击生成前会把本地首关 uiBackgroundPrompt 同步进 levelsJson，使自动保存尚未完成时后端仍能拿到最新提示词。
4. 草稿编译阶段自动生成 UI 背景失败时只记录 warning，并保留草稿进入结果页；用户可在 UI Tab 重新生成，不因背景图上游波动阻断首图草稿主流程。
5. api-server 负责读取参考图、拼接生成 prompt、调用 VectorEngine、下载并转存 OSS；SpacetimeDB 只通过 save_puzzle_ui_background procedure 保存结果，不做外部 I/O。
6. 拼图运行态读取 currentLevel.uiBackgroundImageSrc 渲染为全屏背景；无 UI 背景图时继续使用原封面模糊背景兜底。棋盘本身仍由正式拼图图生成，不能把 UI 背景当作拼图切块来源。

2026-05-12 草稿生成完成自动试玩补充

1. 玩家停留在拼图草稿生成进度页等待 compile_puzzle_draft 完成时，前端必须先把最新 session / profile 记为草稿结果页状态，再自动启动本地拼图试玩。
2. 自动试玩的返回目标固定为 puzzle-result。玩家在试玩过程中点击左上角返回后，应进入同一份拼图草稿结果页继续查看和编辑。
3. 自动试玩只在当前仍处于 puzzle-generating 时触发；若玩家已返回草稿 Tab 或切到其它页面，后台生成完成只标记草稿已生成，不得强行抢屏进入试玩。
4. 若自动启动试玩失败，前端保留草稿结果页作为兜底查看入口，并展示已有错误态，不应丢失已生成草稿。

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 = 当前账号 的资产；不得依赖前端过滤，也不得展示其他账号素材。
9. 画面图 图卡本身就是上传热区，详情页不再保留右下角独立“上传参考图”按钮；历史入口统一使用带 History 图标和 历史 小字的按钮。入口页历史按钮固定在图片上传区域右上角；空图态只展示“上传图片/填写画面描述”轻量提示，不再展示额外规则说明文案。

2026-05-10 关卡生图交互补充

1. 关卡详情页的 画面图 与 画面描述 模块对齐入口页拼图表单：画面图使用稳定正方形图卡，画面描述使用固定高度输入区并保留图片模型选择。
2. 新建关卡或无正式图关卡也展示 画面图 图卡；空图态只保留图标化占位和生成中状态，不追加规则说明文案。
3. 关卡详情页删除手填 参考图链接或资产ID 输入框。参考图只能通过本地上传或历史拼图素材选择进入本次生成请求；字段 levels[].pictureReference 继续作为后端生成后的复用字段透传，不作为用户可手填表单项。
4. 单关生成等待估算从 30 秒调整为 90 秒；生成按钮内展示小字 等待时间可以制作更多关卡哦~，不得另起说明面板。
5. 触发某一关生成时，前端必须立即把该关 generationStatus 标为 generating 并随当前 levelsJson 写入草稿自动保存链路；后端生成完成后再写回 ready。
6. generationStatus = generating 的关卡在详情弹窗关闭后仍保留进度展示，再次打开同一关详情能继续看到生成进度；关卡列表卡片也必须展示生成中的轻量状态。
7. 单关图片生成必须作为后台 action 执行，不占用拼图结果页全局 busy 状态；生成期间仍允许编辑作品信息、编辑关卡、新增关卡、删除其他关卡、关卡测试和继续触发其他可并行动作。
8. 发布是唯一必须等待全部图片生成完成的草稿结果页动作；发布检查需要把 generationStatus = generating 的关卡列为 blocker，避免未完成资源进入广场。
9. 后台生图回包只合并对应关卡的图片候选、正式图、资产 ID 与生成状态，不得覆盖用户等待期间对关卡名、画面描述、作品信息或新增关卡所做的本地编辑。

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

验收

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