refactor: 收口拼图 runtime 状态合并

2026-06-04 05:24:16 +08:00
parent d44560f330
commit 4069fd5859
6 changed files with 284 additions and 39 deletions
--- a/.hermes/shared-memory/decision-log.md
+++ b/.hermes/shared-memory/decision-log.md
@@ -1444,6 +1444,14 @@
 - 验证方式：`npm run test -- src/components/platform-entry/platformPuzzleDraftRecoveryModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft"`、`npm run typecheck`、`npm run check:encoding`。
 - 关联文档：`docs/technical/【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

+## 2026-06-04 Platform Puzzle Runtime State Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 在拼图排行榜提交回包后内联合并服务端 run 快照，壳层需要理解 `PuzzleRunSnapshot` 中哪些字段由前端即时裁决、哪些字段只由服务端补齐。
+- 决策：新增 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts`，以 `mergePuzzleServiceRuntimeState(currentRun, serviceRun)` 收口服务端 run 合并规则。Module 保留当前前端关卡状态、棋盘和计时，只合并服务端 run 身份、`clearedLevelCount` 上限、排行榜与下一关 handoff；任一 run 缺 `currentLevel` 时直接返回当前 run。
+- 影响范围：拼图排行榜提交、推荐 runtime isolated / default 运行态回包合并、下一关同作品 / 相似作品 handoff，以及后续 Puzzle runtime 快照字段调整。
+- 验证方式：`npm run test -- src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-06-04 Puzzle Publish Asset Gate 收紧

 - 背景：后端拼图待发布门槛与前端历史恢复逻辑一样偏弱，只要求标题、描述、标签、关卡名和 cover，导致缺关卡画面、UI spritesheet 或关卡背景的半成品可能被标为 `publishReady` / `ready_to_publish`。
--- a/docs/README.md
+++ b/docs/README.md
@@ -63,6 +63,8 @@ AI 文字游戏模板接入以 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_

 平台拼图生成完成后刷新恢复的草稿归一化与可恢复完成态判定收口到 `src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts`，恢复链路只有在首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才抬为 ready，规则见 [【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md)。

+拼图排行榜提交回包后的服务端 run 快照合并收口到 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts`，只合并排行榜、run 身份、通关数上限和下一关 handoff，保留前端即时裁决的关卡状态与棋盘，规则见 [【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md)。
+
 后端拼图发布 / 待发布门槛收紧到首图、关卡画面、UI spritesheet 与关卡背景资产包完整，`module-puzzle` 的 preview blockers 与 `api-server` 的 session stage 判定保持同一规则，方案见 [【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md](./technical/【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md)。

 平台入口个人钱包本地 delta、dashboard 乐观更新与服务端快照对账规则收口到 `src/components/platform-entry/platformProfileWalletDeltaModel.ts`，平台壳只保留 API、ref 与 state 副作用，规则见 [【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md)。
