@@ -10,6 +10,8 @@
`PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织， `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx` 。
移动端底部一级导航是全局平台样式，不按单一玩法分叉。当前视觉统一为米白浮动胶囊底座、浅棕分隔线、棕色线性图标、橘色选中态和底部短下划线；中间 `创作` 入口保持凸起圆形主按钮，但凸起位移只能作用在按钮内容层，不能移动承载分隔线的 Tab 按钮容器， `PlatformHomeTab` / 登录态规则决定，样式调整不得改写 Tab 文案或导航状态。
## 新增玩法创作工具平台 SOP
新增玩法默认采用表单/图片输入创作工作台，链路为：
@@ -45,23 +47,26 @@
当前口径：
- 图像输入复用 `CreativeImageInputPanel` 。
- 结果页每关画面编辑和素材配置里的 UI 背景生成也 复用 `CreativeImageInputPanel` ； 三处 只共享受控 UI 模块， `formDraft` 与草稿编译 payload， `levels[].pictureReference/pictureDescription` 并触发 `generate_puzzle_images` ， `levels[0].uiBackgroundPrompt/uiBackgroundImage*` 并触发 `generate_puzzle_ui_background` `displayImageSrc` 自动暴露 AI 重绘开关；只有本地上传、历史选择或已保存 `pictureReference` 可作为重绘参考图时，才显示 AI 重绘开关并把状态带入 `generate_puzzle_images` 。
- 支持画面描述生图、多参考图生图、上传或历史生成主图后 AI 重绘、上传或历史生成主图后不重绘；主链要求浏览器先经 `/api/assets/direct-upload-tickets` 直传 OSS 并确认 `asset_object` ，创作 action 只提交 `referenceImageAssetObjectId(s)` ，由后端换取 OSS 只读签名 URL 给 VectorEngine 读取； 本地上传 Data URL 与历史 `/generated-*` 图片路径仅保留为旧草稿、旧入口或未迁移客户端的兼容输入。
- 草稿生成会先持久化 `generationStatus=generating` 的作品摘要，生成完成并回写关卡图、UI 背景后再变为 `ready` ； 首关关卡图和 UI 背景在命名稳定后并行启动， 当前不自动生成背景音乐。
- 结果页每关画面编辑复用 `CreativeImageInputPanel` ； 入口页和关卡画面 只共享受控 UI 模块， `formDraft` 与草稿编译 payload， `levels[].pictureReference/pictureDescription` 并触发 `generate_puzzle_images` 。结果页删除独立“素材配置”Tab， 。通用图片面板的展示图和 AI 重绘参考图能力必须分开控制：结果页正式关卡图只作为预览图，不因存在正式图 自动暴露 AI 重绘开关；只有本地上传、历史选择或已保存 `pictureReference` 可作为重绘参考图时，才显示 AI 重绘开关并把状态带入 `generate_puzzle_images` 。用户在本次编辑中上传或选择历史图后，该图优先占据主图卡片，可删除、切换 AI 重绘，也可关闭 AI 重绘直用；仅有正式图预览时，画面描述框仍可上传多张参考图。关卡详情弹窗应使用加宽面板，关卡名称、画面图和画面描述合并在同一个纵向列表中，名称输入和画面编辑模块外层不再包独立 `platform-subpanel` ；画面图卡仍必须保留稳定最小高度，避免弹窗内 `flex-1` 布局坍缩后只剩标题、描述输入和操作按钮。
- 支持画面描述生图、多参考图生图、上传或历史生成主图后 AI 重绘、上传或历史生成主图后不重绘；主链要求浏览器先经 `/api/assets/direct-upload-tickets` 直传 OSS 并确认 `asset_object` ，创作 action 只提交 `referenceImageAssetObjectId(s)` ，由后端校验 owner / bucket / kind / MIME / size 后签发 OSS 只读 URL 并下载为 VectorEngine `/v1/images/edits` 的 multipart `image` part。`/generated-*` 图片路径仅保留为旧草稿、旧入口或未迁移客户端的兼容输入；关闭 AI 重绘时，后端统一解析为首关或当前关卡正式图后再持久化，不调用第一段拼图首图生成 。
- 草稿生成会先持久化 `generationStatus=generating` 的作品摘要，生成完成并回写关卡拼图画面、关卡画面参考图、UI spritesheet 和关卡 背景图 后再变为 `ready` ；当前不自动生成背景音乐。生成页进度不再按固定 5 分钟展示，而按实际开始时间和当前路径的分步骤预计时长推进；任一同步 action 回包到达时立即以真实完成/失败结果冻结进度 。
- 作品架拼图草稿的“生成中”遮罩只表示初始草稿还没有可查看结果；只要作品摘要、首关封面或任一关卡候选图已经可用，后续 UI 背景重生成和追加关卡生图都必须作为结果页局部生成态处理，不能阻止打开草稿结果页。
- 拼图草稿编译是长耗时 action， `1_0 00_000ms` 且不自动重试，生成页预计完成时间按 `5` 分钟展示； 生成页恢复时必须沿用作品摘要 `updatedAt` 作为原始 `startedAtMs` ，失败/完成态用 `finishedAtMs` 冻结耗时，不能在锁屏或返回草稿页后重新从 0 计时。
- 拼图草稿编译是长耗时 action， `1_8 00_000ms` （ `gpt-image-2` 调用的预期用时按 90 秒计算；完整 AI 重绘路径为 `编译首关草稿` 8 秒、`生成关卡名称` 10 秒、`生成拼图首图` 90 秒、`生成关卡画面` 90 秒、`生成UI与背景` 90 秒、`写入正式草稿` 10 秒，合计约 298 秒。上传图且关闭 AI 重绘时必须跳过 `生成拼图首图` ，直接进入 `生成关卡画面` 和 `生成UI与背景` ，合计约 208 秒。`updatedAt` 作为原始 `startedAtMs` ，失败/完成态用 `finishedAtMs` 冻结耗时，不能在锁屏或返回草稿页后重新从 0 计时。
- 若浏览器锁屏、息屏或网络切换导致 compile 请求失败，前端在标记失败前必须先复读 `getPuzzleAgentSession(sessionId)` ；只有最新 session 仍缺 `draft.coverImageSrc` 、首关 `coverImageSrc` 或候选图时才展示失败，复读到已生成草稿时按成功收尾、刷新作品架并继续自动试玩/结果页链路。
- 拼图参考图 AI 重绘优先 走 VectorEngine `/v1/images/edits` ； 若编辑接口超时，`api-server` 会降级为 `/v1/images/generations` ，并把同一参考图塞进 `image` 数组继续生成，避免参考图草稿整单失败 。
- 结果页素材配置当前只保留 UI 相关能力；旧背景音乐入口隐藏 。
- 拼图参考图 AI 重绘走 VectorEngine `/v1/images/edits` ； 无参考图时走 `/v1/images/generations` 。两者模型都使用 `gpt-image-2` ，参考图由后端作为 multipart `image` part 传入编辑接口 。
- 每次新建关卡生成或重新生成关卡图都必须由 `api-server` 串起当前关卡资产包： `coverImageSrc/coverAssetId` 作为关卡拼图画面和结果页预览图，提示词来源同样按显式画面描述、关卡画面描述、草稿摘要顺序回退，且固定要求输出画面比例为 `1:1` ；上传图且关闭 AI 重绘时跳过这一段，把上传图或历史图持久化为 `sourceType=uploaded` 的正式候选。随后用正式候选图作为参考，`9:16` 生成完整拼图游戏关卡画面并写入 `levelSceneImageSrc/levelSceneImageObjectKey` ， ， ； ， `1:1` 、`1k` 先生成纯绿色绿幕背景图，后端上传 OSS 前必须把绿幕扣成透明 PNG， `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey` ，按钮顺序固定为返回、设置、下一关、提示、原图、冻结，按钮素材自身保留对应中文文字，返回和设置按钮不得额外生成白色外圈、白底圆环或浮雕外框；纯背景用 `9:16` 、`1k` 写入 `levelBackgroundImageSrc/levelBackgroundImageObjectKey` ，提示词必须包含“禁止在背景中出现人像或和拼图画面中主体一致的内容”。运行态不直接使用第二段完整关卡画面，但必须持久化它用于追踪和后续再生成。结果页局部关卡生成进度按 AI 重绘开启约 270 秒、关闭 AI 重绘约 180 秒展示 。
- 结果页允许多关卡并行编辑和生成；某一关卡图片生成完成回包只静默更新该关卡素材与生成态，不得自动打开或切换关卡详情面板，避免打断用户正在编辑的其它关卡。
- 结果页 UI 背景重生成只禁用 UI 背景自己的按钮和确认动作 ，不禁用“新增关卡”、关卡图片生成、 关卡详情编辑和结果页导航；关卡图片生成也只标记对应关卡的局部生成进度 。
- 结果页关卡图片生成只标记对应关卡的局部生成进度 ，不禁用“新增关卡”、其它 关卡详情编辑和结果页导航。
- 结果页单关测试只能把完整草稿持久化，并通过 `levelId` 指定运行态起始关卡；不得把单关快照作为整份草稿调用 `updatePuzzleWork` ，否则 source session 和作品 profile 的 `levels` 会被覆盖成单关，退出重进后其它关卡会丢失。
- 结果页生成关卡图时若关卡名为空，前端必须传 `shouldAutoNameLevel=true` ，后端复用首关命名契约先按画面描述生成关卡名，再在图片生成后用视觉命名结果精修，并把生成名和 UI 背景提示词随本次关卡快照写回。
- 拼图 UI 背景是作品运行态背景，不只属于第一关；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺 `uiBackgroundImageSrc/uiBackgroundImageObjectKey` 必须继承同作品首个可用 UI 背景，仍缺失时才沿用当前运行态快照背景或默认 UI。
- 拼图运行态背景优先读取当前关卡 `levelBackgroundImageSrc/levelBackgroundImageObjectKey` ，旧数据才兼容 `uiBackgroundImageSrc/uiBackgroundImageObjectKey` ；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺关卡背景时 必须继承同作品首个可用关卡 背景，仍缺失时才沿用当前运行态快照背景或默认 UI。运行态按钮视觉优先读取当前关卡 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey` ，先按透明 alpha 自动边界检测识别 spritesheet 中的独立按钮展示矩形，再按原图位置从左到右、从上到下映射到返回、设置、下一关、提示、原图、冻结；同一组件还要按较高 alpha 阈值派生紧致点击热区，透明留白和柔边低 alpha 区域尽量不响应点击。检测失败时回退旧固定六格裁切，缺失时才用现有图标按钮兜底。有 spritesheet 时，返回和设置按钮的点击容器只提供透明点击区，不再叠加默认白色圆形底；底部提示、原图、冻结三枚素材按检测矩形的原始宽高比显示，不能强行拉伸成正圆或铺满整列。底部道具区不再使用连片胶囊背景，提示、原图、冻结三个按钮均匀分布；运行态只展示按钮素材本身，不额外叠加“提示 / 原图 / 冻结”文字。
- 拼图运行态棋盘不叠加分块蒙版、描边、阴影、选中底色或合并块 SVG 轮廓；拼图片本体需要裁切为圆角形状，单块使用独立圆角裁切，合并块使用 SVG 原生 `clipPath` 裁切整体外轮廓，外凸角和内凹角分别计算半径，内凹角半径要比外凸角更明显以避免手机 WebView 中看起来仍是直角。原图道具只在用户主动确认后打开独立原图查看层，不在当前拼图棋盘上叠加原图。
- 拼图运行态拖拽必须完全跟随手指或鼠标位置，`pointermove` 期间即时写入可见拼块的 transform，
- 拼图运行态的提示、设置等点击弹层跟随当前运行态主色主题，使用普通圆角主题面板，不复用像素九宫格素材框。
- 拼图运行态壳层自身要补齐 `platform-ui-shell` / `platform-theme` / `platform-theme--light|dark` ，不能依赖外层平台壳来提供主题变量；`/puzzle` 直达页和平台内嵌页都必须渲染同一套主题语义类。
- 拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 `第 N 关` 和关卡名，左侧固定使用 `media/logo.png` 卡通形象；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
- 拼图运行态进行中关卡的 `elapsedMs` 仍是结算字段，设置面板的“当前用时”必须按 `startedAtMs` 、暂停累计和冻结累计实时派生；不要直接把进行中的 `currentLevel.elapsedMs` 当作展示值。
- 推荐页嵌入拼图运行态时，通关结算弹层必须挂到页面级 fixed 浮层，不能留在推荐卡片视觉区内的 absolute 覆盖层；推荐页滑动卡片和运行态视口都使用 `overflow: hidden` ，半屏内容区会裁剪排行榜、下一关按钮和相似作品卡。
- 推荐页里的拼图作品如果从运行态进入“改造”结果页，返回平台后要清掉推荐嵌入态的 `activeRecommendEntryKey` / `activeRecommendRuntimeKind` / `isStartingRecommendEntry` ，再重新按推荐页自动启动逻辑进入作品，不能复用已经被清空的旧 `puzzleRun` 。
- 拼图运行态允许前端低延迟交互表现，但通关、排行榜、奖励和作品状态仍以后端确认为准。
@@ -94,9 +99,10 @@
入口表单只展示：
- 题材主题。
- `2D素材风格` 横向风格卡：扁平图标、赛璐璐卡通、像素复古、手绘水彩、贴纸描边、厚涂图标、自定义。
- 难度：轻松、标准、进阶、硬核。
入口不再要求用户选择素材风格；历史草稿和旧接口中的 `assetStyleId` / `assetStyleLabel` / `assetStylePrompt` 仅作为兼容字段保留，新入口提交不再写入这些字段。
难度映射：
| 难度 | clearCount | difficulty | 总物品数 | 物品种类 |
@@ -104,29 +110,27 @@
| 轻松 | 8 | 2 | 24 | 3 |
| 标准 | 12 | 4 | 36 | 9 |
| 进阶 | 16 | 6 | 48 | 15 |
| 硬核 | 21 | 8 | 63 | 21 |
| 硬核 | 21 | 8 | 63 | 20 |
当前素材生成流水线：
1. 点击生成前弹出泥点确认，草稿生成固定消耗 `10` 泥点。
2. 先写入可恢复草稿 profile， 图片生成、切图、OSS 上传、背景和容器生成；作品摘要在素材或背景 未完整时下发 `generationStatus=generating` ， 素材和背景 完整后下发 `ready` ，草稿完成条件不包含 `backgroundMusic` 。
3. 物品素材不再调用 Hyper3D Rodin， 。
4. 物品 sheet 走 VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent` ，单张 `1 :1` 图固定 `5*5` ，每张承载 `5 ` 个 物品、每个物品 `5` 个视角 。
5. 物品 sheet prompt、切图、透明化和五视角切片持久化复用 `generated_asset_sheets` 通用模块； `generatedItemAssets[].imageViews[]` 。
6. 切图前先在整张 sheet 上做绿幕 / 近白底透明化和边缘去污染，再按格子导出独立 PNG； 。
7. `generatedItemAssets[].imageViews[]` 是新素材主字段，`imageSrc/imageObjectKey` 只兼容首张视角
2. 先写入可恢复草稿 profile， 关卡整图生成、三张派生图生成、OSS 上传和素材解析； 未完整时下发 `generationStatus=generating` ，完整后下发 `ready` ，草稿完成条件不包含 `backgroundMusic` 。
3. 首次调用 VectorEngine `gpt-image-2` ，无参考图，竖屏 `9:16` ，生成完整抓大鹅关卡画面并持久化到 `generatedBackgroundAsset.levelSceneImageSrc/levelSceneImageObjectKey` 。提示词必须包含用户主题描述、顶部返回 / 标题倒计时 / 设置按钮、中间与主题匹配且贴横向边缘的容器，以及底部“移出 / 凑齐 / 打乱”三个道具按钮 。
4. 关卡整图完成后并发发起三次 `gpt-image-2` 编辑请求，三者都以关卡整图作为参考图：`1K` 、`1:1` 的 UI spritesheet 写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey` ； `1K` 、`9 :16 ` 的背景图写入 `imageSrc/imageObjectKey` ； `2K` 、`1:1 ` 的 物品 spritesheet 写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey` 。
5. UI spritesheet 提示词固定要求按从上到下、从左到右整理纯绿色绿幕背景素材：返回按钮、设置按钮、方格素材（不含边框，仅保留一个）、移出按钮、凑齐按钮、打乱按钮；后端上传 OSS 前必须把绿幕扣成透明 PNG。背景图提示词固定要求移除全部 UI 组件和容器内含物，完整保留容器和背景，并补全被 UI 覆盖的背景内容 。
6. 物品 spritesheet 固定 `10行*10列` 、统一纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG； ， ， ， `20` 种物品，物品信息列表全部展示这 `20` 种；持久化单格映射必须按 `row = itemIndex / 2 + 1` 、`col = itemIndex % 2 * 5 + viewIndex + 1` 写入通用系列素材图集，不能再用 `row = itemIndex + 1` 。`generatedItemAssets[].imageViews[]` 仍兼容已切好的五视角图，缺失时运行态和编辑器按 spritesheet 自动解析结果回退 。
7. 前端和运行态统一使用 alpha 连通域矩形检测解析 spritesheet： `5` 个区域组成一个物品的五个形态，最多 `20` 个物品。透明背景是解析前提，不能在前端按固定像素坐标写死切片 。
8. 文本生成物品名称时必须同时生成 `itemSize` ，只允许 `大` 、`中` 、`小` 。该字段随 `generatedItemAssets[].itemSize` 持久化并下发；历史缺失字段的素材按 `大` 兼容，模型缺失或非法值按物品名本地推断。
9. 局内 `9:16` 纯背景图和 `1:1` 中心容器 UI 图分开生成。纯背景不得包含锅、盘、托盘、HUD、按钮、文字或物品， ， ； `/v1/images/edits` 参考透明容器图。该容器参考图由后端内嵌到 `api-server` ，不要依赖运行时当前目录下的 `public/` 文件 。
10. 当前抓大鹅音频生成关闭：入口无 `生成音效` ，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 `backgroundMusic` / `clickSound` 字段继续兼容传递 。
11. UI 背景和容器资产的持久化真相仍在 `generatedItemAssets[].backgroundAsset` ； `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset` 读取。草稿编译后的 `draftJson` 自身也必须携带 `generatedItemAssets` 快照；
9. 当前抓大鹅音频生成关闭：入口无 `生成音效` ，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 `backgroundMusic` / `clickSound` 字段继续兼容传递 。
10. 背景、UI spritesheet、物品 spritesheet 和历史容器兼容字段的持久化真相仍在 `generatedItemAssets[].backgroundAsset` 与提升后的 `generatedBackgroundAsset` ； `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset` 读取。草稿编译后的 `draftJson` 自身也必须携带 `generatedItemAssets` 快照； 。
结果页当前结构：
- `作品信息` ：名称、描述、标签；封面编辑收口到发布面板。
- `难度配置` ：四档离散拖动条，显示需要消除、总物品数、物品种类、已生成物品种类。
- `素材配置 > 物品` ：两列素材卡，点击打开独立五视角预览面板；支持删除、批量新增和批量重新生成。替换模式必须保留原 `itemId` 和列表顺序。
- `素材配置 > UI` ： 纯 背景图与运行态 UI 预览，重生成消耗 `2` 泥点； UI 预览必须复用运行态顶部 HUD、中央容器棋盘、容器图定位 和底部槽位样式，不单独维护一套简化预览 UI。
- `素材配置 > 容器形象` ：单独预览和重生成中心容器，消耗 `2` 泥点。
- `素材配置 > 物品` ：两列素材卡固定展示 20 个物品 ，点击打开独立五视角预览面板；支持删除、批量新增和批量重新生成。替换模式必须保留原 `itemId` 和列表顺序。
- `素材配置 > UI素材 ` ： 预览 背景图、UI spritesheet 原图、物品 spritesheet 原图和物品 spritesheet 自动解析缩略图；背景图只支持预览，不提供重新生成入口。 UI 预览必须复用运行态顶部 HUD、中央容器棋盘和底部槽位样式，
运行态当前口径：
@@ -136,8 +140,9 @@
- 初始物品坐标围绕容器口中心生成，并保留内缩安全距离，避免贴边和局部角落聚集。
- 本地试玩与 Rust `module-match3d` 后端领域生成使用同一套中心铺开口径；生成点覆盖四象限且均值接近中心。
- 运行态优先消费 2D 生成图；默认积木 / 程序化 3D 表现只作为视觉分支和兜底，不改变规则真相。
- 运行态启动前要预加载 `generatedItemAssets[].imageViews[]` 、顶层 `generatedBackgroundAsset` 、物品挂载 `backgroundAsset` 中的背景和容器图；首次生成自动试玩、结果页手动试玩、推荐流和公开详情启动都必须传入提升后的 profile。卡片摘要缺 UI 背景或容器字段时，进入运行态前必须补读 work detail。补读后的 profile 也要再次提升 `generatedItemAssets[].backgroundAsset` ，确保背景和容器字段传给 `Match3DRuntimeShell` 。
- 局内容器图在移动端宽度大于屏幕宽度并略向下压，当前运行态使用 `w-[min(116vw,42rem)]` 与 `top-[54%]` 放大和下移容器图本体，保持原图比例不拉伸且不改变后端物品布局、点击半径或消除规则；生成容器图加载成功后棋盘外壳透明且 `overflow-visible` ，只有生成图缺失或加载失败时才显示透明参考容器兜底 。
- 难度只决定本局加载的物品种类数量：轻松 3、标准 9、进阶 15、硬核 20。硬核仍保留 21 次消除和 63 件总物品，运行态按 20 种素材循环复用，不要求生成第 21 种素材 。
- 运行态启动前要预加载 `generatedItemAssets[].imageViews[]` 、顶层 `generatedBackgroundAsset` 、物品挂载 `backgroundAsset` 中的背景、UI spritesheet 和物品 spritesheet； ， `generatedItemAssets[].backgroundAsset` ，确保背景和图集字段传给 `Match3DRuntimeShell` 。
- 背景图作为运行态全屏背景，图内已经保留容器；旧 `containerImage*` 只作为历史透明容器兼容字段。若 `containerImage*` 与 `uiSpritesheetImage*` 同源，运行态不得把 UI spritesheet 当中心容器图叠到棋盘上。
- generated 私有图换签未完成时，局内物品先隐藏等待，不得短暂显示默认积木；同一批资源在重启 run 时保留已解析签名 URL，
- `itemSize` 只缩放生成 2D 图片本体：`大` 、`中` 、`小` 均按相对尺寸缩放，其中 `大` 也比原始图片略小，`中` 和 `小` 进一步缩小；不改变后端下发的布局半径、点击半径或三消规则。
- 物品进入底部物品栏时按同类型插入：如果物品栏已有同类物品，新物品插到该类型最后一个物品后面，后续物品整体后移；没有同类时追加到当前末尾。达到三件同类时，在飞入物品栏动画结束后，左侧和右侧同类物品向中间合成，三件一起消失，播放合成音效，不展示星星图标，后面的物品再向前补位。该动效只是前端表现层，后端和本地试玩仍负责权威插入、指定点击类型清除与补位后的槽位快照。
