fix: 修复拼图草稿写入步骤完成态

.hermes/shared-memory/pitfalls.md

@@ -1024,6 +1024,14 @@
 - 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx` 覆盖抓大鹅和拼图生成后自动试玩 / 返回结果页。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
+## 拼图最后一步到 100% 但不变绿优先看阶段映射
+
+- 现象：拼图草稿生成跑完所有步骤后，总进度仍停在 98%，最后一步“写入正式草稿”显示 100% 但卡片不变绿，视觉上像还在进行中。
+- 原因：进度条总进度刻意保留 98% 作为未收到 action 回包前的安全余量，但最后一步的绿色完成态只看步骤状态；如果时间轴已经跑到 `puzzle-select-image` 末尾却还没收到 `ready` 回包，最后一步会一直保持 active。
+- 处理：`buildMiniGameDraftGenerationProgress` 需要在拼图最后一步时，把“预计写入时长已耗尽”单独判为 completed，避免出现“进行中 100%”。
+- 验证：`npm test -- src/services/miniGameDraftGenerationProgress.test.ts`。
+- 关联：`src/services/miniGameDraftGenerationProgress.ts`、`src/services/miniGameDraftGenerationProgress.test.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 微信支付回调验签不要用商户私钥
 
 - 现象：微信小程序支付下单能返回 `prepay_id`，但真实支付通知验签失败，或者本地实现误把商户 API 私钥当作回调验签 key。

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -79,7 +79,7 @@ RPG / 拼图等运行态存档选择入口统一在个人中心 `常用功能 >
 - 支持画面描述生图、多参考图生图、上传或历史生成主图后 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。本地上传 Data URL 与历史 `/generated-*` 图片路径仅保留为旧草稿、旧入口或未迁移客户端的兼容输入；关闭 AI 重绘时，后端统一解析为首关或当前关卡正式图后再持久化，不调用第一段拼图首图生成。
 - 草稿生成会先持久化 `generationStatus=generating` 的作品摘要，生成完成并回写关卡拼图画面、关卡画面参考图、UI spritesheet 和关卡背景图后再变为 `ready`；当前不自动生成背景音乐。生成页进度不再按固定 5 分钟展示，而按实际开始时间和当前路径的分步骤预计时长推进；任一同步 action 回包到达时立即以真实完成/失败结果冻结进度。
 - 作品架拼图草稿的“生成中”遮罩只表示初始草稿还没有可查看结果；只要作品摘要、首关封面或任一关卡候选图已经可用，后续 UI 背景重生成和追加关卡生图都必须作为结果页局部生成态处理，不能阻止打开草稿结果页。
-- 拼图草稿编译是长耗时 action，前端 action 请求默认等待 `1_800_000ms`（30 分钟）且不自动重试。每次 `gpt-image-2` 调用的预期用时按 90 秒计算；完整 AI 重绘路径为 `编译首关草稿` 8 秒、`生成关卡名称` 10 秒、`生成拼图首图` 90 秒、`生成关卡画面` 90 秒、`生成UI与背景` 90 秒、`写入正式草稿` 10 秒，合计约 298 秒。上传图且关闭 AI 重绘时必须跳过 `生成拼图首图`，直接进入 `生成关卡画面` 和 `生成UI与背景`，合计约 208 秒。生成页恢复时必须沿用作品摘要 `updatedAt` 作为原始 `startedAtMs`，失败/完成态用 `finishedAtMs` 冻结耗时，不能在锁屏或返回草稿页后重新从 0 计时。
+- 拼图草稿编译是长耗时 action，前端 action 请求默认等待 `1_800_000ms`（30 分钟）且不自动重试。每次 `gpt-image-2` 调用的预期用时按 90 秒计算；完整 AI 重绘路径为 `编译首关草稿` 8 秒、`生成关卡名称` 10 秒、`生成拼图首图` 90 秒、`生成关卡画面` 90 秒、`生成UI与背景` 90 秒、`写入正式草稿` 10 秒，合计约 298 秒。上传图且关闭 AI 重绘时必须跳过 `生成拼图首图`，直接进入 `生成关卡画面` 和 `生成UI与背景`，合计约 208 秒。生成页恢复时必须沿用作品摘要 `updatedAt` 作为原始 `startedAtMs`，失败/完成态用 `finishedAtMs` 冻结耗时，不能在锁屏或返回草稿页后重新从 0 计时。未收到 action 回包前，总进度仍最多停在 98%，但当预计写入时长耗尽且仍处于 `写入正式草稿` 时，该步骤自身应显示已完成，不能出现“进行中 100%”。
 - 若浏览器锁屏、息屏或网络切换导致 compile 请求失败，前端在标记失败前必须先复读 `getPuzzleAgentSession(sessionId)`；只有最新 session 仍缺 `draft.coverImageSrc`、首关 `coverImageSrc` 或候选图时才展示失败，复读到已生成草稿时按成功收尾、刷新作品架并继续自动试玩/结果页链路。
 - 拼图参考图 AI 重绘走 VectorEngine `/v1/images/edits`；无参考图时走 `/v1/images/generations`。两者模型都使用 `gpt-image-2`，参考图由后端作为 multipart `image` part 传入编辑接口。
 - 每次新建关卡生成或重新生成关卡图都必须由 `api-server` 串起当前关卡资产包：AI 重绘开启时第一段沿用草稿生成第一关的拼图主图提示词配置和模型 / 尺寸 / 参考图规则生成 `coverImageSrc/coverAssetId` 作为关卡拼图画面和结果页预览图，提示词来源同样按显式画面描述、关卡画面描述、草稿摘要顺序回退，且固定要求输出画面比例为 `1:1`；上传图且关闭 AI 重绘时跳过这一段，把上传图或历史图持久化为 `sourceType=uploaded` 的正式候选。随后用正式候选图作为参考，`9:16` 生成完整拼图游戏关卡画面并写入 `levelSceneImageSrc/levelSceneImageObjectKey`，提示词必须要求道具按钮上不要显示次数标注，且返回按钮和设置按钮旁禁止标注文字；UI spritesheet 与关卡纯背景在关卡画面完成后并发生成，spritesheet 用 `1:1`、`1k` 先生成纯绿色绿幕背景图，后端上传 OSS 前必须把绿幕扣成透明 PNG，再写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，按钮顺序固定为返回、设置、下一关、提示、原图、冻结，按钮素材自身保留对应中文文字，返回和设置按钮不得额外生成白色外圈、白底圆环或浮雕外框；纯背景用 `9:16`、`1k` 写入 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，提示词必须包含“禁止在背景中出现人像或和拼图画面中主体一致的内容”。运行态不直接使用第二段完整关卡画面，但必须持久化它用于追踪和后续再生成。结果页局部关卡生成进度按 AI 重绘开启约 270 秒、关闭 AI 重绘约 180 秒展示。

src/services/miniGameDraftGenerationProgress.test.ts

@@ -70,6 +70,25 @@ describe('miniGameDraftGenerationProgress', () => {
     expect(writeBackProgress?.steps[5]?.status).toBe('active');
   });
 
+  test('puzzle write-back step turns completed once rounded progress reaches 100%', () => {
+    const state: MiniGameDraftGenerationState = {
+      kind: 'puzzle',
+      phase: 'compile',
+      startedAtMs: 1_000,
+      completedAssetCount: 0,
+      totalAssetCount: 0,
+      error: null,
+    };
+
+    const progress = buildMiniGameDraftGenerationProgress(state, 298_950);
+
+    expect(progress?.phaseId).toBe('puzzle-select-image');
+    expect(progress?.overallProgress).toBe(98);
+    expect(progress?.estimatedRemainingMs).toBe(50);
+    expect(progress?.steps[5]?.completed).toBe(1);
+    expect(progress?.steps[5]?.status).toBe('completed');
+  });
+
   test('puzzle direct upload generation skips the first image generation step', () => {
     const state: MiniGameDraftGenerationState = {
       kind: 'puzzle',
@@ -116,6 +135,10 @@ describe('miniGameDraftGenerationProgress', () => {
     expect(progress?.overallProgress).toBe(98);
     expect(progress?.estimatedRemainingMs).toBe(0);
     expect(progress?.steps[5]?.completed).toBe(1);
+    expect(progress?.steps[5]?.status).toBe('completed');
+    expect(progress?.steps.every((step) => step.status === 'completed')).toBe(
+      true,
+    );
   });
 
   test('puzzle ready copy points to result page work info completion', () => {

src/services/miniGameDraftGenerationProgress.ts

@@ -484,7 +484,17 @@ function buildMiniGameProgressSteps(
   activeStepProgressRatio: number,
 ) {
   return steps.map((step, index) => {
-    const isCompleted = state.phase === 'ready' || index < activeStepIndex;
+    // 中文注释：拼图草稿编译的 action 回包才代表可进入结果页；
+    // 但预计写入时长已耗尽时，最后一步自身应呈现已完成，避免出现“进行中 100%”。
+    const isPuzzleWriteStepCompleted =
+      state.kind === 'puzzle' &&
+      state.phase !== 'failed' &&
+      step.id === 'puzzle-select-image' &&
+      clampProgress(activeStepProgressRatio * 100) >= 100;
+    const isCompleted =
+      state.phase === 'ready' ||
+      index < activeStepIndex ||
+      isPuzzleWriteStepCompleted;
     const isActive =
       state.phase !== 'failed' && !isCompleted && index === activeStepIndex;
     const isAssetStep = step.id === state.phase && state.totalAssetCount > 0;