--- a/docs/technical/【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md
+++ b/docs/technical/【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md
@@ -0,0 +1,36 @@
+# 【前端架构】Platform Puzzle Runtime State Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾内联 `mergePuzzleServiceRuntimeState(...)`，在拼图排行榜提交回包后，把服务端 run 快照合并回当前前端 run。此逻辑没有 React state、网络、URL 或弹窗副作用，却需要理解 `PuzzleRunSnapshot` 的局部真相分工：拼块布局、当前关卡状态和计时结果由前端即时裁决；服务端回包只补排行榜、run 身份、通关数上限和下一关 handoff。
+
+若该合并规则继续留在平台壳，后续调整排行榜来源、相似作品下一关或本地 / 服务端 run 混合策略时，维护者必须翻大型壳层并同时避开大量副作用代码。
+
+## 决策
+
+新增 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts` 作为 Platform Puzzle Runtime State **Module**。公开 **Interface**：
+
+- `mergePuzzleServiceRuntimeState(currentRun, serviceRun)`：当双方都有 `currentLevel` 时，保留当前前端关卡状态与棋盘，只合并服务端 run 身份、`clearedLevelCount` 上限、排行榜与下一关 handoff；任一方缺 `currentLevel` 时返回当前 run。
+
+`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它负责提交排行榜、读取回包、写 React state、刷新 archive 和错误提示，不再持有拼图 run 快照合并字段清单。
+
+## Interface 约束
+
+- 缺少 `currentRun.currentLevel` 或 `serviceRun.currentLevel` 时不得合并，直接返回当前 run。
+- `clearedLevelCount` 取当前 run 与服务端 run 的最大值，避免服务端较旧回包降低本地通关数。
+- 排行榜优先取 `serviceRun.currentLevel.leaderboardEntries`；为空时取 `serviceRun.leaderboardEntries`；两者皆空时保留当前关卡榜单。
+- `currentLevel` 的棋盘、状态、计时和关卡字段来自当前 run，不被服务端回包覆盖。
+- `runId`、`entryProfileId`、`recommendedNextProfileId`、`nextLevelMode`、`nextLevelProfileId`、`nextLevelId`、`recommendedNextWorks` 来自服务端 run。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层传入当前 run 与服务端 run，即取得合并后的稳定快照；排行榜来源、下一关 handoff 和前端局部真相保留规则藏入 Module Implementation。
+- **Leverage**：排行榜提交、后续相似作品推荐或服务端 run 字段变化时，先改纯 Module 与单测，壳层提交副作用不变。
+- **Locality**：拼图 runtime 快照合并规则集中到一个纯测试面，避免在平台壳中继续散落 `PuzzleRunSnapshot` 字段判断。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts`
+- `npx eslint src/components/platform-entry/platformPuzzleRuntimeStateModel.ts src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`
--- a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
+++ b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
@@ -589,6 +589,7 @@ import {
  buildPuzzleResultProfileId,
  buildPuzzleResultWorkId,
 } from './platformPuzzleIdentityModel';
+import { mergePuzzleServiceRuntimeState } from './platformPuzzleRuntimeStateModel';
 import {
  type PlatformPuzzleRuntimeAuthMode,
  resolvePlatformRecommendRuntimeAuthPlan,
@@ -1250,45 +1251,6 @@ function CreationResultRecoveryPanel({
  );
 }

-function mergePuzzleServiceRuntimeState(
-  currentRun: PuzzleRunSnapshot,
-  serviceRun: PuzzleRunSnapshot,
-): PuzzleRunSnapshot {
-  if (!currentRun.currentLevel || !serviceRun.currentLevel) {
-    return currentRun;
-  }
-
-  const serviceLevel = serviceRun.currentLevel;
-  const leaderboardEntries =
-    serviceLevel.leaderboardEntries.length > 0
-      ? serviceLevel.leaderboardEntries
-      : serviceRun.leaderboardEntries;
-
-  // 中文注释：拼块布局和通关状态由前端即时裁决；后端快照只合并榜单与下一关 handoff。
-  return {
-    ...currentRun,
-    runId: serviceRun.runId,
-    entryProfileId: serviceRun.entryProfileId,
-    clearedLevelCount: Math.max(
-      currentRun.clearedLevelCount,
-      serviceRun.clearedLevelCount,
-    ),
-    recommendedNextProfileId: serviceRun.recommendedNextProfileId,
-    nextLevelMode: serviceRun.nextLevelMode,
-    nextLevelProfileId: serviceRun.nextLevelProfileId,
-    nextLevelId: serviceRun.nextLevelId,
-    recommendedNextWorks: serviceRun.recommendedNextWorks,
-    leaderboardEntries,
-    currentLevel: {
-      ...currentRun.currentLevel,
-      leaderboardEntries:
-        leaderboardEntries.length > 0
-          ? leaderboardEntries
-          : currentRun.currentLevel.leaderboardEntries,
-    },
-  };
-}
-
 export function PlatformEntryFlowShellImpl({
  selectionStage,
  setSelectionStage,
--- a/src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts
+++ b/src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts
@@ -0,0 +1,197 @@
+import { describe, expect, test } from 'vitest';
+
+import type {
+  PuzzleLeaderboardEntry,
+  PuzzleRunSnapshot,
+  PuzzleRuntimeLevelSnapshot,
+} from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
+import { mergePuzzleServiceRuntimeState } from './platformPuzzleRuntimeStateModel';
+
+const currentLeaderboard: PuzzleLeaderboardEntry[] = [
+  {
+    rank: 1,
+    nickname: '本地玩家',
+    elapsedMs: 12000,
+    isCurrentPlayer: true,
+  },
+];
+
+const serviceLevelLeaderboard: PuzzleLeaderboardEntry[] = [
+  {
+    rank: 1,
+    nickname: '服务端玩家',
+    elapsedMs: 9000,
+  },
+];
+
+const serviceRunLeaderboard: PuzzleLeaderboardEntry[] = [
+  {
+    rank: 2,
+    nickname: '全局玩家',
+    elapsedMs: 15000,
+  },
+];
+
+function buildPuzzleLevel(
+  overrides: Partial<PuzzleRuntimeLevelSnapshot> = {},
+): PuzzleRuntimeLevelSnapshot {
+  return {
+    runId: 'run-current',
+    levelIndex: 0,
+    levelId: 'level-1',
+    gridSize: 3,
+    profileId: 'puzzle-profile-current',
+    levelName: '星桥机关',
+    authorDisplayName: '玩家',
+    themeTags: ['星桥'],
+    coverImageSrc: '/cover.png',
+    board: {
+      rows: 3,
+      cols: 3,
+      pieces: [],
+      mergedGroups: [],
+      selectedPieceId: null,
+      allTilesResolved: true,
+    },
+    status: 'cleared',
+    startedAtMs: 1000,
+    clearedAtMs: 13000,
+    elapsedMs: 12000,
+    timeLimitMs: 120000,
+    remainingMs: 108000,
+    pausedAccumulatedMs: 0,
+    pauseStartedAtMs: null,
+    freezeAccumulatedMs: 0,
+    freezeStartedAtMs: null,
+    freezeUntilMs: null,
+    leaderboardEntries: currentLeaderboard,
+    ...overrides,
+  };
+}
+
+function buildPuzzleRun(
+  overrides: Partial<PuzzleRunSnapshot> = {},
+): PuzzleRunSnapshot {
+  return {
+    runId: 'run-current',
+    entryProfileId: 'puzzle-profile-current',
+    clearedLevelCount: 1,
+    currentLevelIndex: 0,
+    currentGridSize: 3,
+    playedProfileIds: ['puzzle-profile-current'],
+    previousLevelTags: ['星桥'],
+    currentLevel: buildPuzzleLevel(),
+    recommendedNextProfileId: null,
+    nextLevelMode: 'sameWork',
+    nextLevelProfileId: null,
+    nextLevelId: null,
+    recommendedNextWorks: [],
+    leaderboardEntries: currentLeaderboard,
+    ...overrides,
+  };
+}
+
+describe('platformPuzzleRuntimeStateModel', () => {
+  test('keeps current run when either current level is missing', () => {
+    const currentRun = buildPuzzleRun({ currentLevel: null });
+    expect(
+      mergePuzzleServiceRuntimeState(currentRun, buildPuzzleRun()),
+    ).toBe(currentRun);
+
+    const serviceRun = buildPuzzleRun({ currentLevel: null });
+    const playableCurrentRun = buildPuzzleRun();
+    expect(
+      mergePuzzleServiceRuntimeState(playableCurrentRun, serviceRun),
+    ).toBe(playableCurrentRun);
+  });
+
+  test('merges service leaderboard and next-level handoff without replacing local level state', () => {
+    const currentRun = buildPuzzleRun({
+      clearedLevelCount: 2,
+      currentLevel: buildPuzzleLevel({
+        runId: 'run-current',
+        status: 'cleared',
+        board: {
+          rows: 3,
+          cols: 3,
+          pieces: [
+            {
+              pieceId: 'piece-local',
+              correctRow: 0,
+              correctCol: 0,
+              currentRow: 0,
+              currentCol: 0,
+              mergedGroupId: null,
+            },
+          ],
+          mergedGroups: [],
+          selectedPieceId: 'piece-local',
+          allTilesResolved: true,
+        },
+      }),
+    });
+    const serviceRun = buildPuzzleRun({
+      runId: 'run-service',
+      entryProfileId: 'puzzle-profile-service',
+      clearedLevelCount: 1,
+      recommendedNextProfileId: 'next-recommended',
+      nextLevelMode: 'similarWorks',
+      nextLevelProfileId: 'next-profile',
+      nextLevelId: 'next-level',
+      recommendedNextWorks: [
+        {
+          profileId: 'next-profile',
+          levelName: '月桥机关',
+          authorDisplayName: '推荐作者',
+          themeTags: ['月桥'],
+          coverImageSrc: '/next-cover.png',
+          similarityScore: 0.91,
+        },
+      ],
+      currentLevel: buildPuzzleLevel({
+        runId: 'run-service-level',
+        status: 'playing',
+        leaderboardEntries: serviceLevelLeaderboard,
+      }),
+    });
+
+    const merged = mergePuzzleServiceRuntimeState(currentRun, serviceRun);
+
+    expect(merged.runId).toBe('run-service');
+    expect(merged.entryProfileId).toBe('puzzle-profile-service');
+    expect(merged.clearedLevelCount).toBe(2);
+    expect(merged.recommendedNextProfileId).toBe('next-recommended');
+    expect(merged.nextLevelMode).toBe('similarWorks');
+    expect(merged.nextLevelProfileId).toBe('next-profile');
+    expect(merged.nextLevelId).toBe('next-level');
+    expect(merged.recommendedNextWorks).toEqual(serviceRun.recommendedNextWorks);
+    expect(merged.leaderboardEntries).toEqual(serviceLevelLeaderboard);
+    expect(merged.currentLevel?.status).toBe('cleared');
+    expect(merged.currentLevel?.board.pieces).toEqual(
+      currentRun.currentLevel?.board.pieces,
+    );
+    expect(merged.currentLevel?.leaderboardEntries).toEqual(
+      serviceLevelLeaderboard,
+    );
+  });
+
+  test('falls back to service run leaderboard, then current level leaderboard', () => {
+    const currentRun = buildPuzzleRun();
+    const serviceRun = buildPuzzleRun({
+      currentLevel: buildPuzzleLevel({ leaderboardEntries: [] }),
+      leaderboardEntries: serviceRunLeaderboard,
+    });
+
+    expect(
+      mergePuzzleServiceRuntimeState(currentRun, serviceRun).currentLevel
+        ?.leaderboardEntries,
+    ).toEqual(serviceRunLeaderboard);
+
+    expect(
+      mergePuzzleServiceRuntimeState(currentRun, {
+        ...serviceRun,
+        leaderboardEntries: [],
+      }).currentLevel?.leaderboardEntries,
+    ).toEqual(currentLeaderboard);
+  });
+});
--- a/src/components/platform-entry/platformPuzzleRuntimeStateModel.ts
+++ b/src/components/platform-entry/platformPuzzleRuntimeStateModel.ts
@@ -0,0 +1,40 @@
+import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
+
+export function mergePuzzleServiceRuntimeState(
+  currentRun: PuzzleRunSnapshot,
+  serviceRun: PuzzleRunSnapshot,
+): PuzzleRunSnapshot {
+  if (!currentRun.currentLevel || !serviceRun.currentLevel) {
+    return currentRun;
+  }
+
+  const serviceLevel = serviceRun.currentLevel;
+  const leaderboardEntries =
+    serviceLevel.leaderboardEntries.length > 0
+      ? serviceLevel.leaderboardEntries
+      : serviceRun.leaderboardEntries;
+
+  // 中文注释：拼块布局和通关状态由前端即时裁决；后端快照只合并榜单与下一关 handoff。
+  return {
+    ...currentRun,
+    runId: serviceRun.runId,
+    entryProfileId: serviceRun.entryProfileId,
+    clearedLevelCount: Math.max(
+      currentRun.clearedLevelCount,
+      serviceRun.clearedLevelCount,
+    ),
+    recommendedNextProfileId: serviceRun.recommendedNextProfileId,
+    nextLevelMode: serviceRun.nextLevelMode,
+    nextLevelProfileId: serviceRun.nextLevelProfileId,
+    nextLevelId: serviceRun.nextLevelId,
+    recommendedNextWorks: serviceRun.recommendedNextWorks,
+    leaderboardEntries,
+    currentLevel: {
+      ...currentRun.currentLevel,
+      leaderboardEntries:
+        leaderboardEntries.length > 0
+          ? leaderboardEntries
+          : currentRun.currentLevel.leaderboardEntries,
+    },
+  };
+}