From b89d4940a99c1366a38b7076f40a8ae9d8c5e495 Mon Sep 17 00:00:00 2001
From: kdletters <61648117+kdletters@users.noreply.github.com>
Date: Fri, 22 May 2026 16:09:01 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=E6=8B=BC=E5=9B=BE?=
 =?UTF-8?q?=E8=8D=89=E7=A8=BF=E5=86=99=E5=85=A5=E6=AD=A5=E9=AA=A4=E5=AE=8C?=
 =?UTF-8?q?=E6=88=90=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .hermes/shared-memory/pitfalls.md             |  8 +++++++
 ...�玩法创作】平�入�与玩法链路-2026-05-15.md |  2 +-
 .../miniGameDraftGenerationProgress.test.ts   | 23 +++++++++++++++++++
 .../miniGameDraftGenerationProgress.ts        | 12 +++++++++-
 4 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md
index 04bfcdd0..25c1b2df 100644
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.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。
diff --git a/docs/�玩法创作】平�入�与玩法链路-2026-05-15.md b/docs/�玩法创作】平�入�与玩法链路-2026-05-15.md
index dec72bac..ad3b3c28 100644
--- a/docs/�玩法创作】平�入�与玩法链路-2026-05-15.md
+++ b/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 秒展示。
diff --git a/src/services/miniGameDraftGenerationProgress.test.ts b/src/services/miniGameDraftGenerationProgress.test.ts
index 75a08bc7..0172b366 100644
--- a/src/services/miniGameDraftGenerationProgress.test.ts
+++ b/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', () => {
diff --git a/src/services/miniGameDraftGenerationProgress.ts b/src/services/miniGameDraftGenerationProgress.ts
index d21e7dc6..9d0060fe 100644
--- a/src/services/miniGameDraftGenerationProgress.ts
+++ b/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;