1
This commit is contained in:
@@ -2,25 +2,38 @@
|
||||
|
||||
## 背景
|
||||
|
||||
拼图创作入口不再使用 Agent 对话收集题材锚点。新流程只让玩家填写两个字段：拼图标题、画面描述。画面描述支持上传参考图。玩家确认后直接进入草稿生成进度页，后续草稿生成、首图生成、正式图选择、结果页编辑和发布沿用现有后端编排。
|
||||
拼图创作入口不再使用 Agent 对话收集题材锚点。新流程让玩家填写作品名称、作品描述、画面描述三类信息，其中画面描述只服务首关画面生成与关卡画面语义，不再作为作品详情页的作品描述。画面描述支持上传参考图。玩家确认后直接进入草稿生成进度页，后续草稿生成、首图生成、正式图选择、结果页编辑和发布沿用现有后端编排。
|
||||
|
||||
## 入口表单
|
||||
|
||||
1. 拼图标题为必填字段，保存到 `seedText`，同时作为 `levelName` 的优先来源。
|
||||
2. 画面描述为必填字段，保存到 `pictureDescription`，同时作为 `summary` 和首图生成 prompt 的优先来源；支持多行文本，后端解析不得截断首行之后的内容。
|
||||
3. 参考图为可选字段，保存到 `referenceImageSrc`。表单支持本地图片上传为 Data URL；草稿首图生成时直接传入现有拼图图生图接口。
|
||||
4. 表单确认后前端先创建拼图 session，再立即执行 `compile_puzzle_draft`，并传入 `promptText = pictureDescription`、`referenceImageSrc`。
|
||||
5. 表单提交 payload 需要在前端创作流程中暂存，生成进度页失败重试时必须继续携带同一份画面描述与参考图。
|
||||
6. 入口不再展示拼图 Agent 聊天气泡、快捷补齐或多锚点卡片；新建拼图时必须清空旧 session，只有从当前生成进度页返回表单时保留本轮内容。
|
||||
### 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` 的默认关卡；参考图只保存在当前前端会话内，不落入 SpacetimeDB。
|
||||
4. 玩家在生成草稿前退出，再次从创作中心点击这条拼图草稿时，必须恢复到填表页，并回填之前自动保存的作品名称、作品描述和画面描述；只有执行 `compile_puzzle_draft` 且生成结果页草稿后，草稿入口才进入结果页。
|
||||
5. 表单自动保存走 `save_puzzle_form_draft` action，不消耗陶泥币，不生成图片，不改变 `stage = collecting_anchors`；生成草稿按钮仍单独触发 `compile_puzzle_draft` 并进入进度页。
|
||||
6. 点击拼图入口始终创建新草稿，不复用上一次未完成 session；恢复旧草稿只通过“我的创作”中的草稿卡进入。
|
||||
|
||||
1. 作品名称为必填字段，保存到 `workTitle`，兼容写入旧 `seedText`，同时作为作品级 `workTitle` 的真相源。
|
||||
2. 作品描述为必填字段，保存到 `workDescription`，作为作品详情页、作品列表和发布资料中的 `summary` 真相源。
|
||||
3. 画面描述为必填字段，保存到 `pictureDescription`，只作为首关画面生成 prompt、首关 `pictureDescription` 和关卡命名输入，不再覆盖作品描述。
|
||||
4. 参考图为可选字段，保存到 `referenceImageSrc`。表单支持本地图片上传为 Data URL；草稿首图生成时直接传入现有拼图图生图接口。
|
||||
5. 表单确认后前端先创建拼图 session，再立即执行 `compile_puzzle_draft`，并传入 `promptText = pictureDescription`、`referenceImageSrc`。
|
||||
6. 表单提交 payload 需要在前端创作流程中暂存，生成进度页失败重试时必须继续携带同一份作品名称、作品描述、画面描述与参考图。
|
||||
7. 生成进度页的“当前拼图信息”必须优先读取这份表单 payload，而不是读取 session 中旧 Agent 锚点或编译后的关卡名，避免用户确认后看到的标题、作品描述、画面描述发生漂移。
|
||||
8. `compile_puzzle_draft` action 必须显式携带 `workTitle`、`workDescription`、`pictureDescription`、`promptText` 与 `referenceImageSrc`。`seedText` 只作为 SpacetimeDB 旧表结构兼容载体，不能成为前端生成页展示和失败重试的唯一来源。
|
||||
9. 入口不再展示拼图 Agent 聊天气泡、快捷补齐或多锚点卡片；新建拼图时必须清空旧 session，只有从当前生成进度页返回表单时保留本轮内容。
|
||||
|
||||
## 锚点映射
|
||||
|
||||
拼图模式锚点收口为两个玩家输入源：
|
||||
拼图模式锚点收口为三个玩家输入源：
|
||||
|
||||
| 新字段 | 落地字段 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 拼图标题 | `themePromise.value`、`levelName`、`creatorIntent.themePromise` | 作为题材承诺与关卡名称的真相源 |
|
||||
| 画面描述 | `visualSubject.value`、`summary`、首图 `promptText` | 作为画面主体与生图 prompt 的真相源 |
|
||||
| 作品名称 | `themePromise.value`、`workTitle`、旧 `levelName` 兼容字段、`creatorIntent.themePromise` | 作为作品名称与题材承诺真相源 |
|
||||
| 作品描述 | `workDescription`、旧 `summary` 兼容字段 | 作为作品详情页描述、列表描述和发布描述真相源 |
|
||||
| 画面描述 | `visualSubject.value`、`levels[0].pictureDescription`、首图 `promptText` | 作为首关画面主体、首图生成 prompt 和首关关卡命名输入 |
|
||||
|
||||
兼容旧结构时仍保留 `visualMood`、`compositionHooks`、`tagsAndForbidden` 字段，但它们不再由 Agent 问答收集：
|
||||
|
||||
@@ -28,31 +41,49 @@
|
||||
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 = 表单画面描述`，首图生成后直接写入该关卡。
|
||||
6. 关卡名称由后端基于画面描述和图片语义输入生成；无可用语义时按题材标签与序号兜底，禁止继续直接使用作品名称作为关卡名称。
|
||||
7. 旧草稿或旧作品缺少 `levels` 时，读取层必须由旧 `levelName`、`summary`、`coverImageSrc`、`candidates` 补出一个兼容关卡，避免历史草稿无法打开。
|
||||
|
||||
## 后端编译
|
||||
|
||||
1. `CreatePuzzleAgentSessionRequest` 新增 `pictureDescription` 与 `referenceImageSrc`，但不改 SpacetimeDB 表结构。
|
||||
2. api-server 创建 session 时把标题和画面描述合成 `seedText` 传入 SpacetimeDB；SpacetimeDB reducer 只做确定性锚点生成，不接触图片或外部服务。
|
||||
3. `compile_puzzle_draft_with_initial_cover` 新增首图 prompt 和参考图参数。若前端传入画面描述，则首图生成直接使用这段文本；若传入参考图，则走现有 DashScope 图生图链路。
|
||||
4. 图片生成仍在 api-server 内完成，遵守 SpacetimeDB reducer 不做网络 I/O 的约束。
|
||||
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` 中保留真实钱包错误。
|
||||
|
||||
## 结果页
|
||||
|
||||
拼图草稿结果页不再区分 Tab，合并为一个可滚动列表页，内容顺序固定为：
|
||||
拼图草稿结果页分为两个 Tab：
|
||||
|
||||
1. 关卡名称。
|
||||
2. 画面预览。
|
||||
3. 画面描述。
|
||||
4. 重新生成画面按钮。
|
||||
5. 题材标签。
|
||||
1. 拼图关卡列表：默认展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、重新生成画面，并支持单独体验该关卡。
|
||||
2. 作品信息：展示并编辑作品名称、作品描述、作品标签。
|
||||
|
||||
画面描述区域不再展示候选图实际 prompt 或“请生成一张适合……”之类内部提示词模块。参考图入口保留在画面描述编辑区域内，便于重新生成时继续带入。结果页编辑画面描述时必须同步更新 `summary`，确保自动保存、作品测试、发布和重新生成画面使用同一份描述。
|
||||
画面描述区域不再展示候选图实际 prompt 或“请生成一张适合……”之类内部提示词模块。参考图入口保留在画面描述编辑区域内，便于重新生成时继续带入。结果页编辑关卡画面描述时只同步该关卡 `pictureDescription`；作品描述只在作品信息 Tab 编辑，作品详情页不得再回退使用画面描述。
|
||||
|
||||
## 验收
|
||||
|
||||
1. 从拼图创作入口只能看到标题、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
|
||||
1. 从拼图创作入口只能看到作品名称、作品描述、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
|
||||
2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择。
|
||||
3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图。
|
||||
4. 结果页为单列表，顺序符合上文要求，不展示 Tab 和内部实际 prompt。
|
||||
5. 发布、作品测试、自动保存标题、画面描述和标签仍可用。
|
||||
3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图；作品详情页展示玩家作品描述。
|
||||
4. 结果页包含“拼图关卡”和“作品信息”两个 Tab；关卡列表默认至少一关，支持新增、删除和进入关卡详情。
|
||||
5. 关卡详情页支持重新生成画面和单独体验该关卡。
|
||||
6. 发布、作品测试、自动保存作品名称、作品描述、作品标签和关卡列表仍可用。
|
||||
|
||||
Reference in New Issue
Block a user