Merge codex/sse-stream-architecture into architecture adjustment

.hermes/shared-memory/decision-log.md

@@ -81,6 +81,153 @@
 - 验证方式：关闭任一创作入口后，新建创作请求返回 `creation_entry_disabled`；公开作品列表 / 详情 / 启动 / 运行态动作不返回该错误；进入平台首页不弹“平台首页：creation_entry_disabled”；关闭态入口卡显示锁定状态且不显示 `10-20泥点数`。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-06-04 Draft Generation Shelf 剩余草稿打开 intent 收口
+
+- 背景：拼图 / 抓大鹅草稿打开 intent 已归入 `platformDraftGenerationShelfModel.ts`，但方洞挑战、大鱼吃小鱼和视觉小说仍在平台壳层内联判断已发布详情、缺 session、active generating、当前结果页和普通草稿恢复。
+- 决策：继续扩展 `src/components/platform-entry/platformDraftGenerationShelfModel.ts`，新增 `resolveSquareHoleDraftOpenIntent(...)`、`resolveBigFishDraftOpenIntent(...)` 与 `resolveVisualNovelDraftOpenIntent(...)`；平台壳只按 intent 执行 notice seen、详情打开、恢复 session、读取 work detail、清生成态和切 stage 副作用。
+- 追加决策：跳一跳与敲木鱼草稿打开也归入同一 Draft Generation Shelf Model，新增 `resolveJumpHopDraftOpenIntent(...)` 与 `resolveWoodenFishDraftOpenIntent(...)`；壳层只按 intent 执行已发布详情、失败生成页恢复、持久化 generating 恢复、读取 detail 和敲木鱼失败 fallback stage 副作用。
+- 影响范围：创作中心作品架打开方洞挑战 / 大鱼吃小鱼 / 视觉小说 / 跳一跳 / 敲木鱼草稿、创作 URL 恢复时强制打开草稿、生成中回到生成页和视觉小说结果页恢复。
+- 验证方式：`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对 Draft Shelf Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md`。
+
+## 2026-06-04 Platform Public Code Search matcher / DTO 收口
+
+- 背景：`resolvePlatformPublicCodeSearchPlan(...)` 已收口公开搜索顺序，但 `PlatformEntryFlowShellImpl.tsx` 仍内联 RPG by-code DTO 构造，以及拼图、大鱼吃小鱼、跳一跳、敲木鱼、宝贝识物、抓大鹅、方洞挑战、视觉小说和汪汪声浪的 `isSame*PublicWorkCode` 匹配、公开可见性过滤与详情卡映射。
+- 决策：扩展 `src/components/platform-entry/platformPublicCodeSearchModel.ts`，以 `mapRpgPublicCodeSearchDetailToGalleryCard(...)` 和各 `resolve*PublicCodeSearchMatch(...)` 收口 per-play 公开码匹配与 DTO 映射；壳层只保留 gallery 刷新、详情打开、Bark Battle runtime 特例、用户查询和错误归航副作用。`M3D-*` 旧抓大鹅前缀在 `isSameMatch3DPublicWorkCode(...)` 中继续匹配。
+- 影响范围：平台首页搜索框、初始 `publicWorkCode` 恢复、各玩法公开作品号命中、RPG 公开作品 by-code 详情映射、Bark Battle runtime 内搜索启动。
+- 验证方式：`npm run test -- src/components/platform-entry/platformPublicCodeSearchModel.test.ts src/services/publicWorkCode.test.ts`、针对搜索 Module / 壳层 / publicWorkCode 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Draft Generation Shelf 草稿打开 intent 收口
+
+- 背景：`openPuzzleDraft` / `openMatch3DDraft` 在平台壳内重复判断已发布作品、缺 session、ready 未读、失败 notice、active / background 生成中、持久化 generating 和普通草稿恢复，导致壳层继续理解拼图稳定 ID、抓大鹅 notice key 与生成状态优先级。
+- 决策：扩展 `src/components/platform-entry/platformDraftGenerationShelfModel.ts`，以 `resolvePuzzleDraftOpenIntent(...)` 与 `resolveMatch3DDraftOpenIntent(...)` 返回纯打开计划和 notice keys；壳层只按 intent 执行网络读取、生成态 rebase、试玩启动、错误写入、路由 / stage 和 notice seen 副作用。
+- 影响范围：创作中心作品架打开拼图 / 抓大鹅草稿、公开码搜索强制打开抓大鹅草稿、生成完成后 ready 未读试玩、失败草稿恢复和后续 pending / persisted generating 判定。
+- 验证方式：`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对 Draft Shelf Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md`。
+
+## 2026-06-04 Bark Battle Work Cache 草稿状态收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 仍内联维护 Bark Battle 草稿三图完整性、生成状态归一、作品架摘要恢复草稿配置，以及草稿 / 已发布作品进入 runtime 前的 `BarkBattlePublishedConfig` 字段映射，导致结果页试玩、作品架启动、草稿恢复和公开详情启动都要理解同一份资产字段清单。
+- 决策：扩展 `src/components/platform-entry/barkBattleWorkCache.ts`，以 `hasBarkBattleDraftRequiredImages`、`resolveBarkBattleDraftGenerationStatus`、`buildBarkBattleDraftConfigFromWorkSummary`、`buildBarkBattlePublishedConfigFromDraft`、`buildBarkBattlePublishedConfigFromWork`、`buildBarkBattlePublishSnapshot` 和 `mergeBarkBattlePublishedConfigAssets` 收口 Bark Battle 纯规则。平台壳只保留 API、缓存刷新、React state、URL 和 stage 副作用。
+- 影响范围：Bark Battle 草稿生成完成、结果页保存、作品架摘要恢复草稿、草稿试玩、作品架 / 公开详情启动正式 runtime，以及后续 Bark Battle 资产字段或 ruleset 默认值调整。
+- 验证方式：`npm run test -- src/components/platform-entry/barkBattleWorkCache.test.ts`、针对 Bark Battle Work Cache Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md`。
+
+## 2026-06-04 Platform Recommend Runtime Auth Model 收口
+
+- 背景：平台推荐 runtime 的 embedded 启动需要在匿名 Runtime Guest Token、已登录 background auth 和非 embedded 默认鉴权之间分流，拼图还额外维护 `isolated` / `default` runtime auth mode；旧规则散在顶层 helper 与多个启动 callback。
+- 决策：新增 `src/components/platform-entry/platformRecommendRuntimeAuthModel.ts`，以 `resolvePlatformRecommendRuntimeAuthPlan(input)` 和 `shouldUsePlatformRecommendRuntimeGuestAuth(input)` 收口纯鉴权计划。壳层仍负责读取 `getStoredAccessToken()`、申请 `ensureRuntimeGuestToken()`、拼装 request options 和写入拼图 runtime auth mode。
+- 影响范围：推荐 Tab 内嵌 runtime 启动、拼图公开详情 isolated 入口、推荐运行态后续 action 的局部鉴权口径，以及后续新增可嵌入推荐 runtime 的玩法。
+- 验证方式：`npm run test -- src/components/platform-entry/platformRecommendRuntimeAuthModel.test.ts`、针对新 Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md`。
+
+## 2026-06-04 Platform Recommend Runtime Auto Start 收口
+
+- 背景：推荐 runtime 自动启动 effect 同时判断桌面断点、stage、Tab、loading、推荐列表、active entry、ready 状态和启动中状态，导致壳层 effect 依赖过长且混合推荐流状态机知识。
+- 决策：扩展 `src/components/platform-entry/platformPublicGalleryFlow.ts`，新增 `resolvePlatformRecommendRuntimeAutoStartDecision(input)`，只返回 `noop`、`clear` 或 `start(entry)`。平台壳只执行清空 active runtime state 或调用 `selectRecommendRuntimeEntry(entry)`。
+- 影响范围：移动端首页推荐 runtime 自动启动、推荐列表为空时清空状态、active entry ready 判定，以及后续新增推荐 runtime 玩法的启动时机。
+- 验证方式：`npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`、针对 Flow Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md`。
+
+## 2026-06-04 Platform Creation Launch Model 收口
+
+- 背景：平台创作入口点击回调曾在 `PlatformEntryFlowShellImpl.tsx` 内联判断 `airp` 占位、隐藏的 `baby-object-match`、未知入口和各玩法工作台启动目标，壳层同时承接入口 ID 规则、启动前准备顺序和副作用。
+- 决策：新增 `src/components/platform-entry/platformCreationLaunchModel.ts`，以 `resolvePlatformCreationLaunchIntent({ type, isBabyObjectMatchVisible })` 收口创作入口启动意图。`airp` 返回 `noop` 且不触发 `prepareCreationLaunch()`；隐藏 `baby-object-match` 返回 blocked intent 且仍在 prepare 后显示 `EDUTAINMENT_HIDDEN_MESSAGE`；未知入口保持旧语义，先 prepare 后 no-op；已知入口返回稳定 launch target。壳层只执行 prepare、错误提示和 `runProtectedAction(...)`。
+- 影响范围：底部加号创作入口模板卡点击、入口可见性拦截、后续新增可启动模板的 launch target 接入。
+- 验证方式：`npm run test -- src/components/platform-entry/platformCreationLaunchModel.test.ts`、针对新 Module 与壳层执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md`。
+
+## 2026-06-04 Platform Selection Stage Model 收口
+
+- 背景：平台入口在受保护数据失效后会清空当前用户私有作品、草稿、运行态和生成状态，但哪些 `SelectionStage` 可保留、哪些必须回首页曾以内联长否定串散在 `PlatformEntryFlowShellImpl.tsx`。
+- 决策：新增 `src/components/platform-entry/platformSelectionStageModel.ts`，以 `resolveSelectionStageAfterProtectedDataLoss(stage)` 收口受保护数据失效后的 stage 去留判定。模型内部使用 `satisfies Record<SelectionStage, boolean>` 全量分类，新增 stage 时必须明确保留或回首页。壳层仍负责检测权限变化、清 state 和调用 `setSelectionStage`。
+- 追加决策：缺失草稿 / 作品 / run 时的阶段回退也归入 `platformSelectionStageModel.ts`，由 `resolveSelectionStageAfterMissingCreationState(params)` 统一判断 big-fish、match3d、square-hole、visual-novel 和 baby-object-match 的 result / runtime / gallery-detail 是否还能被当前状态支撑。壳层只汇总布尔事实并按输出 stage 跳转；big-fish、match3d、square-hole 的草稿事实固定来自 `Boolean(session?.draft)`，visual-novel 的 session draft 与 work draft 可独立支撑结果页，baby-object-match runtime 缺 draft 时直接回首页。
+- 影响范围：退出登录、鉴权上下文收回、平台入口公开页 / 工作台 / 结果页 / 生成页 / 运行态的阶段恢复规则，以及后续新增 `SelectionStage`。
+- 验证方式：`npm run test -- src/components/platform-entry/platformSelectionStageModel.test.ts`、针对新 Module 与壳层执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md`。
+
+## 2026-06-04 Creation Work Delete Flow 收口
+
+- 背景：平台入口作品架删除入口在 RPG、拼图、抓大鹅、方洞挑战、大鱼吃小鱼、视觉小说和宝贝识物 handler 内重复计算确认标题、删除说明、草稿 notice key 与拼图派生稳定 ID，导致删除确认规则散在巨型壳层。
+- 决策：新增 `src/components/platform-entry/platformCreationWorkDeleteFlow.ts`，以 `resolvePlatformCreationWorkDeleteConfirmationModel(input)` 收口作品架删除确认纯模型；输出 `id/title/detail/noticeKeys`。`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 Adapter，保留删除 API、刷新作品架 / 公开广场、错误状态、`markDraftNoticeSeen` 和页面跳转。
+- 影响范围：创作中心作品架删除确认弹窗、删除后生成 notice 清理、拼图稳定 result ID 清理、宝贝识物已发布删除说明，以及后续新增玩法作品架删除接入。
+- 验证方式：`npm run test -- src/components/platform-entry/platformCreationWorkDeleteFlow.test.ts`、`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对新 Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md`。
+
+## 2026-06-03 平台入口公开作品详情 Strategy 收口
+
+- 背景：平台壳层直接判断公开作品详情入口的玩法类型、是否需要补读完整详情，以及自有作品按钮显示“编辑”还是“改造”，导致统一作品详情的纯决策散落在巨型 Implementation 内。
+- 决策：新增 `src/components/platform-entry/platformPublicWorkDetailFlow.ts`，以 `getPlatformPublicWorkDetailKind`、`resolvePlatformPublicWorkDetailOpenStrategy`、`resolvePlatformPublicWorkActionMode`、`resolvePlatformPublicWorkDetailOpenDecision` 和 `resolveActivePlatformPublicWorkAuthorEntry` 收口公开作品详情 Strategy。`PlatformEntryFlowShellImpl.tsx` 只按 Strategy 调用现有详情读取 / 直接展示 Adapter，并保留作者请求竞态控制；启动、点赞、remix 和编辑副作用不搬入 Module。
+- 追加决策：公开详情 entry 映射与公开详情反推玩法 work 摘要也归入 `platformPublicWorkDetailFlow.ts`，包括 RPG、拼图、大鱼吃小鱼、方洞挑战、视觉小说、跳一跳、敲木鱼和汪汪声浪的通用映射。抓大鹅 `mapMatch3DWorkToPublicWorkDetail` 归入 `platformMatch3DRuntimeProfile.ts`，继续委托 `normalizeMatch3DWorkForRuntimeUi` 做素材归一和背景资产提升，避免把 Match3D 运行态规则复制到公开详情 Flow Module。
+- 追加决策：拼图公开详情封面解锁数由 `resolveVisiblePuzzleDetailCoverCount(entry, run)` 收口；非拼图、无当前 run 或 run 不匹配当前公开详情时只展示首图，匹配当前公开详情时按 `clearedLevelCount + 1` 解锁且至少为 1。`PlatformWorkDetailView` 只接收 `visibleCoverCount` 展示，不读取 run。
+- 追加决策：公开详情点赞能力矩阵由 `resolvePlatformPublicWorkLikeIntent(entry)` 收口；Module 只返回大鱼吃小鱼、拼图、旧 RPG gallery fallback 或不可用文案，壳层仍执行鉴权、API 调用、缓存同步、错误展示和 busy 状态。
+- 追加决策：公开详情改造能力矩阵由 `resolvePlatformPublicWorkRemixIntent(entry)` 收口；Module 只返回大鱼吃小鱼、拼图、旧 RPG gallery fallback 或不可用文案，壳层仍执行鉴权、remix API、session / 缓存写入、stage 切换、错误展示和 busy 状态。
+- 追加决策：公开详情启动分流由 `resolvePlatformPublicWorkStartIntent(entry, deps)` 收口；Module 只返回大鱼吃小鱼、拼图、跳一跳、敲木鱼、抓大鹅、方洞挑战、视觉小说、汪汪声浪、宝贝识物或旧 RPG gallery 记录游玩的 intent。壳层仍执行登录保护、运行态启动、RPG 游玩记录、详情更新、busy 状态和错误展示；抓大鹅 public detail -> work mapper 作为 Adapter 注入，继续由 Match3D Runtime Profile Module 维护素材归一与背景资产提升。
+- 追加决策：自有公开作品编辑分流由 `resolvePlatformPublicWorkEditIntent(entry, deps)` 收口；Module 只返回可编辑草稿目标、需解析宝贝识物本地草稿 intent、旧 RPG gallery 编辑 intent 或原阻断文案。壳层仍执行登录保护、草稿恢复、宝贝识物异步草稿解析、RPG 编辑导航和错误展示；抓大鹅 public detail -> work mapper 仍作为 Adapter 注入，不复制 Match3D 素材归一规则。
+- 影响范围：统一作品详情入口、公开详情打开策略、自有公开作品编辑 / 改造动作模式，以及后续新增玩法公开详情接入。
+- 验证方式：`npm run test -- src/components/platform-entry/platformPublicWorkDetailFlow.test.ts`、`npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`、公开详情壳层交互回归、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md`。
+
+## 2026-06-03 平台入口弹窗状态规则收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 曾同时持有平台级错误 / 完成弹窗的文案归一、来源格式、候选择一、dismiss key、后台生成 still-running 识别和任务完成文案，导致壳层 Interface 偏浅，测试面不稳定。
+- 决策：新增 `src/components/platform-entry/platformDialogStateModel.ts` 作为 Platform Dialog State Module，统一导出 `normalizePlatformDialogMessage`、`formatPlatformDialogSource`、`resolvePlatformErrorDialog`、dismiss key builder、`resolveActivePlatformDialog`、`isBackgroundGenerationStillRunningMessage` 和 `PLATFORM_TASK_COMPLETION_MESSAGE`。平台壳只汇总候选、持有 React state，并在关闭弹窗时作为 Adapter 清理对应副作用 setter。
+- 影响范围：平台入口错误弹窗、任务完成弹窗、后台生成仍在处理识别、草稿生成完成 / 失败通知。
+- 验证方式：`npm run test -- src/components/platform-entry/platformDialogStateModel.test.ts`、`npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx`、相关壳层交互测试、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md`。
+
+## 2026-06-03 前端 SSE 客户端传输层统一收口
+
+- 背景：创作 Agent、创意互动 Agent、视觉小说运行态和微信充值订单状态等多个前端 client 曾各自手写 SSE 边界扫描、`TextDecoder` 解码、JSON 解析和流结束 flush，导致 CRLF / LF、UTF-8 尾部、多行 `data:` 和提前停止释放 reader 的处理容易漂移。
+- 决策：前端 SSE 传输层统一使用 `src/services/sseStream.ts`；`readSseStream` 负责事件边界、解码 flush、多行 data 和提前停止取消 reader，`readSseJsonStream` 负责 JSON object 事件解析与异常 JSON 静默跳过。业务 client 只保留领域事件归一化、结果聚合和中文错误文案，OpenAI 兼容文本流通过 `readSseStream` 处理 `[DONE]` 哨兵，后续不得复制 `findSseEventBoundary`、`parseSseEventBlock` 或手写 reader 循环。
+- 影响范围：`src/services/sseStream.ts`、`src/services/aiService.ts`、`src/services/llmClient.ts`、`src/services/creation-agent/creationAgentSse.ts`、`src/services/creative-agent/creativeAgentSse.ts`、`src/services/visual-novel-runtime/visualNovelRuntimeSse.ts`、`src/services/rpg-entry/rpgProfileClient.ts`、前端 SSE 相关测试与架构文档。
+- 验证方式：`npm run test -- src/services/sseStream.test.ts src/services/llmClient.test.ts src/services/creation-agent/creationAgentSse.test.ts src/services/creative-agent/creativeAgentSse.test.ts src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts src/services/rpg-entry/rpgProfileClient.test.ts src/services/ai.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 `npx eslint ... --max-warnings 0` 通过。
+- 关联文档：`docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md`。
+
+## 2026-06-03 平台入口公开作品流身份规则收口
+
+- 背景：平台入口公开作品推荐流需要同时处理 RPG、拼图、抓大鹅、跳一跳、敲木鱼、视觉小说、Bark Battle、宝贝识物等卡片，公开作品身份、跨玩法去重、排序和推荐运行态 kind 判定曾放在 `PlatformEntryFlowShellImpl.tsx` 巨型实现里。
+- 决策：公开作品身份、排序规则、公开作品流聚合矩阵、推荐 runtime 启动意图和 ready 判定统一收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`；入口壳层只调用该 Module 的 `getPlatformPublicGalleryEntryKey`、`getPlatformRecommendRuntimeKind`、`buildPlatformPublicGalleryFeeds`、`resolvePlatformRecommendRuntimeStartIntent`、`isPlatformRecommendRuntimeReadyForEntry`、`isSamePlatformPublicGalleryEntry` 和 `mergePlatformPublicGalleryEntries`。`edutainment` key 必须带 `templateId`，RPG 卡片回退为 `rpg`。公开作品流聚合负责 featured / latest、玩法可见性 gate、汪汪声浪 works fallback 和首屏 `slice(0, 6)`；推荐 runtime 启动 intent 只返回启动目标、`embedded` / `returnStage` 参数、阻断文案和错误落点；ready 判定只接布尔值与拼图 profile id，避免把各玩法 run snapshot 类型拖入 Module。壳层仍执行 request key、运行态 API、错误 setter 与 UI 状态。
+- 影响范围：平台入口推荐流、最新公开作品流、公开作品详情、推荐 runtime 启动、跨玩法公开作品合并，以及后续新增玩法的入口接入。
+- 验证方式：`npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
+- 关联文档：`docs/technical/【前端架构】平台入口PublicGalleryFlowModule收口计划-2026-06-03.md`。
+
+## 2026-06-03 Work Shelf 打开动作交由 item Adapter
+
+- 背景：`creationWorkShelf.ts` 已经为每个 `CreationWorkShelfItem` 生成 `actions.open`，但 `CustomWorldCreationHub.tsx` 点击卡片后仍按 `item.source.kind` 重复分发 RPG、拼图、抓大鹅、方洞、跳一跳、敲木鱼、视觉小说、Bark Battle 和宝贝识物的打开逻辑。
+- 决策：`CreationWorkShelfItem.actions.open` 作为作品架打开动作的正式 Interface；Hub 只保留 `onOpenShelfItem` 通知和 `item.actions.open()` 调用，不再读取玩法 kind 做打开分支。`buildCreationWorkShelfItemsFromSources` 与 `CreationWorkShelfSourceAdapter` 作为 source registry Interface，统一执行 flatten、运行态覆盖、持久化生成态兜底和更新时间排序；旧 `buildCreationWorkShelfItems` 保留兼容，但内部改为组装 source adapters。
+- 影响范围：创作中心作品架卡片点击、作品架动作 Adapter、source registry、后续新增玩法作品架接入。
+- 验证方式：`npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
+- 关联文档：`docs/technical/【前端架构】WorkShelfModule收口计划-2026-06-03.md`。
+
+## 2026-06-03 Runtime Client Family 请求骨架收口
+
+- 背景：Match3D、SquareHole、Puzzle、Jump Hop 等 runtime client 重复手写 path segment 编码、JSON header / body、runtime guest token、auth options 和 retry options，新增玩法容易遗漏同一请求骨架。
+- 决策：新增 `src/services/runtimeRequest.ts`，以 `buildRuntimeApiPath` 统一 runtime path 编码，以 `requestRuntimeJson` 统一 JSON 请求、runtime guest auth 和 retry 合并。Match3D 与 SquareHole runtime client 已先迁移，保留原导出函数名、错误文案、返回契约和重试常量。
+- 追加决策：Big Fish 与 Bark Battle runtime client 也迁入 `runtimeRequest.ts`；玩法专属 payload 归一化（如 Bark Battle start / finish 自动补 `workId`、`runId`）仍留在各玩法 client，通用 Module 只承接请求骨架。
+- 追加决策：Puzzle 的 start / get / swap / drag / next-level / leaderboard 与 Jump Hop 的 start / jump / restart 也迁入 `runtimeRequest.ts`；Puzzle `pause` 与 `props` 仍保留原账号态 auth options，不直接接入 runtime guest auth。
+- 追加决策：Wooden Fish 的 start / checkpoint / finish 与 Visual Novel 的 gallery / run / history / regenerate JSON 请求也迁入 `runtimeRequest.ts`；Wooden Fish 的 `clientEventId` 生成仍留在木鱼 client，Visual Novel start 因 `timeoutMs`、SSE 因流式 `fetchWithApiAuth` 仍暂留原实现。
+- 影响范围：`src/services/runtimeRequest.ts`、Match3D / SquareHole / Big Fish / Bark Battle / Puzzle / Jump Hop / Wooden Fish / Visual Novel runtime client。
+- 验证方式：`npm run test -- src/services/runtimeRequest.test.ts src/services/recommendedRuntimeGuestLaunch.test.ts src/services/match3d-runtime/match3dRuntimeAdapter.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
+- 关联文档：`docs/technical/【前端架构】RuntimeClientFamily收口计划-2026-06-03.md`。
+
+## 2026-06-03 Public Gallery ViewModel 收口
+
+- 背景：`RpgEntryHomeView.tsx` 巨型页面内混合了公开作品分类、跨来源去重、搜索归一化、作品号匹配、时间戳解析和排序规则，新增玩法时页面与 ViewModel 规则容易纠缠。
+- 决策：新增 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，把 `buildPublicGalleryCardKey`、`buildPublicCategoryGroups`、`getPlatformPublicEntries`、`getAllPlatformPublicEntries`、`getPlatformSearchableWorkIds`、`filterPlatformWorkSearchResults`、`isExactPublicWorkCodeSearch`、`filterTodayPublishedEntries`、公开卡片指标 getter、`buildPlatformRankingEntries`、`getPlatformRankingMetricValue`、`getPlatformCategoryKindFilter`、`matchesPlatformCategoryKindFilter`、`sortPlatformCategoryEntries`、`getPlatformCategoryPrimaryMetric`、`parsePlatformEntryTimestamp` 和 `getPlatformWorldTimestamp` 收口为公开作品 ViewModel Interface。公开作品 key 复用平台入口身份规则，补齐 jump-hop / wooden-fish 等玩法区分。
+- 影响范围：RPG 首页公开作品发现、分类、搜索、排行数据准备，以及后续新增玩法公开卡片接入。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
+- 关联文档：`docs/technical/【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md`。
+
+## 2026-06-03 Profile Task ViewModel 收口
+
+- 背景：`RpgEntryHomeView.tsx` 同时持有每日任务卡片和任务中心弹窗的任务选择、进度 clamp、奖励兜底、状态标签和按钮文案，导致任务展示规则和 JSX 缠在一起。
+- 决策：新增 `src/components/rpg-entry/rpgEntryProfileTaskViewModel.ts`，把 `selectProfileTaskCenterTasks`、`selectProfileTaskCardTask`、`buildProfileTaskCardSummary`、`buildProfileTaskProgressLabel`、`getProfileTaskStatusLabel` 和 `getProfileTaskClaimButtonLabel` 收口为每日任务 ViewModel Interface。任务中心仍只展示一条 claimable / incomplete 优先任务，任务卡按可操作、claimed、非 disabled 的顺序兜底。
+- 影响范围：RPG 首页“每日任务”卡片、任务中心弹窗、后续任务状态和任务展示文案调整。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryProfileTaskViewModel.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
+- 关联文档：`docs/technical/【前端架构】ProfileTaskViewModel收口计划-2026-06-03.md`。
+
 ## 2026-06-03 最近创作只复用创作模板入口
 
 - 背景：底部加号创作入口的“最近创作”最初由真实作品架摘要驱动，但页面曾按作品标题、摘要和生成状态渲染独立最近创作卡，和其它模板页签的卡片样式及点击语义不一致。
@@ -240,7 +387,7 @@
 ## 2026-05-26 推荐页拼图下一关 pending 时保留当前运行态
 
 - 背景：推荐页嵌入拼图在点击“下一关”时，`advancePuzzleNextLevel` 的服务端请求会短暂处于 pending。旧逻辑把推荐卡的 `isStartingRecommendEntry` 和拼图局部 busy 混在一起，导致外层直接切回“加载中...”，把当前 `PuzzleRuntimeShell` 一起卸载，视觉上像是切关闪回。
-- 决策：推荐页嵌入拼图切关 pending 期间必须保留当前运行态与棋盘，只让拼图壳内部 busy 表现承接同步；`isStartingRecommendEntry` 只表示推荐作品尚未真正启动出来，不再把已有嵌入拼图 run 的局部 busy 一并当成整卡加载态。若下一关落到相似作品，前端还必须把新作品写回推荐缓存并同步 `activeRecommendEntryKey`，避免运行态进入新作品但推荐卡元信息、分享 / 点赞 / 改造和后续“下一个”仍锚定旧作品；但这个同步仍属于同一个 run 内部推进，不得触发推荐 rail 切卡动画、纵向位移或启动封面重置。
+- 决策：推荐页嵌入拼图切关 pending 期间必须保留当前运行态与棋盘，只让拼图壳内部 busy 表现承接同步；`isStartingRecommendEntry` 只表示推荐作品尚未真正启动出来，不再把已有嵌入拼图 run 的局部 busy 一并当成整卡加载态。若下一关落到相似作品，前端还必须把新作品写回推荐缓存并同步 `activeRecommendEntryKey`，避免运行态进入新作品但推荐卡元信息、分享 / 点赞 / 改造和后续“下一个”仍锚定旧作品。
 - 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、推荐页拼图切关测试与平台链路文档。
 - 验证方式：点击推荐页拼图“下一关”后，在 `advancePuzzleNextLevel` 未返回前，页面仍应保留 `puzzle-board`，且不出现 `加载中...` 占位；返回相似作品后，当前推荐卡的 `作品信息` 应显示新作品标题。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
@@ -281,7 +428,6 @@
 
 - 背景：创作页顶部、banner 奖池和玩法卡消耗口径曾经混在一起，容易把活动奖池误认成账号余额，也让横向空间被外部边框和过大的卡片高度挤占。
 - 决策：移动端创作 Tab 顶栏与 `陶泥儿` 品牌同一行只显示真实账户泥点数，数据直接取 `profileDashboard.walletBalance`；banner 内只展示赛事奖池，新增拼图主题创作赛和抓大鹅主题创作赛，两个主题奖池各 `1000` 泥点数；玩法卡封面右下角固定展示 `10-20泥点数`，列表外框取消，卡片高度和横向间距一起收紧。
-- 追加决策：创作页和草稿页顶栏右上泥点余额胶囊是补足泥点入口；当前环境开启充值入口时直接打开账户充值弹窗，否则打开运营兑换码弹窗，不再跳到账户面板或泥点账单。
 - 影响范围：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、创作页相关测试和玩法链路文档。
 - 验证方式：移动端浏览器检查应看到创作顶栏余额、卡内分页点、内嵌横向 banner 和更紧凑的玩法卡；`CustomWorldCreationHub.test.tsx` 与 `RpgEntryHomeView.recharge.test.tsx` 的定向断言应保持通过。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
@@ -500,7 +646,7 @@
 
 ## 2026-05-19 生产 provision 改为 Windows 下载包后由目标机本地安装
 
-- 后续更新：该口径先被 2026-06-01 Linux 优先方案取代，又在 2026-06-05 被 Server-Provision 专用口径覆盖；当前 `Genarrative-Server-Provision` 不走 Windows 下载阶段，也不在 Linux build 节点中转工具包，而是在目标 dev / release agent 内准备 `provision-tools/`。
+- 后续更新：该口径已被 `2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost` 取代；当前 `Genarrative-Server-Provision` 不再走 Windows 下载阶段，而是在 Linux build 节点直接准备 `provision-tools/`。
 - 背景：当前 `development` provision 目标实际就是 Linux agent `genarrative-build-01`，之前把 `Prepare Provision Tools` 放在 `linux && genarrative-build` 会让目标机自己连 GitHub 和 `install.spacetimedb.com`，违背“Windows 本机先下载再传到目标机”的运维要求。
 - 决策：`Genarrative-Server-Provision` 拆成 Windows 下载阶段和 Linux 目标机安装阶段。Windows 节点的 `Download Provision Tool Archives` 只下载 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz`，通过 `stash/unstash` 传到目标 Linux 节点；目标机执行 `scripts/prepare-server-provision-tools.sh` 时设置 `PROVISION_REQUIRE_LOCAL_DOWNLOADS=true`，只消费已下载件生成 `provision-tools/`，缺包直接失败，不回退外网下载。
 - 追加决策：Server-Provision 的 Windows helper 不再对 Jenkins `writeFile` 刚写出的 `.ps1` 做原地 UTF-8 BOM 重写，而是由显式 `powershell.exe` 按 UTF-8 读入脚本文本，并用 `ScriptBlock::Create(...)` 在内存中执行；这样既保留中文脚本内容，又避免同一个 workspace 脚本被立即重写时触发 `拒绝访问`。
@@ -1158,7 +1304,6 @@
 
 ## 2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost
 
-- 后续更新：该条仍适用于常规构建 / 发布流水线；`Genarrative-Server-Provision` 已在 2026-06-05 改为目标部署 agent 全程执行，并禁止公网 Git fallback 与 build 节点工具包中转。
 - 背景：生产流水线长期混用 Windows、Linux 和公网 Git 入口，导致构建 / 发布 / provision 的 checkout 口径分叉；同时 `Genarrative-Server-Provision` 还残留过 Windows 下载 helper，和当前 Linux 构建 / 发布部署路径不一致。
 - 决策：生产 Jenkins 流水线统一把执行节点收口到 Linux label，`Pipeline script from SCM` 仍保留公网域名，但所有生产流水线首次 `GitSCM checkout` 先尝试 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后再回退到 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；`Genarrative-Stdb-Module-Build`、`Genarrative-Server-Provision`、`Genarrative-Notify-Email` 也都切到 Linux 节点。`Genarrative-Server-Provision` 的工具准备不再依赖 Windows helper，而是在 Linux build 节点直接生成 `provision-tools/` 后交给后续 Linux 发布阶段。
 - 影响范围：`jenkins/Jenkinsfile.production-*`、`scripts/jenkins-checkout-source.sh`、`scripts/prepare-server-provision-tools.sh`、生产运维文档。
@@ -1274,6 +1419,186 @@
 - 验证方式：工作台首屏不再出现标题 / 简介 / 标签输入；结果页修改后点试玩或发布会先写回当前作品信息。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-06-03 Profile Dashboard Presentation 收口
+
+- 背景：`RpgEntryHomeView.tsx` 同时承载个人数据卡、钱包 chip 与“玩过”弹窗，计数压缩、累计时长、单作品时长、玩法标签和作品号兜底散在页面 Implementation 内，修改展示口径时缺少稳定测试面。
+- 决策：新增 `src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts` 作为个人数据展示 Module，Interface 收口为 `buildProfileDashboardPresentation`、计数 / 时长格式化和“玩过”列表标签 / 作品号格式化函数；页面只消费结果并保留 UI 编排与点击处理。
+- 影响范围：RPG 首页“我的数据”卡片、移动端 / 桌面端钱包 chip、个人数据弹窗与“玩过”列表。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryProfileDashboardPresentation.test.ts`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】ProfileDashboardPresentation收口计划-2026-06-03.md`。
+
+## 2026-06-03 Recommend Feed ViewModel 收口
+
+- 背景：推荐 feed 与正式 runtime 的上一条 / 下一条选择分别在 `RpgEntryHomeView.tsx` 和 `PlatformEntryFlowShellImpl.tsx` 手写公开作品去重、隐藏内容过滤、active key 兜底和相邻回环，存在推荐预览与 runtime 口径漂移风险。
+- 决策：在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 追加推荐 feed Module Interface：`dedupePlatformPublicGalleryEntries`、`buildPlatformRecommendFeedEntries`、`selectPlatformRecommendFeedWindow`、`selectAdjacentPlatformRecommendEntry`；首页与 FlowShell 均消费该 Interface。
+- 影响范围：移动端首页推荐 swipe、发现页推荐频道、桌面推荐格、推荐 runtime 队列与上一条 / 下一条跳转。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|edutainment"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "logged out home recommendation next starts the next puzzle work"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】RecommendFeedViewModel收口计划-2026-06-03.md`。
+
+## 2026-06-03 Recommend Swipe Deck Model 收口
+
+- 背景：移动端推荐首页 swipe deck 的拖拽阈值、offset clamp、commit 方向、rail class 和分享文案仍留在 `RpgEntryHomeView.tsx` 页面 Implementation 内，页面同时承载 DOM pointer 副作用和纯规则。
+- 决策：新增 `src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts` 作为 Recommend Swipe Deck Module，Interface 收口 `hasRecommendDragStarted`、`clampRecommendDragOffset`、`resolveRecommendDragCommitDirection`、`resolveRecommendCommitOffset`、`buildRecommendSwipeRailClassName`、`shouldAnimateRecommendSwipe` 与 `buildRecommendShareText`；页面仅保留 pointer capture、DOM 高度读取、动画 timer、clipboard 与 like/remix/open 副作用 Adapter。
+- 影响范围：移动端推荐首页 swipe 手势、上一条 / 下一条动画、推荐分享文案与未登录时的直接切换行为。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|edutainment"`、`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts -t "recommend"`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md`。
+
+## 2026-06-03 Ranking ViewModel 收口
+
+- 背景：排行 tab 的文案、metric label 与空态文案在 `RpgEntryHomeView.tsx`，排序和 metric value 在 `rpgEntryPublicGalleryViewModel.ts`，同一 `PlatformRankingTab` 的 Interface 分散且页面需要类型断言取 active config。
+- 决策：在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 收口 `DEFAULT_PLATFORM_RANKING_TAB`、`PLATFORM_RANKING_TABS`、`getPlatformRankingTabConfig` 与 `getPlatformRankingMetric`；页面仅保留 active tab 状态和渲染。
+- 影响范围：发现页排行频道 tab 顺序、tab 文案、空态文案、排行项指标 label/value。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "bottom category tab becomes ranking and switches ranking metrics|ranking"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】RankingViewModel收口计划-2026-06-03.md`。
+
+## 2026-06-03 Category Option ViewModel 收口
+
+- 背景：分类频道的筛选选项、排序选项、默认值、active label fallback 和排序循环仍留在 `RpgEntryHomeView.tsx` 页面 Implementation 内，而玩法过滤、排序和主指标已经在 `rpgEntryPublicGalleryViewModel.ts`，同一分类 Interface 被拆成两处。
+- 决策：在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 收口 `DEFAULT_PLATFORM_CATEGORY_KIND_FILTER`、`DEFAULT_PLATFORM_CATEGORY_SORT_MODE`、`PLATFORM_CATEGORY_KIND_FILTERS`、`PLATFORM_CATEGORY_SORT_OPTIONS`、`getPlatformCategoryKindFilterOption`、`getPlatformCategorySortOption` 与 `getNextPlatformCategorySortMode`；页面仅保留当前筛选 / 排序状态和渲染。
+- 影响范围：发现页分类频道筛选弹窗、筛选按钮 label、排序按钮 label 与排序循环。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "category"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md`。
+
+## 2026-06-03 Match3D Runtime Profile 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 内仍直接承载抓大鹅公开详情转 work、session draft 转 profile、生成背景资产提升、runtime active profile 选择和 run / profile / public detail 素材优先级，平台壳需要理解抓大鹅生成素材内部结构。
+- 决策：新增 `src/components/platform-entry/platformMatch3DRuntimeProfile.ts` 作为抓大鹅 runtime profile Module，Interface 收口 `mapPublicWorkDetailToMatch3DWork`、`buildMatch3DProfileFromSession`、`normalizeMatch3DWorkForRuntimeUi`、`mapMatch3DWorksForRuntimeUi`、`promoteMatch3DGeneratedBackgroundAsset`、`hasMatch3DRuntimeAsset`、`hasMatch3DRuntimeBackgroundAsset`、`resolveActiveMatch3DRuntimeProfile` 与 runtime item/background/backgroundImage 解析函数；平台壳只保留启动 run、预加载、路由、错误和 state 编排。
+- 影响范围：抓大鹅作品架、公开详情试玩、推荐 runtime、正式 runtime 与草稿结果页试玩前素材规范化。
+- 验证方式：`npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "match3d|抓大鹅"`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】Match3DRuntimeProfile收口计划-2026-06-03.md`。
+
+## 2026-06-03 Draft Generation Shelf Model 收口
+
+- 背景：平台壳内散落创作生成 notice key、pending 作品架占位、作品详情更新回填、失败文案覆盖、拼图稳定 ID、持久化 generating/failed 判断与草稿 Tab 未读点，新增或调整玩法时需要在多处理解 `workId` / `profileId` / `sourceSessionId` / `draftId` 形状。
+- 决策：新增 `src/components/platform-entry/platformDraftGenerationShelfModel.ts` 作为 Draft Generation Shelf Module，Interface 收口 `collectDraftNoticeKeys`、`getGenerationNoticeShelfKeys`、`createPendingDraftShelfState`、各玩法 `buildPending*Works`、`buildCreationWorkShelfRuntimeState`、`collectVisibleDraftNoticeKeys`、`hasUnreadDraftGenerationUpdates`、`mergePuzzleWorkSummary`、`mergeBigFishWorkSummary`、拼图稳定 ID 与持久化状态判断；`PlatformEntryFlowShellImpl.tsx` 仅作为 React state、网络刷新、路由和弹窗副作用 Adapter。
+- 影响范围：创作中心草稿 Tab 未读点、作品架生成中遮罩、作品详情更新回填、失败草稿摘要、pending 草稿占位、拼图 / 抓大鹅生成恢复和各玩法生成完成通知。
+- 验证方式：`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、`npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts -t "generation state|failure notice|failed puzzle"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft|persisted generating match3d draft|completed baby object match draft"`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md`。
+
+## 2026-06-03 Creation Hub Shelf Items Interface 收口
+
+- 背景：`creationWorkShelf.ts` 已把各玩法作品映射为 `CreationWorkShelfItem.actions`，但 `CustomWorldCreationHub.tsx` 的生产 Interface 仍接收 raw items 与 open/delete/claim 回调列阵，新增玩法时 Hub props 继续膨胀。
+- 决策：`CustomWorldCreationHub.tsx` 生产 Interface 收敛为 `shelfItems: CreationWorkShelfItem[]` 与少量 UI 状态；`PlatformEntryFlowShellImpl.tsx` 在外层作为 Adapter 调用 `buildCreationWorkShelfItems` 注入完整 actions；Hub 测试改经 `CustomWorldCreationHub.testAdapter.tsx` 把旧 fixture 转成 shelf items，不让测试继续依赖旧浅 Interface。
+- 影响范围：创作 Tab / 草稿 Tab 作品架、RPG / 拼图 / 抓大鹅 / 方洞 / 跳一跳 / 敲木鱼 / 视觉小说 / Bark Battle / 宝贝识物作品打开、删除、生成态与拼图奖励领取。
+- 验证方式：`npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts`、`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx`、`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、相关 FlowShell creation hub 交互片段、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】WorkShelfModule收口计划-2026-06-03.md`。
+
+## 2026-06-03 Creation URL State Model 收口
+
+- 背景：平台壳内散落各玩法创作恢复 URL 的 `sessionId` / `profileId` / `draftId` / `workId` 组装、空值归一化、拼图 runtime query key 与拼图稳定身份互推，导致刷新恢复规则缺少稳定测试面。
+- 决策：新增 `src/components/platform-entry/platformCreationUrlStateModel.ts` 作为 Creation URL State Module，Interface 收口各玩法 `build*CreationUrlState`、拼图 `buildPuzzle*RuntimeUrlState`、URL state 非空判断和 runtime state key；新增 `src/components/platform-entry/platformPuzzleIdentityModel.ts` 作为拼图稳定身份 Module，`platformDraftGenerationShelfModel.ts` 仅 re-export 旧入口以保持兼容。`PlatformEntryFlowShellImpl.tsx` 只保留路由、URL 写入和网络副作用 Adapter。
+- 追加决策：初始创作 URL 恢复的已处理、非创作路径、无私有 query、平台配置加载中、受保护数据暂不可读与可恢复判定也收口到 `resolveInitialCreationUrlRestoreDecision`；壳层只按 `skip`、`mark-handled`、`wait`、`restore` 执行 ref 标记或进入原恢复副作用。
+- 追加决策：创作直达恢复目标解析收口到 `resolveCreationUrlRestoreTarget(pathname, state)`；Module 统一识别 big-fish、match3d、square-hole、puzzle、visual-novel、bark-battle、baby-object-match、jump-hop、wooden-fish 的 path、私有 query 归一化、生成路径标记和 big-fish workId 到 sessionId 兜底。壳层仍执行作品列表读取、草稿恢复、错误处理、stage 切换和 URL 写回；`/creation/rpg` 继续保持无具体恢复目标，后续要接入需先补规则与测试。
+- 追加决策：创作 URL 恢复的作品 / 草稿身份匹配谓词、以及跳一跳 / 敲木鱼恢复后的阶段落点也归入 `platformCreationUrlStateModel.ts`。身份匹配只允许非空目标值命中，避免 query 缺失时用空值误开草稿；壳层只把已读取的列表项、session 或 work 交给 Module 判定，然后执行对应打开 / restore 副作用。
+- 影响范围：创作流程刷新恢复、拼图草稿 / 发布 runtime 深链、作品架打开试玩、跳一跳 / 敲木鱼 work-backed 恢复、Bark Battle / 宝贝识物本地草稿恢复。
+- 验证方式：`npm run test -- src/components/platform-entry/platformCreationUrlStateModel.test.ts src/components/platform-entry/platformPuzzleIdentityModel.test.ts`、`npm run test -- src/services/creationUrlState.test.ts`、`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】CreationUrlStateModel收口计划-2026-06-03.md`。
+
+## 2026-06-04 Platform Public Code Search Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 的公开搜索回调内联判断内部用户 ID、陶泥号、RPG 作品号、各玩法公开作品号前缀和 fallback 顺序，壳层同时承担纯搜索计划与网络 / 打开副作用。
+- 决策：新增 `src/components/platform-entry/platformPublicCodeSearchModel.ts`，以 `resolvePlatformPublicCodeSearchPlan(keyword)` 返回 `normalizedKeyword` 与 `steps`。`user_` / `user-` 只查用户 ID；玩法前缀直达对应作品；`CW` / 纯数字先查 RPG 作品再查陶泥号；普通关键词和 `SY` 保持既有用户号、RPG 作品、汪汪声浪、用户号兜底顺序。壳层只按 step 执行既有查找、详情打开、Bark Battle runtime 特例和 missing work 归航。
+- 影响范围：发现页 / 推荐页公开搜索、作品详情深链初始搜索、陶泥号命中面板、各玩法公开作品号直达。
+- 验证方式：`npm run test -- src/components/platform-entry/platformPublicCodeSearchModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform Played Work Open Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 的个人“玩过作品”点击回调内联判断 `worldType`、`worldKey` 前缀、玩法别名、目标 ID、RPG fallback 详情和大鱼吃小鱼 fallback work，壳层同时承担打开意图与异步副作用。
+- 决策：新增 `src/components/platform-entry/platformPlayedWorkOpenModel.ts`，以 `resolvePlatformPlayedWorkOpenIntent(work)` 返回 `noop`、各玩法公开详情打开意图、`open-big-fish` 或 `open-rpg`。Module 负责玩法别名、`worldKey` 前缀兜底、big-fish gallery miss `fallbackWork` 和 RPG `CustomWorldGalleryCard` payload；壳层继续负责关闭面板、刷新 gallery、命中真实作品、打开详情和错误提示。
+- 影响范围：个人“玩过作品”面板点击打开、拼图 / 抓大鹅 / 方洞 / 跳一跳 / 敲木鱼 / 大鱼吃小鱼 / RPG 公开详情入口。
+- 验证方式：`npm run test -- src/components/platform-entry/platformPlayedWorkOpenModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、相关 profile 面板交互片段、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform Generation Progress Tick Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 的生成页进度 tick effect 内联维护 stage 到小游戏生成状态的三元链，并额外手写视觉小说 `startedAtMs` / `phase` 特例，壳层同时承担纯判定与 interval 副作用。
+- 决策：新增 `src/components/platform-entry/platformGenerationProgressTickModel.ts`，以 `resolvePlatformGenerationProgressTickDecision(input)` 返回 `{ activeKind, shouldTick }`。Module 负责 stage 到 kind 映射、小游戏状态缺失 / 终态判定、视觉小说轻量生成判定；壳层继续负责 `Date.now()`、`window.setInterval`、progress now state 写入和 cleanup。
+- 影响范围：拼图、抓大鹅、大鱼吃小鱼、方洞挑战、跳一跳、敲木鱼、宝贝识物和视觉小说生成页进度 tick。
+- 验证方式：`npm run test -- src/components/platform-entry/platformGenerationProgressTickModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform Mini Game Session Mapping Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 顶部仍保留拼图 runtime 恢复、方洞 session draft 转 profile、视觉小说 work detail 转 Agent session、跳一跳 pending session、敲木鱼 detail 恢复、敲木鱼生成中作品摘要和敲木鱼 pending session 等纯 DTO 映射，壳层需要理解 sessionId 优先级、拼图稳定 ID、方洞草稿 profile 默认值、视觉小说 work/session fallback、敲木鱼生成中摘要和 pending draft 默认值。
+- 决策：新增 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts`，收口 `buildPuzzleRuntimeWorkFromSession`、`buildSquareHoleProfileFromSession`、`buildVisualNovelSessionFromWorkDetail`、`buildJumpHopPendingSession`、`buildWoodenFishSessionFromWorkDetail`、`buildWoodenFishGeneratingWorkSummary` 与 `buildWoodenFishPendingSession`。Module 复用 `normalizeCreationUrlValue` 与 `platformPuzzleIdentityModel`；壳层只保留网络读取、React state、URL 写入和 stage 切换副作用。
+- 影响范围：拼图 runtime URL 恢复、方洞挑战草稿 profile 构造、视觉小说草稿作品架恢复、跳一跳生成中作品架打开、敲木鱼生成中作品架摘要 / 作品架打开和敲木鱼草稿 detail 恢复。
+- 验证方式：`npm run test -- src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform RPG Agent Result Preview Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护 RPG Agent 结果页发布门禁展示修正和 result preview source label 映射，壳层需要理解 `CustomWorldProfile` 顶层字段、`creatorIntent`、`anchorContent`、章节蓝图和首幕 acts。
+- 决策：新增 `src/components/platform-entry/platformRpgAgentResultPreviewModel.ts`，收口 `buildPlatformRpgAgentResultPublishGateView` 与 `resolvePlatformRpgAgentResultPreviewSourceLabel`。Module 只做展示层纯判定；壳层继续负责 session/profile 编排、发布副作用和结果页 props 传递。
+- 影响范围：RPG Agent 结果页发布按钮门禁 blockers、publishReady 展示修正和预览来源 label。
+- 验证方式：`npm run test -- src/components/platform-entry/platformRpgAgentResultPreviewModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform Mini Game Draft Generation State Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护小游戏生成状态恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并和 ready / generating 判定，壳层同时承担 API / background task 副作用和 `MiniGameDraftGenerationState` 生命周期细节。
+- 决策：新增 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts`，收口恢复态、失败态、完成态、展示 rebase、拼图 progress phase 阈值和进度 metadata 合并。壳层继续负责 API、后台任务、React state 写入、作品架刷新、URL 和 stage 切换。
+- 追加决策：抓大鹅轮询作品素材时的旁路进度合并也归入该 Module，由 `mergeMatch3DGeneratedAssetsIntoGenerationState(state, assets)` 统一统计可用图片素材、至少 5 个总素材计数、`match3d-generate-views` phase 推进和首个素材错误传播；壳层只负责轮询 session / work detail 与写入 state。
+- 影响范围：拼图 / 抓大鹅 / 大鱼吃小鱼 / 方洞 / 跳一跳 / 敲木鱼 / 宝贝识物生成状态恢复、完成失败收尾、生成页返回展示和拼图轮询进度合并。
+- 验证方式：`npm run test -- src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform Mini Game Draft Payload Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护拼图 / 抓大鹅表单 payload、拼图作品更新 payload、拼图编译 action、跳一跳 / 敲木鱼生成 action、作品摘要回填 payload 和 pending 草稿 metadata，壳层需要理解描述字段优先级、formDraft 回退、结果页 draft 到作品更新字段的映射、跳一跳 / 敲木鱼 payload 与 draft 优先级、Match3D config / draft / anchorPack 优先级和数字解析。
+- 决策：新增 `src/components/platform-entry/platformMiniGameDraftPayloadModel.ts`，收口 `buildPuzzleFormPayloadFromWork`、`buildPuzzleFormPayloadFromSession`、`buildPuzzleFormPayloadFromAction`、`buildPuzzleCompileActionFromFormPayload`、`buildPuzzleWorkUpdatePayloadFromDraft`、`buildJumpHopDraftActionPayload`、`buildWoodenFishDraftActionPayload`、`buildPendingPuzzleDraftMetadata`、`isPuzzleFormOnlyDraft`、`isEmptyPuzzleFormOnlyDraft`、`buildMatch3DFormPayloadFromSession`、`buildMatch3DFormPayloadFromWork` 与 `buildPendingMatch3DDraftMetadata`；`parseOptionalFiniteNumber` 留在 Module 内部。
+- 影响范围：拼图 action 完成 / 执行前 / 失败恢复、拼图结果页试玩前作品更新、跳一跳 / 敲木鱼生成与重生成 action、拼图表单直生草稿、拼图 form-only 草稿恢复 / 分流 / 结果页渲染、拼图草稿架恢复、抓大鹅表单直生草稿与失败恢复。
+- 验证方式：`npm run test -- src/components/platform-entry/platformMiniGameDraftPayloadModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform Puzzle Draft Recovery Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 的拼图恢复链路只要 cover 或候选图存在就会把恢复 session 抬为 ready，可能让缺关卡画面、UI spritesheet 或关卡背景的半成品直接进入结果页完成态。
+- 决策：新增 `src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts`，收口 `normalizeRecoveredPuzzleDraftSession` 与 `hasRecoverableGeneratedPuzzleDraft`。恢复完成态必须同时具备首图、`levelSceneImage*`、`uiSpritesheetImage*` 与 `levelBackgroundImage*`；只有完整资产包成立时才把 draft 与首关 `generationStatus` 抬为 `ready`。
+- 影响范围：拼图生成完成后刷新恢复、拼图 background compile task 完成态写入和结果页自动打开。
+- 验证方式：`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`。
+- 决策：`module-puzzle::validate_publish_requirements` 新增三类资产 blocker，要求每关具备 `level_scene_image_*`、`ui_spritesheet_image_*` 与 `level_background_image_*`；`api-server::puzzle::tags::is_puzzle_session_snapshot_publish_ready` 同步使用完整资产包判定。
+- 影响范围：拼图 result preview blockers、publishReady、标签生成后 session stage、从 action payload 构造 fallback session 的 ready 判定。
+- 验证方式：`cargo test -p module-puzzle --manifest-path server-rs/Cargo.toml validate_publish_requirements`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml puzzle_image_generation_builds_fallback_session_from_levels_snapshot`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml puzzle_image_generation_fallback_session_ready_when_asset_pack_complete`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-04 Platform Profile Wallet Delta Model 收口
+
+- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护钱包余额归一、本地 delta 乐观更新和服务端 dashboard 刷新后的 delta 抵消，壳层需要理解余额非负、整数截断、借贷方向和服务端快照对账。
+- 决策：新增 `src/components/platform-entry/platformProfileWalletDeltaModel.ts`，收口 `resolveProfileWalletBalance`、`adjustProfileDashboardWalletBalance` 与 `reconcileProfileWalletLocalDeltaWithServerDashboard`。壳层只保留 API 请求、React ref、state 写入和刷新触发副作用。
+- 影响范围：创作入口泥点展示、生成前泥点校验、扣点 / 返还后的个人 dashboard 乐观更新、后台刷新 dashboard 时的本地 delta 对账。
+- 验证方式：`npm run test -- src/components/platform-entry/platformProfileWalletDeltaModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-06-03 Public Work Presentation 收口
+
+- 背景：作品卡、推荐 runtime meta、排行项、分类项、搜索结果和桌面 hero 共用玩法类型 label 与紧凑计数格式，但规则仍在 `RpgEntryHomeView.tsx` 页面 Implementation 内。
+- 决策：在 `src/components/rpg-entry/rpgEntryWorldPresentation.ts` 追加单作品展示 Interface：`describePlatformPublicWorkKind`、`formatPlatformCompactCount`、`resolvePlatformPublicWorkAuthorLookup` 与 `formatPlatformPublicAuthorAvatarLabel`；页面删除本地玩法类型、紧凑计数、公开作者 lookup 和头像首字实现。集合筛选、排序和指标选择继续留在 `rpgEntryPublicGalleryViewModel.ts`。
+- 影响范围：公开作品卡片 aria label、推荐点赞 / 改造文案、排行数值、分类主指标、搜索结果、桌面 hero 玩法 label、公开作者摘要缓存 key 与无头像首字兜底。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryWorldPresentation.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|ranking|category"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】PublicWorkPresentation收口计划-2026-06-03.md`。
+
+## 2026-06-03 Profile Funds ViewModel 收口
+
+- 背景：个人资金展示规则散在 `RpgEntryHomeView.tsx`，且账单来源 label 表漏掉后端契约已有的 `puzzle_author_incentive_claim`，会把原始枚举值直接外显。
+- 决策：新增 `src/components/rpg-entry/rpgEntryProfileFundsViewModel.ts` 作为个人资金展示 Module，Interface 收口账单来源文案、金额正负号、余额兜底、充值价格、商品主值与会员摘要；页面保留弹窗布局、支付流程、微信渠道和订单轮询副作用。
+- 影响范围：泥点账单弹窗、充值商品卡片、账户充值弹窗会员摘要。
+- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryProfileFundsViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger|profile recharge modal shows native qr code"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/【前端架构】ProfileFundsViewModel收口计划-2026-06-03.md`。
+
 ## 2026-05-26 前端不外露图片模型名
 
 - 背景：拼图与相关结果页、生成进度和错误提示里直接显示 `gpt-image-2`、`gemini-3.1-flash-image-preview`、`image-2` 等名称，会把内部模型路由暴露给普通用户。

.hermes/shared-memory/pitfalls.md

@@ -1293,10 +1293,10 @@
 ## 拼图会过早进入待发布态，结果页可能空图但仍显示可发布
 
 - 现象：拼图创作有时刚结束就跳到“待发布”结果页，但结果页里的正式图还是空的，发布检查随后又会拦住，用户会感觉“已经完成了却又不能发布”。
-- 原因：拼图的待发布判定太弱，`build_result_preview` / `validate_publish_requirements` 和 `is_puzzle_session_snapshot_publish_ready` 只检查了作品名、简介、标签、关卡名和 cover 图，没有要求 `level_scene_image_src`、`ui_spritesheet_image_src`、`level_background_image_src` 等完整资产都齐；前端恢复链路里的 `hasRecoverableGeneratedPuzzleDraft` / `normalizeRecoveredPuzzleDraftSession` 也只要有 cover 或候选图就会把草稿当成已完成。
-- 处理：待修复时要把“待发布”门槛收紧到整套拼图资产包完整，再让恢复逻辑只在完整草稿下抬高为完成态，避免半成品直接进入结果页。
-- 验证：当某个拼图草稿只补齐首图、但关卡背景或 UI spritesheet 仍缺失时，不应再进入 `ready_to_publish`；结果页也不应把这类草稿误判为已完成。
-- 关联：`server-rs/crates/module-puzzle/src/application.rs`、`server-rs/crates/api-server/src/puzzle/tags.rs`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`。
+- 原因：拼图的待发布判定太弱，`build_result_preview` / `validate_publish_requirements` 和 `is_puzzle_session_snapshot_publish_ready` 只检查了作品名、简介、标签、关卡名和 cover 图，没有要求 `level_scene_image_src`、`ui_spritesheet_image_src`、`level_background_image_src` 等完整资产都齐；历史前端恢复链路里的 `hasRecoverableGeneratedPuzzleDraft` / `normalizeRecoveredPuzzleDraftSession` 也只要有 cover 或候选图就会把草稿当成已完成。
+- 处理：前端恢复链路已收口到 `platformPuzzleDraftRecoveryModel.ts`，只有首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才把恢复草稿抬为完成态；后端 `build_result_preview` / `validate_publish_requirements` / `is_puzzle_session_snapshot_publish_ready` 也已收紧到同一完整资产包门槛。
+- 验证：当某个拼图草稿只补齐首图、但关卡背景或 UI spritesheet 仍缺失时，前端恢复链路不应把它误判为已完成，后端也不应进入 `ready_to_publish` 或返回 `publishReady=true`。
+- 关联：`server-rs/crates/module-puzzle/src/application.rs`、`server-rs/crates/api-server/src/puzzle/tags.rs`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts`、`src/components/puzzle-result/PuzzleResultView.tsx`。
 
 ## WebGL 画布在高 DPR 移动端放大溢出
 

docs/README.md

@@ -37,6 +37,74 @@ SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段
 
 AI 文字游戏模板接入以 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md) 为最新口径：只吸收 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，禁止迁入外部社区、支付、榜单、私有存档或回放。
 
+前端 Server-Sent Events 客户端传输层收口到 `src/services/sseStream.ts`，事件边界、UTF-8 flush、JSON 解析跳过和提前取消约定见 [【前端架构】SSE客户端传输层收口约定-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91SSE%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BC%A0%E8%BE%93%E5%B1%82%E6%94%B6%E5%8F%A3%E7%BA%A6%E5%AE%9A-2026-06-03.md)。
+
+平台入口公开作品身份、跨玩法去重、公开作品流聚合、推荐运行态 kind 判定、推荐 runtime 启动意图、ready 判定和最新排序收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`，规则见 [【前端架构】平台入口PublicGalleryFlowModule收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91%E5%B9%B3%E5%8F%B0%E5%85%A5%E5%8F%A3PublicGalleryFlowModule%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+统一作品详情页的玩法 kind、详情打开策略、自有作品动作模式、编辑 / 点赞 / 改造 / 启动意图和公开详情映射收口到 `src/components/platform-entry/platformPublicWorkDetailFlow.ts`；抓大鹅公开详情映射与启动 / 编辑 Adapter 的素材归一仍归 `platformMatch3DRuntimeProfile.ts`，规则见 [【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md](./technical/【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md)。
+
+创作中心作品架打开动作由 `CreationWorkShelfItem.actions.open` 统一承载，生产 Hub 只接收 `CreationWorkShelfItem[]` 与 UI 状态，不再接收各玩法 raw items 和回调列阵，规则见 [【前端架构】WorkShelfModule收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91WorkShelfModule%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+作品架删除确认的标题、删除说明、草稿 notice key 和拼图派生稳定 ID 收口到 `src/components/platform-entry/platformCreationWorkDeleteFlow.ts`，平台壳只保留删除 API、刷新、错误和页面跳转副作用，规则见 [【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md](./technical/【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md)。
+
+创作入口点击的占位、隐藏模板拦截、未知入口 no-op 与工作台启动目标收口到 `src/components/platform-entry/platformCreationLaunchModel.ts`，壳层只执行启动前准备、错误提示和受保护动作，规则见 [【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md)。
+
+平台入口公开码搜索的用户 ID、陶泥号、RPG 作品号、各玩法作品号前缀、per-play 公开码匹配、详情卡 DTO 映射和失败回退顺序收口到 `src/components/platform-entry/platformPublicCodeSearchModel.ts`，壳层只按计划执行网络读取、详情打开和错误归航副作用，规则见 [【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md)。
+
+个人“玩过作品”面板的玩法别名、`worldKey` 前缀兜底、RPG 公开详情 payload 和大鱼吃小鱼 gallery miss fallback 收口到 `src/components/platform-entry/platformPlayedWorkOpenModel.ts`，壳层只执行面板关闭、gallery 读取、详情打开和错误提示副作用，规则见 [【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md)。
+
+平台入口生成页进度 tick 的 stage 到生成状态映射、终态判定和视觉小说轻量生成特例收口到 `src/components/platform-entry/platformGenerationProgressTickModel.ts`，壳层只保留 `Date.now()`、`setInterval` 和 cleanup 副作用，规则见 [【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md)。
+
+平台壳的拼图 runtime 恢复 work、方洞 session draft 转 profile、视觉小说 work detail 转 Agent session、跳一跳 pending session、敲木鱼 detail 恢复 session、敲木鱼生成中作品摘要和敲木鱼 pending session DTO 映射收口到 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts`，壳层只保留网络、状态、URL 与 stage 副作用，规则见 [【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md)。
+
+平台小游戏生成状态的恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并、抓大鹅生成资产旁路进度合并和 ready / generating 判定收口到 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts`，壳层只保留 API、后台任务、React state、URL 与 stage 副作用，规则见 [【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md)。
+
+平台小游戏草稿恢复和提交所需的拼图 / 抓大鹅表单 payload、拼图作品更新 payload、拼图编译 action、跳一跳 / 敲木鱼生成 action、pending metadata 与拼图 form-only 草稿判定收口到 `src/components/platform-entry/platformMiniGameDraftPayloadModel.ts`，壳层只保留 API、Action 执行、background task 与状态副作用，规则见 [【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md)。
+
+平台拼图生成完成后刷新恢复的草稿归一化与可恢复完成态判定收口到 `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)。
+
+Bark Battle 草稿三图完整性、生成状态归一、作品架摘要恢复草稿配置、发布快照 / 发布回包资产兜底和草稿 / 已发布作品进入 runtime 前的 `BarkBattlePublishedConfig` 映射收口到 `src/components/platform-entry/barkBattleWorkCache.ts`，规则见 [【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md](./technical/【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md)。
+
+平台首页推荐 runtime 的匿名 Runtime Guest Token、已登录 background auth、非 embedded no-op 和拼图 isolated/default auth mode 计划收口到 `src/components/platform-entry/platformRecommendRuntimeAuthModel.ts`，规则见 [【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md)。
+
+平台首页推荐 runtime 自动启动的桌面 / Tab / stage / loading gate、active entry 查找、ready 判定和 clear/start/noop 决策收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`，规则见 [【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md](./technical/【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md)。
+
+RPG Agent 结果页发布门禁展示和预览来源 label 收口到 `src/components/platform-entry/platformRpgAgentResultPreviewModel.ts`，壳层只保留 session/profile 编排和结果页 props 传递，规则见 [【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md)。
+
+平台入口创作生成通知、pending 作品架占位、作品详情更新回填、失败覆盖、跨玩法草稿打开优先级、拼图稳定 ID 和草稿 Tab 未读点收口到 `src/components/platform-entry/platformDraftGenerationShelfModel.ts`，规则见 [【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91DraftGenerationShelfModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+平台入口创作恢复 URL 私有 query、初始恢复判定、创作直达恢复目标解析、恢复目标身份匹配、跳一跳 / 敲木鱼恢复阶段落点、拼图 runtime query 与拼图稳定身份互推收口到 `src/components/platform-entry/platformCreationUrlStateModel.ts` 和 `src/components/platform-entry/platformPuzzleIdentityModel.ts`，规则见 [【前端架构】CreationUrlStateModel收口计划-2026-06-03.md](./technical/【前端架构】CreationUrlStateModel收口计划-2026-06-03.md)。
+
+平台入口错误 / 完成弹窗的文案归一、来源格式、候选择一、dismiss key 与任务完成文案收口到 `src/components/platform-entry/platformDialogStateModel.ts`，规则见 [【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md](./technical/【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md)。
+
+平台入口受保护数据失效后的 stage 去留判定，以及缺失草稿 / 作品 / run 时的阶段回退，收口到 `src/components/platform-entry/platformSelectionStageModel.ts`，壳层只执行缓存清空、布尔事实汇总和必要跳转，规则见 [【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md)。
+
+小游戏 runtime client 的路径编码、JSON 请求、runtime guest auth 与 retry 选项收口到 `src/services/runtimeRequest.ts`，Match3D、SquareHole、Big Fish、Bark Battle、Puzzle 公开 / 推荐运行态请求、Jump Hop / Wooden Fish 正式 run 请求和 Visual Novel 局部 JSON runtime 请求已先迁移，规则见 [【前端架构】RuntimeClientFamily收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RuntimeClientFamily%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+抓大鹅 runtime profile 的公开详情转 work、session draft 转 profile、生成背景资产提升和 run/profile/public detail 素材优先级收口到 `src/components/platform-entry/platformMatch3DRuntimeProfile.ts`，规则见 [【前端架构】Match3DRuntimeProfile收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91Match3DRuntimeProfile%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+公开作品分类选项、搜索、跨来源去重、今日筛选、排行排序和时间戳解析收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91PublicGalleryViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+公开作品的玩法类型 label、公开作者 lookup 与游玩 / 改造 / 点赞等紧凑计数格式收口到 `src/components/rpg-entry/rpgEntryWorldPresentation.ts`，规则见 [【前端架构】PublicWorkPresentation收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91PublicWorkPresentation%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+推荐 feed 的公开作品去重、普通内容过滤、active 窗口与上一条 / 下一条回环选择也收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】RecommendFeedViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RecommendFeedViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+移动端推荐首页 swipe deck 的拖拽阈值、offset clamp、commit 方向、rail class 和分享文案收口到 `src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts`，规则见 [【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md](./technical/【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md)。
+
+排行频道的默认 tab、tab 文案、空态文案、排序字段与指标 label/value 收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】RankingViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RankingViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+每日任务卡片与任务中心弹窗的任务选择、进度、状态标签和按钮文案收口到 `src/components/rpg-entry/rpgEntryProfileTaskViewModel.ts`，规则见 [【前端架构】ProfileTaskViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileTaskViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+个人数据卡、钱包 chip 与“玩过”弹窗的计数、时长、作品类型和作品号展示收口到 `src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts`，规则见 [【前端架构】ProfileDashboardPresentation收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileDashboardPresentation%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
+个人资金展示的账单来源、金额正负号、余额兜底、充值价格、商品主值和会员摘要收口到 `src/components/rpg-entry/rpgEntryProfileFundsViewModel.ts`，规则见 [【前端架构】ProfileFundsViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileFundsViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
+
 ## 推荐阅读顺序
 
 1. 先看 [经验沉淀](./experience/README.md)，快速建立这个项目的开发共识。

docs/technical/【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md

@@ -0,0 +1,46 @@
+# 【前端架构】Bark Battle Work Cache 草稿状态收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 仍内联维护 Bark Battle 草稿三图完整性、生成状态归一、作品架摘要恢复草稿配置，以及草稿 / 已发布作品进入 runtime 前的 `BarkBattlePublishedConfig` 映射。壳层因此需要同时理解三图资产字段、`partial_failed` 与 `pending_assets` 的差异、`publishedAt` 兜底、作品摘要字段和草稿试玩配置默认值。
+
+这些规则属于 Bark Battle 作品摘要与草稿缓存的纯模型。若留在平台壳层，后续发布、作品架刷新、公开详情启动或草稿试玩都容易重复一份字段清单。
+
+## 决策
+
+扩展 `src/components/platform-entry/barkBattleWorkCache.ts`，作为 Bark Battle Work Cache **Module** 继续承接作品摘要缓存和草稿 runtime 配置规则。新增公开 **Interface**：
+
+- `hasBarkBattleDraftRequiredImages(draft)`：判断草稿是否已具备玩家形象、对手形象和竞技背景三图。
+- `resolveBarkBattleDraftGenerationStatus(draft, partialFailed)`：三图齐备返回 `ready`，否则按是否部分失败返回 `partial_failed` 或 `pending_assets`。
+- `buildBarkBattleDraftConfigFromWorkSummary(work)`：把作品架摘要恢复成可编辑 / 可试玩的 `BarkBattleDraftConfig`。
+- `buildBarkBattlePublishedConfigFromDraft(draft)`：把草稿结果页试玩所需配置映射为 `BarkBattlePublishedConfig`。
+- `buildBarkBattlePublishedConfigFromWork(work)`：把作品架 / 公开详情启动正式 runtime 所需配置映射为 `BarkBattlePublishedConfig`。
+- `buildBarkBattlePublishSnapshot(draft)`：拼装发布接口所需的最终草稿快照。
+- `mergeBarkBattlePublishedConfigAssets(published, draft)`：发布回包缺少三图字段时沿用结果页草稿图。
+
+`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它只负责 API 请求、React state、URL、运行态 stage 切换和错误提示，不再持有 Bark Battle 三图完整性与 runtime config 字段清单。
+
+## Interface 约束
+
+- 草稿三图必须同时具备 `playerCharacterImageSrc`、`opponentCharacterImageSrc` 和 `uiBackgroundImageSrc` 的非空值，才视为 `ready`。
+- 未齐三图且 `partialFailed=true` 时返回 `partial_failed`，否则返回 `pending_assets`。
+- 作品摘要恢复草稿时，`draftId` 缺失回退 `workId`，`description` 来自 summary，三图 null 归一为 `undefined`，`configVersion=1` 且 `rulesetVersion='bark-battle-ruleset-v1'`。
+- 草稿试玩配置的 `workId` 优先使用草稿稳定 `workId`，缺失时回退 `draftId`。
+- 草稿试玩配置的 `configVersion` 与 `rulesetVersion` 使用草稿值，缺失时回退 `1` 与 `bark-battle-ruleset-v1`。
+- 已发布作品配置的 `publishedAt` 缺失时回退 `updatedAt`，保持旧 runtime 启动语义。
+- 发布快照只携带草稿已有的三图字段，不凭空补空字符串。
+- 发布接口回包缺少三图字段时，结果页草稿图继续作为 runtime 和作品摘要的兜底。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层传入草稿或作品摘要，即可得到生成状态、草稿配置或 runtime 配置；字段归一、默认值和三图完整性藏入 Module Implementation。
+- **Leverage**：作品架草稿恢复、结果页试玩、作品架启动、公开详情启动和缓存刷新可复用同一组 Bark Battle 规则。
+- **Locality**：Bark Battle 资产完整性与配置映射集中到纯测试面，后续变更三图字段或规则集默认值时无需搜索巨型平台壳。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/barkBattleWorkCache.test.ts`
+- `npx eslint --max-warnings 0 src/components/platform-entry/barkBattleWorkCache.ts src/components/platform-entry/barkBattleWorkCache.test.ts`
+- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】CreationUrlStateModel收口计划-2026-06-03.md

@@ -0,0 +1,41 @@
+# CreationUrlStateModel 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾直接承载多玩法创作恢复 URL 的拼装规则：`sessionId`、`profileId`、`draftId`、`workId` 的优先级、拼图草稿 runtime query、以及空值归一化散在壳层 Implementation 内。平台壳因此需要理解各玩法快照结构，新增玩法或修复刷新恢复时缺少稳定测试面。
+
+## 决策
+
+- 新增 `src/components/platform-entry/platformCreationUrlStateModel.ts` 作为 Creation URL State Module。
+- 该 Module 的 Interface 收口为各玩法 `build*CreationUrlState`、拼图 `buildPuzzle*RuntimeUrlState`、`normalizeCreationUrlValue`、`hasCreationUrlStateValue`、`hasPuzzleRuntimeUrlStateValue`、`buildPuzzleRuntimeUrlStateKey`、初始创作 URL 恢复判定 `resolveInitialCreationUrlRestoreDecision`、创作直达恢复目标解析 `resolveCreationUrlRestoreTarget`、恢复目标身份匹配谓词，以及跳一跳 / 敲木鱼恢复后的阶段落点判定。
+- 新增 `src/components/platform-entry/platformPuzzleIdentityModel.ts` 作为拼图稳定身份 Module，统一 `puzzle-session-*`、`puzzle-profile-*`、`puzzle-work-*` 的互推规则。
+- `PlatformEntryFlowShellImpl.tsx` 保留 React state、路由、登录门禁、网络请求和 URL 写入副作用 Adapter；不再在壳层内定义各玩法 URL 状态构造函数，也不直接内联初始恢复的已处理 / 等待 / 可恢复判定。
+
+## Interface 约束
+
+- 创作恢复私有 query 只使用 `sessionId`、`profileId`、`draftId`、`workId`；不得新增说明性 query 字段。
+- 空字符串、全空白字符串统一视为 `null`，避免刷新恢复时写入无效私有参数。
+- work-backed 玩法优先使用后端 work summary 的公开 `workId` / `profileId`；仅缺失时才回退 session draft。
+- 拼图 runtime query 独立使用 `mode`、`runtimeSessionId`、`runtimeProfileId`、`runtimeLevelId`、`publicWorkCode`，不与创作恢复 query 混写。
+- 拼图 draft runtime 若没有 `sourceSessionId`，只允许从 `puzzle-profile-*` 反推出 `puzzle-session-*`。
+- 初始创作 URL 恢复只在未处理、当前路径属于创作恢复路径、私有 query 有值、平台配置加载完成且受保护数据可读时执行；非创作路径或无私有 query 时标记已处理，加载中或暂不可读时等待。
+- 创作直达恢复目标由 `resolveCreationUrlRestoreTarget(pathname, state)` 统一识别；它只返回玩法 kind、归一化后的四个私有 query、生成路径标记和大鱼吃小鱼 session 兜底，不执行网络请求、草稿打开、stage 切换或 URL 写回。
+- 作品 / 草稿身份匹配只允许非空目标值命中，避免 query 缺失时用 `null` / 空值误匹配到无效草稿。匹配谓词仍只判断身份，不触发列表读取或打开动作。
+- 跳一跳和敲木鱼的恢复阶段落点由 `resolveJumpHopCreationUrlRestoreStage` 与 `resolveWoodenFishCreationUrlRestoreStage` 决定；生成路径优先进入生成页，否则按是否恢复到 draft / work 落到结果页或工作台。
+- `/creation/rpg` 当前仍不归入具体恢复目标；若后续要恢复 RPG 直达，需要先补明确恢复规则和测试，不得让壳层重新内联路径判定。
+
+## Depth / Leverage / Locality
+
+- **Depth**：调用方只传玩法快照或作品摘要，即可得到规范化 URL state；各玩法字段优先级藏在 Module Implementation 内。
+- **Leverage**：新增或调整玩法恢复规则、恢复目标或恢复等待条件时，优先补 Module Interface 测试，再接壳层 Adapter。
+- **Locality**：恢复 query、拼图 runtime query 和拼图稳定身份规则集中在两个小 Module，避免散落在页面壳、作品架和 runtime 打开逻辑中。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformCreationUrlStateModel.test.ts src/components/platform-entry/platformPuzzleIdentityModel.test.ts`
+- `npm run test -- src/services/creationUrlState.test.ts`
+- `npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`
+- `npx eslint src/components/platform-entry/platformCreationUrlStateModel.ts src/components/platform-entry/platformCreationUrlStateModel.test.ts src/components/platform-entry/platformPuzzleIdentityModel.ts src/components/platform-entry/platformPuzzleIdentityModel.test.ts --max-warnings 0`
+- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx src/components/platform-entry/platformDraftGenerationShelfModel.ts --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md

@@ -0,0 +1,33 @@
+# 【前端架构】Creation Work Delete Flow 收口计划
+
+## 背景
+
+平台入口作品架的删除入口覆盖 RPG、拼图、抓大鹅、方洞挑战、大鱼吃小鱼、视觉小说和宝贝识物。此前 `PlatformEntryFlowShellImpl.tsx` 在每个删除 handler 内重复计算确认框标题、删除说明、草稿 notice key 和拼图派生稳定 ID。壳层既要理解每种玩法的作品身份，又要承接异步删除、刷新列表、错误状态和页面跳转，导致删除确认规则缺少稳定测试面。
+
+该 **Interface** 过浅：页面只想展示“删除哪个作品、会从哪里移除、删除成功后清哪些生成 notice”，却必须知道 `workId` / `profileId` / `sourceSessionId` / `draftId`、`status` / `publicationStatus` / `publishStatus` 和宝贝识物特殊公开去向。
+
+## 决策
+
+新增 `src/components/platform-entry/platformCreationWorkDeleteFlow.ts` 作为 Creation Work Delete Flow **Module**。其唯一公开 **Interface** 是 `resolvePlatformCreationWorkDeleteConfirmationModel(input)`，输入为带 `kind` 的 union，输出：
+
+- `id`：确认框和删除 busy 使用的稳定作品 ID。
+- `title`：确认框标题，含拼图、视觉小说和宝贝识物标题兜底。
+- `detail`：草稿 / 已发布删除说明，宝贝识物已发布使用“寓教于乐板块”文案。
+- `noticeKeys`：删除成功后应标记已读的草稿生成 notice keys，拼图包含 `buildPuzzleResultWorkId` / `buildPuzzleResultProfileId` 派生 key。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 **Adapter**：负责鉴权保护、确认框 state、调用各玩法删除 API、清错误、刷新作品架 / 公开广场、`markDraftNoticeSeen` 和必要的页面跳转。`run` 不进入纯 **Module**，避免把网络副作用和 React state 写入藏入模型层。
+
+## 约定
+
+- 新玩法接入作品架删除时，先补齐后端删除链路、作品架 action 和本 **Module** 的确认模型，再开放删除按钮。
+- Jump Hop、Wooden Fish 和 Bark Battle 当前仅有作品架 action 预留，平台壳不传删除 handler；不得因本 Module 存在而默认开放删除。
+- 删除确认文案不得散回平台壳；若公开去向不是公开广场，应在本 **Module** 明确分支。
+- 草稿 notice key 的身份扩展必须复用 `collectDraftNoticeKeys`，保持 trim、去空和去重语义一致。
+
+## 验证
+
+- `npm run test -- src/components/platform-entry/platformCreationWorkDeleteFlow.test.ts`
+- `npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`
+- `npx eslint src/components/platform-entry/platformCreationWorkDeleteFlow.ts src/components/platform-entry/platformCreationWorkDeleteFlow.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md

@@ -0,0 +1,40 @@
+# 【前端架构】Draft Generation Shelf Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 同时承载创作生成状态、草稿 Tab 未读点、pending 作品架占位、失败文案覆盖、作品详情更新回填和跨玩法 notice key。拼图、抓大鹅、方洞、跳一跳、敲木鱼、视觉小说、汪汪声浪、大鱼吃小鱼和宝贝识物各有不同的 `workId` / `profileId` / `sourceSessionId` / `draftId`，这些规则散在平台壳 **Implementation** 内，导致调用方必须理解每种玩法的草稿身份形状。
+
+该 **Interface** 过浅：页面看似只关心“生成中 / 已完成未读 / 失败”，却要知道多 ID 去重、pending 草稿去重、失败摘要、拼图空标题兜底和持久化 generating 覆盖规则。
+
+## 决策
+
+新增 `src/components/platform-entry/platformDraftGenerationShelfModel.ts` 作为 Draft Generation Shelf **Module**。其 **Interface** 收口为：
+
+- `collectDraftNoticeKeys(kind, ids)` / `getGenerationNoticeShelfKeys(item)`：统一把玩法草稿身份映射为 notice key。
+- `createPendingDraftShelfState(...)` 与 `buildPending*Works(...)`：统一把本地 pending 生成状态映射成作品架占位，并避免与后端已有草稿重复。
+- `buildCreationWorkShelfRuntimeState({ item, notices, pendingShelfItems })`：统一输出 `CreationWorkShelfRuntimeState`，处理失败覆盖、拼图空标题 `拼图草稿` 兜底、summary 占位覆盖、生成中遮罩和 ready 未读点。
+- `collectVisibleDraftNoticeKeys(...)` / `hasUnreadDraftGenerationUpdates(...)`：统一草稿 Tab 顶部未读点规则。
+- `mergePuzzleWorkSummary(current, updated)` 与 `mergeBigFishWorkSummary(current, updated)`：统一作品详情更新后回填作品架和当前详情的身份匹配规则。
+- `resolvePuzzleDraftOpenIntent(...)`、`resolveMatch3DDraftOpenIntent(...)`、`resolveSquareHoleDraftOpenIntent(...)`、`resolveBigFishDraftOpenIntent(...)`、`resolveVisualNovelDraftOpenIntent(...)`、`resolveJumpHopDraftOpenIntent(...)` 与 `resolveWoodenFishDraftOpenIntent(...)`：统一拼图、抓大鹅、方洞挑战、大鱼吃小鱼、视觉小说、跳一跳和敲木鱼草稿打开时的已发布详情、缺 session、ready 未读试玩、失败 / active / background 生成页、当前结果页、持久化 generating 恢复、失败 fallback stage 和普通草稿恢复优先级。
+- `buildPuzzleResultWorkId(...)` / `buildPuzzleResultProfileId(...)`、`isPersistedDraftGenerating(...)` / `isPersistedDraftFailed(...)`：把拼图稳定 ID 与持久化状态判断收在同一 **Seam**。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 React state 与副作用 **Adapter**：负责写入 `draftGenerationNotices` / `pendingDraftShelfItems`、读取生成 session、启动 ready 草稿试玩、刷新后端列表、打开结果页和弹窗；它不再内联 pending shelf row shape、notice key 汇总、作品架 runtime state 和上述玩法草稿打开优先级。
+
+## 约定
+
+- 新玩法若需进入草稿生成通知，必须在此 **Module** 补 notice key、pending 占位和 visible key 映射，避免在平台壳里新增散落 switch。
+- pending 作品只用于本地生成任务尚未被后端作品架返回时的临时展示；一旦后端已有同一 `sourceSessionId` / `profileId` / `workId`，pending 占位必须让位。
+- 拼图作品详情更新只以 `profileId` 匹配回填；大鱼吃小鱼作品详情更新只以 `sourceSessionId` 匹配回填。
+- 失败 notice 优先级高于持久化 generating，且可通过 pending metadata 提供更具体 summary；否则回退玩法默认失败摘要。
+- 已有封面的拼图草稿即使局部关卡仍在后台生成，也不得被整卡遮罩为不可打开的生成中状态。
+- 草稿打开 intent 只返回纯计划、notice keys 与必要稳定 ID，不创建失败生成态、不请求详情、不写 stage；这些仍由壳层 Adapter 执行。
+- 本 **Module** 不做网络请求、路由切换、弹窗副作用或 React state 写入，只保留纯 **Implementation**，以提高 **Depth**、**Leverage** 与 **Locality**。
+
+## 验证
+
+- `npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`
+- `npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts -t "generation state|failure notice|failed puzzle"`
+- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft|persisted generating match3d draft|completed baby object match draft"`
+- 针对新 **Module** 与测试执行 ESLint；`PlatformEntryFlowShellImpl.tsx` 保留既有 hook dependency warnings，不在本切片扩大处理。
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】Match3DRuntimeProfile收口计划-2026-06-03.md

@@ -0,0 +1,34 @@
+# 【前端架构】Match3D Runtime Profile 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 同时编排抓大鹅创作、作品详情、推荐 runtime 和正式 runtime。运行态启动前的 profile 规范化、公开详情转 work、生成背景资产提升、run / profile / public detail 优先级和 runtime 素材选择原本都在平台壳 **Implementation** 内，导致平台壳必须理解抓大鹅生成素材的内部结构。
+
+## 决策
+
+新增 `src/components/platform-entry/platformMatch3DRuntimeProfile.ts`，作为抓大鹅 runtime profile **Module**。该 **Module** 的 **Interface** 收口为：
+
+- `mapPublicWorkDetailToMatch3DWork(entry)`：把公开作品详情映射为可启动 runtime 的 Match3D work，并补齐生成背景资产。
+- `buildMatch3DProfileFromSession(session)`：从创作 session draft 生成 runtime profile。
+- `normalizeMatch3DWorkForRuntimeUi(profile)` / `mapMatch3DWorksForRuntimeUi(profiles)`：统一作品列表进入 UI / runtime 前的素材规范化。
+- `promoteMatch3DGeneratedBackgroundAsset(profile)`：从 `generatedBackgroundAsset` 或 `generatedItemAssets[].backgroundAsset` 提升背景图、对象 key 与 prompt。
+- `hasMatch3DRuntimeAsset(profile.generatedItemAssets)` / `hasMatch3DRuntimeBackgroundAsset(profile)`：统一判断 runtime 是否具备物品与背景素材。
+- `resolveActiveMatch3DRuntimeProfile(run, runtimeProfile, profile)`：按 run 的 `profileId` 选择当前 profile，避免切屏时误用旧草稿。
+- `resolveMatch3DRuntimeGeneratedItemAssets(...)`、`resolveMatch3DRuntimeGeneratedBackgroundAsset(...)`、`resolveMatch3DRuntimeBackgroundImageSrc(...)`：统一 run / profile / public detail 的素材优先级。
+
+`PlatformEntryFlowShellImpl.tsx` 只保留启动 run、预加载、路由、错误和 state 编排；抓大鹅素材规则集中到该 **Module**，提升 **Locality** 与测试 **Leverage**。
+
+## 约定
+
+- 公开详情补 runtime 素材时，只有 `profileId` 与 run 匹配才优先使用公开详情；错配时不得污染当前 run。
+- 当前启动时拿到的 `runtimeProfile` 优先于旧草稿 profile；若 run 指向旧草稿 profile，才使用草稿 profile。
+- 背景资产提升不得覆盖已有显式 `backgroundImageSrc` / `backgroundImageObjectKey` / `generatedBackgroundAsset`，只补缺。
+- 本 **Module** 只放纯 profile / asset 规则，不引入启动 run、预加载、URL、状态机或 UI 副作用。
+
+## 验证
+
+- `npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`
+- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "match3d|抓大鹅"`
+- `npm run typecheck`
+- `npm run check:encoding`
+- 针对新 Module 与测试执行 ESLint；`PlatformEntryFlowShellImpl.tsx` 保留既有 hook dependency warnings，不在本切片扩大处理。

docs/technical/【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md

@@ -0,0 +1,29 @@
+# 【前端架构】Platform Creation Launch Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 的创作入口点击回调曾直接以内联 `if` 链判断 `airp` 占位、隐藏的 `baby-object-match`、RPG 与各小游戏工作台启动目标。壳层因此同时理解入口 ID、是否需要执行启动前准备、隐藏模板错误文案和具体工作台分流。
+
+这类规则属于创作入口启动意图。壳层应只执行准备、错误提示和受保护动作，不应持有入口 ID 到工作台目标的长链判定。
+
+## 决策
+
+新增 `src/components/platform-entry/platformCreationLaunchModel.ts` 作为 Platform Creation Launch **Module**。其公开 **Interface** 为：
+
+- `resolvePlatformCreationLaunchIntent({ type, isBabyObjectMatchVisible })`：输入后端入口配置下发的模板 ID 与幼教入口可见性，输出 `noop`、`blocked` 或 `launch` 意图。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 **Adapter**：根据 intent 决定是否调用 `prepareCreationLaunch()`，对 blocked intent 写入 `sessionController.setCreationTypeError(...)`，对 launch intent 进入 `runProtectedAction(...)` 并调用具体工作台打开函数。
+
+## 约定
+
+- `airp` 是占位入口，必须在 `prepareCreationLaunch()` 之前返回 `noop`，避免触发新游戏初始化、返回目标复位或错误清理。
+- 隐藏的 `baby-object-match` 必须在 `prepareCreationLaunch()` 之后返回 blocked intent，错误文案仍使用 `EDUTAINMENT_HIDDEN_MESSAGE`。
+- 未知入口 ID 保持旧语义：先允许壳层执行启动前准备，再作为 `noop` 结束，避免改变未来后端配置异常时的准备流程。
+- 新增可启动模板时，先在本 **Module** 的 launch target union、目标集合和测试中列明，再在壳层 Adapter 中补具体启动函数。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformCreationLaunchModel.test.ts`
+- `npx eslint src/components/platform-entry/platformCreationLaunchModel.ts src/components/platform-entry/platformCreationLaunchModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md

@@ -0,0 +1,46 @@
+# PlatformDialogStateModel 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾直接承载平台级错误 / 完成弹窗的纯状态规则：错误文案 trim、来源 label 与 id 拼接、后台生成仍在处理的识别、错误候选优先级、dismiss key 与生成完成文案都散在壳层 Implementation 内。壳层因此既要管理 React state 与副作用清理，又要记住弹窗判定细则；新增玩法错误或调整弹窗展示时缺少稳定测试面。
+
+## 决策
+
+- 新增 `src/components/platform-entry/platformDialogStateModel.ts` 作为 Platform Dialog State Module。
+- Module Interface 收口：
+  - `normalizePlatformDialogMessage`
+  - `formatPlatformDialogSource`
+  - `isBackgroundGenerationStillRunningMessage`
+  - `resolvePlatformErrorDialog`
+  - `buildPlatformErrorDialogDismissKey`
+  - `buildPlatformTaskCompletionDialogDismissKey`
+  - `resolveActivePlatformDialog`
+  - `PLATFORM_TASK_COMPLETION_MESSAGE`
+  - `PlatformErrorDialogState`、`PlatformTaskFailureDialogState` 与 `PlatformTaskCompletionDialogState`
+- `PlatformEntryFlowShellImpl.tsx` 继续作为 Adapter：汇总各玩法候选、持有 React state、关闭弹窗时清理对应 setter。副作用清理不下沉到 Module，避免把大量壳层 setter 变成浅 Interface。
+
+## Interface 约束
+
+- 错误与完成弹窗文案先 trim；空字符串或全空白字符串统一视为 `null`。
+- 来源格式固定为 `label + 空格 + trimmed id`；缺 id 时只返回 label。
+- 平台错误候选按数组顺序取第一个有效文案；候选本身只描述 `key/source/message`。
+- 错误 dismiss key 固定为 `key:source:message`；完成 dismiss key 固定为 `key:source:message:completedAtMs`，缺完成时间时补 `0`。
+- `resolveActivePlatformDialog` 只根据当前弹窗 dismiss key 与已记录 dismiss key 决定是否隐藏，不修改底层错误或完成状态。
+- 任务完成弹窗文案统一使用 `PLATFORM_TASK_COMPLETION_MESSAGE`，不得在壳层重复写同一中文 literal。
+- `closePlatformErrorDialog` 保持在壳层 Adapter；它负责按错误来源清理 `creationEntryConfigError`、玩法 error、作品详情 error 等副作用状态，不属于纯状态 Module。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层传入候选和 dismiss 记录，即可得到当前平台弹窗状态；文案归一、来源格式和 dismiss 规则藏在 Module Implementation 内。
+- **Leverage**：新增玩法错误来源时只需补候选；调整弹窗纯规则时优先改 Module 与单测。
+- **Locality**：平台错误弹窗、任务完成弹窗和后台生成 still-running 识别集中在一个小 Module，避免继续散落在大型平台壳 Implementation 内。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformDialogStateModel.test.ts`
+- `npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx`
+- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "background match3d draft failure notifies and reopens failed retry page|completed match3d draft notice first opens trial then reopens result|puzzle compile timeout shows failure dialog when reread session is still generating"`
+- `npx eslint src/components/platform-entry/platformDialogStateModel.ts src/components/platform-entry/platformDialogStateModel.test.ts --max-warnings 0`
+- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md

@@ -0,0 +1,37 @@
+# 【前端架构】Platform Generation Progress Tick Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 的生成页进度 tick effect 曾以内联三元链按 `selectionStage` 选择拼图、抓大鹅、大鱼吃小鱼、方洞挑战、跳一跳、敲木鱼和宝贝识物的生成状态，并额外手写视觉小说的 `startedAtMs` / `phase` 判定。壳层因此既要维护 `setInterval` 副作用，又要记住每个生成页 stage 对应哪份进度状态。
+
+生成进度是否需要 tick 是纯判定；`Date.now()`、`window.setInterval` 和进度时间 state 写入仍属于 React 壳层副作用。
+
+## 决策
+
+新增 `src/components/platform-entry/platformGenerationProgressTickModel.ts` 作为 Platform Generation Progress Tick **Module**。其公开 **Interface** 为：
+
+- `resolvePlatformGenerationProgressTickDecision(input)`：输入当前 `selectionStage`、各小游戏 `MiniGameDraftGenerationState` 和视觉小说轻量生成状态，输出 `{ activeKind, shouldTick }`。
+- `PlatformGenerationProgressTickKind`：枚举可 tick 的生成类型，包含已有小游戏生成 kind 与 `visual-novel`。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它把当前 state 组装给 Module，若 `shouldTick=false` 则不启动 interval；若为真，仍按旧逻辑立即写一次 `Date.now()`，再每 `500ms` 更新并在 effect cleanup 中清理 timer。
+
+## Interface 约束
+
+- 小游戏生成 stage 只读取匹配 kind 的 `MiniGameDraftGenerationState`；stage 与 state 不匹配时不 tick。
+- 小游戏状态缺失、`phase='ready'` 或 `phase='failed'` 时不 tick；其它 phase 按进行中处理。
+- `visual-novel-generating` 不强行转成 `MiniGameDraftGenerationState`，只在 `startedAtMs != null` 且 phase 非 `ready` / `failed` 时 tick。
+- 非生成 stage 即使传入可运行 state 也不 tick。
+- 本 Module 不计算进度、不重建 view state、不处理拼图 / 抓大鹅 background task 覆盖；这些仍按既有生成页和作品架模型处理。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层只消费 `shouldTick`，stage 到 state 的映射和终态判定藏入 Module Implementation。
+- **Leverage**：新增生成页玩法时，先扩展 stage-to-kind 映射和单测，再让壳层 Adapter 传入对应 state。
+- **Locality**：生成进度 tick 规则集中到一个纯测试面，interval 副作用继续局部留在 React effect，避免把 timer 控制做成浅 Interface。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformGenerationProgressTickModel.test.ts`
+- `npx eslint src/components/platform-entry/platformGenerationProgressTickModel.ts src/components/platform-entry/platformGenerationProgressTickModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md

@@ -0,0 +1,47 @@
+# 【前端架构】Platform Mini Game Draft Generation State Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾内联维护小游戏生成状态的恢复、失败/完成收尾、展示 rebase、拼图后端进度合并、抓大鹅生成资产旁路进度合并和生成中 / ready 判定。壳层因此既要处理 API 回包、React state、后台任务、URL 和 stage，又要记住 `MiniGameDraftGenerationState` 的生命周期细节。
+
+这些状态变换不读取 DOM，不请求网络，也不写 React state；它们属于平台层小游戏草稿生成状态 **Module**。壳层只应决定何时调用、把返回值写入对应 state。
+
+## 决策
+
+新增 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts` 作为 Platform Mini Game Draft Generation State **Module**。其公开 **Interface** 为：
+
+- `createMiniGameDraftGenerationStateForRestoredDraft(kind, metadata?, startedAtMs?)`：为恢复的草稿重建生成态，并保留后端开始时间作为进度事实源。
+- `createFailedMiniGameDraftGenerationStateForRestoredDraft(kind, updatedAt, error, metadata?)`：恢复失败草稿时按后端 `updatedAt` 建立失败态。
+- `rebaseMiniGameDraftGenerationStateForDisplay(state)` 与 `rebaseMiniGameDraftBackgroundCompileTaskForDisplay(task)`：清理展示用 `finishedAtMs`，避免返回生成页后沿用结束态计时。
+- `createPuzzleDraftGenerationStateFromPayload(payload, session?)`、`resolvePuzzlePhaseFromSessionProgress(state, session)`、`mergePuzzleSessionProgressIntoGenerationState(state, session)`：集中处理拼图生成的 aiRedraw、后端进度百分比和 phase 推进。
+- `mergeMatch3DGeneratedAssetsIntoGenerationState(state, assets)`：抓大鹅轮询到作品素材后，按可用图片数量推进生成页资产计数，并把首个素材错误传播到生成态。
+- `resolveFinishedMiniGameDraftGenerationState(state, phase, options?)`：统一完成 / 失败收尾的 `finishedAtMs`、错误与资产计数合并。
+- `isMiniGameDraftReady(state)` 与 `isMiniGameDraftGenerating(state)`：统一生成态轻量判定。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它继续负责 API、background task、React state 写入、作品架刷新、URL 与 stage 切换。
+
+## Interface 约束
+
+- 恢复草稿状态必须允许调用方传入 `startedAtMs`；未传时使用当前时间，与旧逻辑一致。
+- 恢复失败状态必须通过 `resolveMiniGameDraftGenerationStartedAtMs(updatedAt)` 解析后端时间，并保留传入 metadata。
+- `resolveFinishedMiniGameDraftGenerationState` 只覆盖显式传入的 `error`、`completedAssetCount`、`totalAssetCount`；未传时沿用原 state。
+- 拼图 session 只有在 `draft` 存在且不是 `formDraft` 时才视为后端编译生成中 session，才写入 `puzzleProgressPercent` 并推进 phase。
+- 拼图进度阈值保持旧值：`>=96` 到 `puzzle-select-image`，`>=94` 到 `puzzle-ui-assets`，`>=88` 时按 `puzzleAiRedraw=false` 进入 `puzzle-level-scene`，否则进入 `puzzle-cover-image`。
+- phase 变化时 `puzzleActiveStepStartedAtMs` 使用 session `updatedAt` 解析值；phase 不变时保留旧值。
+- 抓大鹅资产旁路进度不得覆盖 `ready` 或 `failed` 终态；非终态下只统计有 `imageViews[].imageObjectKey` / `imageViews[].imageSrc`、顶层 `imageObjectKey` 或顶层 `imageSrc` 的素材。
+- 抓大鹅资产旁路进度的 `totalAssetCount` 至少为 `5`，保留当前五物品首批生成节奏；已有素材数量超过 `5` 时按真实素材数量展示。
+- 抓大鹅已有可用素材时 phase 推进到 `match3d-generate-views`；无可用素材时保留原 phase；首个素材错误写入 `error`，无素材错误时保留原错误。
+- 展示 rebase 只清理 `finishedAtMs`，不得修改 phase、error、资产计数或 metadata。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层以状态变换函数表达意图；生成态字段、拼图阈值、抓大鹅素材计数、时间解析与计数合并藏入 Module Implementation。
+- **Leverage**：后续新增小游戏生成恢复、调整拼图后端进度阈值或改变抓大鹅素材批次展示时，先改 Module 与单测，再让壳层 Adapter 保持调用点不变。
+- **Locality**：小游戏生成状态规则集中到一个纯测试面，避免在大型壳层的 API callback、background task 和恢复流程中重复推理 `MiniGameDraftGenerationState`。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts`
+- `npx eslint src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md

@@ -0,0 +1,52 @@
+# 【前端架构】Platform Mini Game Draft Payload Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾内联维护拼图和抓大鹅草稿恢复所需的表单 payload、拼图编译 action payload、拼图作品更新 payload、跳一跳 / 敲木鱼生成 action payload、作品摘要回填 payload 和 pending 草稿 metadata。壳层因此需要理解拼图描述字段优先级、formDraft 回退、结果页 draft 到作品更新字段的映射、Match3D config / draft / anchorPack 优先级、跳一跳 / 敲木鱼 payload 与 session draft 优先级，以及 pending 作品架标题摘要如何从 payload 派生。后续还残留拼图 form-only 草稿判定，影响 action 分流、草稿恢复阶段和结果页渲染。
+
+这些逻辑都是 DTO 变换；不读取 React state，不请求网络，也不写 URL。壳层只应决定何时恢复、何时提交 action、何时写入生成状态。
+
+## 决策
+
+新增 `src/components/platform-entry/platformMiniGameDraftPayloadModel.ts` 作为 Platform Mini Game Draft Payload **Module**。其公开 **Interface** 为：
+
+- `buildPuzzleFormPayloadFromWork(item)`：从拼图作品摘要恢复创作表单 payload。
+- `buildPuzzleFormPayloadFromSession(session)`：从拼图 session 恢复创作表单 payload。
+- `buildPuzzleFormPayloadFromAction(payload)`：从拼图 action 还原表单 payload，仅接受 `compile_puzzle_draft` 与 `save_puzzle_form_draft`。
+- `buildPuzzleCompileActionFromFormPayload(payload)`：从表单 payload 构造拼图编译 action。
+- `buildPuzzleWorkUpdatePayloadFromDraft(draft)`：从拼图结果 draft 构造 `updatePuzzleWork(...)` 所需 payload。
+- `buildJumpHopDraftActionPayload(actionType, { payload, draft })`：从跳一跳表单 payload / session draft 构造生成或重生成 action。
+- `buildWoodenFishDraftActionPayload(actionType, { payload, draft })`：从敲木鱼表单 payload / session draft 构造生成或重生成 action。
+- `buildPendingPuzzleDraftMetadata(payload)`：从拼图 payload 派生 pending 作品架 metadata。
+- `isPuzzleFormOnlyDraft(session)` 与 `isEmptyPuzzleFormOnlyDraft(session)`：判断拼图 session 是否仍只是表单草稿，以及表单草稿是否没有任何可提交内容。
+- `buildMatch3DFormPayloadFromSession(session)` 与 `buildMatch3DFormPayloadFromWork(item)`：从抓大鹅 session / work 恢复表单 payload。
+- `buildPendingMatch3DDraftMetadata(payload)`：从抓大鹅 payload 派生 pending metadata。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它继续负责 API、Action 执行、background task、生成状态、错误提示、作品架和阶段切换。
+
+## Interface 约束
+
+- 拼图 work payload 的 `pictureDescription` 优先级固定为 `workDescription > summary > first level pictureDescription > levelName > workTitle > ''`。
+- 拼图 session payload 的 `pictureDescription` 优先级固定为 `formDraft.pictureDescription > first level pictureDescription > anchorPack.visualSubject.value > seedText > ''`。
+- 拼图编译 action 的 `promptText` 来自 `pictureDescription || seedText`；`workDescription` 缺省回退到图片描述；`candidateCount` 固定为 `1`。
+- 拼图 action 还原只接受 `compile_puzzle_draft` 与 `save_puzzle_form_draft`；其它 action 返回 `null`。
+- 拼图作品更新 payload 必须直接映射 `workTitle`、`workDescription`、`levelName`、`summary`、`themeTags`、`coverImageSrc`、`coverAssetId`，`levels` 缺失时回退空数组。
+- 跳一跳和敲木鱼生成 action payload 的字段优先级固定为表单 payload 优先，其次 session draft；重生成 action 只传 session draft 字段。
+- 拼图 form-only 草稿只在 `session.stage === 'collecting_anchors'` 且存在 `draft.formDraft` 时成立。
+- 空 form-only 草稿必须同时缺少 `seedText`、`formDraft.workTitle`、`formDraft.workDescription` 与 `formDraft.pictureDescription`。
+- 抓大鹅 session payload 优先读取 `config`，其次 `draft`，最后 `anchorPack`；`anchorPack.clearCount` 与 `anchorPack.difficulty` 只接受有限数字字符串或数字。
+- 抓大鹅 work payload 的 `themeText` 优先 `themeText`，缺失回退 `gameName`。
+- pending metadata 只收非空 trim 后标题和摘要；抓大鹅 metadata 用 `themeText || seedText` 同时作为 title 和 summary。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层以一组表意函数取得 payload / metadata；字段优先级、结果页 draft 更新字段、跳一跳 / 敲木鱼 action 字段、默认空资产和数字解析藏入 Module Implementation。
+- **Leverage**：后续调整拼图或抓大鹅草稿恢复表单、拼图作品更新字段、跳一跳 / 敲木鱼生成 action 字段时，先改 Module 与单测，再保持壳层 API / state 副作用不变。
+- **Locality**：表单恢复、作品更新与 action payload 规则集中到一个纯测试面，避免在大型平台壳的生成、重试和恢复流程里重复散落 DTO 拼装。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformMiniGameDraftPayloadModel.test.ts`
+- `npx eslint src/components/platform-entry/platformMiniGameDraftPayloadModel.ts src/components/platform-entry/platformMiniGameDraftPayloadModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md

@@ -0,0 +1,47 @@
+# 【前端架构】Platform Mini Game Session Mapping Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 顶部曾保留拼图 runtime 恢复、方洞挑战 session draft 转 profile、视觉小说 work detail 转 Agent session、跳一跳 pending session、敲木鱼 work detail 恢复、敲木鱼生成中作品摘要和敲木鱼 pending session 多段纯 DTO 映射。它们没有 React state、网络请求、路由、弹窗或计时副作用，却住在大型平台壳内；新增或修正生成中草稿恢复时，需要在壳层里理解 sessionId 优先级、拼图稳定 ID、方洞 profile 默认值、视觉小说 work/session fallback、pending draft 默认值和木鱼 fallback 规则。
+
+这些规则属于平台壳 session / work 恢复映射，应成为可测试的 **Module**。壳层只负责调用网络、写 React state、写 URL 和切换 stage。
+
+## 决策
+
+新增 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts` 作为 Platform Mini Game Session Mapping **Module**。其公开 **Interface** 为：
+
+- `buildPuzzleRuntimeWorkFromSession(session, owner)`：从拼图 Agent session 构造可进入 runtime 的 draft `PuzzleWorkSummary`，缺草稿、缺 profile 或缺封面时返回 `null`。
+- `buildSquareHoleProfileFromSession(session)`：从方洞挑战 Agent session draft 构造草稿 `SquareHoleWorkProfile`，缺 session、缺 draft 或缺 profileId 时返回 `null`。
+- `buildVisualNovelSessionFromWorkDetail(work)`：从视觉小说 work detail 恢复 `VisualNovelAgentSessionSnapshot`，供草稿作品架回到结果页继续编辑。
+- `buildJumpHopPendingSession(item)`：从跳一跳作品架 summary 构造生成中 pending session。
+- `buildWoodenFishSessionFromWorkDetail(work, fallbackItem?)`：从敲木鱼 work detail 恢复 session，并按 summary / fallback / profileId 决定 sessionId。
+- `buildWoodenFishGeneratingWorkSummary(session, payload?)`：从敲木鱼生成 session 和可选表单 payload 构造作品架生成中摘要。
+- `buildWoodenFishPendingSession(item)`：从敲木鱼作品架 summary 构造生成中 pending session。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：调用这些映射后继续负责 `set*Session`、`set*Work`、`set*Run`、`createMiniGameDraftGenerationState(...)`、`writeCreationUrlState(...)`、`enterCreateTab()` 和 `setSelectionStage(...)`。
+
+## Interface 约束
+
+- 拼图 runtime work 必须保留 `draft.coverImageSrc` 非空门槛，避免启动缺封面的草稿运行态。
+- 拼图 profileId 优先 `publishedProfileId`，否则用 `buildPuzzleResultProfileId(sessionId)`；workId 使用 `buildPuzzleResultWorkId(sessionId)`，缺失时回退 profileId。
+- 拼图 owner 缺省为 `current-user` / `玩家`；`publishReady` 来自 `session.resultPreview?.publishReady`。
+- 方洞 profile 的 `workId` 与 `profileId` 都来自 draft `profileId`；owner 固定为 `current-user`，`sourceSessionId` 来自 sessionId。
+- 方洞 profile 的 `updatedAt` 优先 session `updatedAt`，缺失时使用当前时间；`publicationStatus='draft'`、`playCount=0`、`publishedAt=null`，`publishReady` 来自 draft。
+- 视觉小说恢复 session 的 `sessionId` 优先归一化后的 `sourceSessionId`，为空时回退 `workId`；`status='ready'`，`messages=[]`，`pendingAction=null`，`sourceMode` 来自 draft，`updatedAt` 来自 summary。
+- 跳一跳 pending sessionId 优先 `sourceSessionId`，缺失时用 `profileId`；素材、路径和 prompt 维持空值兜底。
+- 敲木鱼 detail sessionId 优先级固定为 `work.summary.sourceSessionId > fallbackItem.sourceSessionId > profileId`。
+- 敲木鱼生成中摘要的 `workId/profileId/sourceSessionId` 都来自 sessionId；标题、描述和标签优先表单 payload，其次 session draft，最后回退 `敲木鱼` / 空描述 / `['敲木鱼']`。
+- 敲木鱼 pending session 保持 `floatingWords=['功德 +1']`、素材 / 音效 / 背景为空的旧默认。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层以少量函数取得恢复用 DTO；ID 优先级、方洞 profile 默认值、视觉小说 session fallback、敲木鱼生成中摘要和 pending draft 字段藏入 Module Implementation。
+- **Leverage**：后续新增生成中作品恢复或修改 sessionId 规则时，先改 Module 与单测，再保持壳层 Adapter 副作用不变。
+- **Locality**：拼图、方洞、视觉小说、跳一跳和敲木鱼的恢复 / 生成中映射集中在一个纯测试面，避免在大型壳层顶部继续堆积 DTO 构造。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts`
+- `npx eslint src/components/platform-entry/platformMiniGameSessionMappingModel.ts src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md

@@ -0,0 +1,39 @@
+# 【前端架构】Platform Played Work Open Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 的个人“玩过作品”点击回调曾在壳层内直接判断 `worldType`、`worldKey` 前缀、玩法别名、目标 ID 兜底、RPG 公开详情 payload 和大鱼吃小鱼 gallery miss fallback。壳层因此同时承载纯打开意图与异步副作用，后续新增玩法或修正玩过作品身份时缺少稳定测试面。
+
+个人“玩过作品”的点击规则属于打开意图。壳层应只关闭面板、读取 gallery、打开详情和写错误；玩法别名、目标 ID、fallback payload 应收口到纯 **Module**。
+
+## 决策
+
+新增 `src/components/platform-entry/platformPlayedWorkOpenModel.ts` 作为 Platform Played Work Open **Module**。其公开 **Interface** 为：
+
+- `resolvePlatformPlayedWorkOpenIntent(work)`：输入 `ProfilePlayedWorkSummary`，输出 `noop`、各玩法公开详情打开意图、`open-big-fish` 或 `open-rpg`。
+- `PlatformPlayedWorkOpenIntent`：描述壳层可执行的打开动作；大鱼吃小鱼意图包含 `sessionId` 和 gallery miss 时使用的 `fallbackWork`，RPG 意图包含 `CustomWorldGalleryCard` 详情 payload。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它保留 `setIsProfilePlayStatsOpen(false)`、各玩法 `open*PublicWorkDetail`、`refreshBigFishGallery()`、大鱼 gallery 命中优先逻辑、`mapBigFishWorkToPublicWorkDetail(...)` 与错误 setter。
+
+## Interface 约束
+
+- `worldType` 只做小写归一，不 trim；`worldKey` 前缀匹配保持大小写敏感，延续旧行为。
+- `profileId` 使用 nullish 优先级：只在 `profileId` 为 `null` / `undefined` 时从 `worldKey` 前缀兜底；空字符串仍视为缺目标并返回 `noop`。
+- `puzzle` 打开时固定携带 `{ tab: 'profile' }`。
+- `match3d` / `match_3d`、`square-hole` / `square_hole`、`jump-hop` / `jump_hop`、`wooden-fish` / `wooden_fish`、`big-fish` / `big_fish` 均保持既有别名。
+- `big-fish` 缺 gallery 命中时使用 Module 生成的 `fallbackWork`，默认 `ownerUserId` 为空串、`authorDisplayName` 为 `worldSubtitle || '玩家'`、关卡和素材 ready 计数为 `0` / `false`。
+- 未识别的 `worldType` 仍按 RPG 公开详情打开；缺 `ownerUserId` 或缺 profile 目标时返回 `noop`。
+
+## Depth / Leverage / Locality
+
+- **Depth**：调用方只消费一个打开 intent；玩法别名、目标 ID 兜底和 fallback payload 藏入 Module Implementation。
+- **Leverage**：新增“玩过作品”玩法时，先在 intent union、resolver 与单测中定义，再让壳层 Adapter 绑定对应打开副作用。
+- **Locality**：RPG fallback payload 与大鱼 fallback work 不再散落在大型壳层里，维护者可在纯测试中锁定字段契约。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformPlayedWorkOpenModel.test.ts`
+- `npx eslint src/components/platform-entry/platformPlayedWorkOpenModel.ts src/components/platform-entry/platformPlayedWorkOpenModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "authenticated users can open save archives from the profile played panel"`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md

@@ -0,0 +1,32 @@
+# 【前端架构】Platform Profile Wallet Delta Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 仍内联维护个人钱包余额的本地 delta 规则：余额归一化、本地扣点 / 返还后的 dashboard 乐观更新，以及刷新服务端 dashboard 时如何抵消已经被服务端反映的本地 delta。
+
+这些规则是纯展示状态计算，但留在平台壳层会让壳层同时理解钱包余额边界、整数截断、负数保护和服务端快照对账。
+
+## 决策
+
+新增 `platformProfileWalletDeltaModel.ts`，收口钱包余额本地 delta 的纯规则：
+
+- `resolveProfileWalletBalance(...)` 负责把 dashboard 余额归一为非负整数。
+- `adjustProfileDashboardWalletBalance(...)` 负责把本地 delta 应用到 dashboard，并刷新 `updatedAt`。
+- `reconcileProfileWalletLocalDeltaWithServerDashboard(...)` 负责在拿到新服务端 dashboard 后扣除已被服务端反映的本地借贷变化。
+
+`PlatformEntryFlowShellImpl.tsx` 继续保留 API 请求、React ref、state 写入和刷新触发副作用。
+
+## 接口约束
+
+- 非数字、无穷值或空 dashboard 的余额按 `0` 处理。
+- 本地 delta 必须先 `Math.trunc`，余额不得低于 `0`。
+- 当服务端最新余额已经反映本地扣点时，剩余负 delta 应减少；已经全部反映时归零。
+- 当服务端最新余额已经反映本地返还 / 奖励时，剩余正 delta 应减少；已经全部反映时归零。
+- 服务端余额变化方向与本地 delta 相反时，不得错误抵消。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformProfileWalletDeltaModel.test.ts`
+- 针对新 Module 与 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint。
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md

@@ -0,0 +1,40 @@
+# 【前端架构】Platform Public Code Search Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 的公开搜索回调曾直接在壳层内判断 `user_` / `user-`、`PZ`、`BF`、`JH`、`WF`、`BO`、`M3`、`SH`、`VN`、`BB`、`CW`、纯数字和普通关键词的优先级。壳层因此既要持有搜索输入到查找顺序的纯规则，又要执行各玩法公开详情读取、用户读取、运行态启动和错误归航副作用。
+
+公开搜索的“先查什么、失败后回退什么”是稳定的分流规则，应有独立测试面；壳层只应作为副作用 Adapter，按计划执行网络读取与打开动作。
+
+## 决策
+
+新增 `src/components/platform-entry/platformPublicCodeSearchModel.ts` 作为 Platform Public Code Search **Module**。其公开 **Interface** 为：
+
+- `resolvePlatformPublicCodeSearchPlan(keyword)`：输入用户搜索词，输出 `{ normalizedKeyword, steps }`；空输入返回 `null`。
+- `PlatformPublicCodeSearchStep`：枚举壳层可执行的查找步骤，包括 `user-id`、`public-user-code`、`rpg-work`、各玩法公开作品步骤与 `bark-battle-work`。
+- `mapRpgPublicCodeSearchDetailToGalleryCard(entry)`：把 RPG by-code 详情响应映射为公开作品卡，收口 `playCount` / `remixCount` / `likeCount` 的 `0` 兜底。
+- `resolve*PublicCodeSearchMatch(entries, keyword)`：统一各玩法公开作品列表的公开码匹配、公开可见性过滤和详情卡 DTO 映射；拼图、大鱼吃小鱼、跳一跳、敲木鱼、宝贝识物、抓大鹅、方洞挑战、视觉小说和汪汪声浪都走此接口。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它保留 `getPublicAuthUserByCode`、各玩法 gallery 刷新 / 详情打开、Bark Battle runtime 特例和 missing work 归航副作用，只按 `steps` 顺序执行，前一步失败才尝试下一步；壳层不再重复维护 per-play `isSame*PublicWorkCode` 匹配和 DTO 映射。
+
+## Interface 约束
+
+- 空白搜索词返回 `null`，壳层不得进入搜索 loading。
+- `user_` / `user-` 开头的内部用户 ID 只执行 `user-id`，不回退作品号。
+- `PZ`、`BF`、`JH`、`WF`、`BO`、`M3`、`SH`、`VN`、`BB` 前缀只进入对应玩法公开作品查找；`M3D-*` 继续归入并匹配 `M3` / 抓大鹅。
+- `CW` 与 `1-8` 位纯数字先查 RPG 公开作品，再回退陶泥号。
+- 普通关键词与 `SY` 陶泥号保持既有顺序：先查陶泥号，再查 RPG 公开作品，再查汪汪声浪作品，最后再以陶泥号兜底。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层只消费短小的 `steps` 与 match result Interface，搜索前缀、优先级、回退顺序、per-play 匹配和 DTO 映射藏入 Module Implementation。
+- **Leverage**：新增公开作品前缀时，先扩展 Module 的 step union、前缀表、matcher 和单测，再在壳层 Adapter 绑定对应网络读取与打开动作。
+- **Locality**：搜索计划与作品命中规则集中在一个纯 Module；UI、网络、详情打开与 runtime 启动副作用继续留在壳层，避免把副作用 setter 变成浅 Interface。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformPublicCodeSearchModel.test.ts`
+- `npm run test -- src/services/publicWorkCode.test.ts`
+- `npx eslint src/components/platform-entry/platformPublicCodeSearchModel.ts src/components/platform-entry/platformPublicCodeSearchModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md

@@ -0,0 +1,68 @@
+# PlatformPublicWorkDetailFlow 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 已把公开作品身份、去重和推荐 runtime kind 收口到 `platformPublicGalleryFlow.ts`，但统一作品详情入口仍在壳层 Implementation 内直接判断 RPG、拼图、跳一跳、敲木鱼、视觉小说和其它玩法。壳层既要知道哪些公开详情可直接使用当前 entry，又要知道哪些玩法必须先补读完整详情，还要按当前用户判断详情按钮是“编辑”还是“改造”。这些是纯决策规则，继续留在巨型壳层会削弱 Locality。
+
+## 决策
+
+- 新增 `src/components/platform-entry/platformPublicWorkDetailFlow.ts` 作为 Platform Public Work Detail Flow Module。
+- Module Interface 收口：
+  - `getPlatformPublicWorkDetailKind(entry)`
+  - `resolvePlatformPublicWorkDetailOpenStrategy(entry)`
+  - `resolvePlatformPublicWorkActionMode(entry, viewerUserId)`
+  - `resolvePlatformPublicWorkEditIntent(entry, deps)`
+  - `resolvePlatformPublicWorkLikeIntent(entry)`
+  - `resolvePlatformPublicWorkRemixIntent(entry)`
+  - `resolvePlatformPublicWorkStartIntent(entry, deps)`
+  - `resolvePlatformPublicWorkDetailOpenDecision(entry, deps)`
+  - `resolveActivePlatformPublicWorkAuthorEntry(args)`
+  - `map*WorkToPublicWorkDetail(...)`
+  - `mapPublicWorkDetailToPuzzleWork(entry)`
+  - `mapPublicWorkDetailToBigFishWork(entry)`
+  - `mapPublicWorkDetailToSquareHoleWork(entry)`
+  - `mapBarkBattlePublicDetailToWorkSummary(entry)`
+  - `resolveVisiblePuzzleDetailCoverCount(entry, run)`
+- `PlatformEntryFlowShellImpl.tsx` 继续作为 Adapter：根据 open strategy 调用 `openPublicWorkDetail`、`openPuzzlePublicWorkDetail`、`openJumpHopPublicWorkDetail`、`openWoodenFishPublicWorkDetail`、`openVisualNovelPublicWorkDetail` 或 `openRpgPublicWorkDetail`。
+- 公开详情 entry 映射与公开详情反推玩法 work 摘要也收口到 Module。壳层只在运行态启动、编辑、改造、推荐缓存和详情展示时调用映射 Interface，不再在壳层顶部持有每个玩法的 DTO 拼装 Implementation。
+- `mapMatch3DWorkToPublicWorkDetail` 归入 `platformMatch3DRuntimeProfile.ts`，继续委托 `normalizeMatch3DWorkForRuntimeUi` 处理素材归一和背景资产提升；`platformPublicWorkDetailFlow.ts` 不复制 Match3D 运行态素材规则。
+- 公开详情启动、编辑、点赞和改造只抽“意图” Interface，不把整个 callback 搬进 Module。壳层继续作为 Adapter 执行鉴权、API 调用、运行态启动、草稿恢复、busy 状态、缓存同步、stage 切换和错误 setter，避免形成伪 Seam。
+
+## Interface 约束
+
+- `getPlatformPublicWorkDetailKind` 只根据 `PlatformPublicGalleryCard` 的玩法判定 helper 归一 kind；没有 `sourceType` 的公开 RPG 作品回退为 `rpg`。
+- `resolvePlatformPublicWorkDetailOpenStrategy` 只表达“如何打开详情”，不执行网络请求或 state setter。
+- 拼图、跳一跳、敲木鱼、视觉小说需要按 `profileId` 补读完整详情；返回对应 `load-*` strategy。
+- 大鱼吃小鱼、抓大鹅、方洞挑战、汪汪声浪、宝贝识物和其它可直接展示的公开 entry 返回 `use-entry` strategy。
+- RPG 返回 `load-rpg-detail` strategy，由壳层 Adapter 继续调用 RPG 详情读取流程。
+- `resolvePlatformPublicWorkActionMode` 只比较 `entry.ownerUserId` 与当前 viewer user id；当前用户拥有该公开作品时返回 `edit`，否则返回 `remix`。
+- `resolvePlatformPublicWorkEditIntent` 只表达自有公开作品编辑意图：大鱼吃小鱼、拼图、抓大鹅、方洞挑战、视觉小说和汪汪声浪在能定位原草稿时返回对应 draft open 目标；跳一跳、敲木鱼和缺草稿作品返回原阻断文案；宝贝识物只返回需解析本地草稿的 intent；旧 RPG gallery fallback 只在完整 RPG 详情已补读且 profile 匹配时返回编辑 intent。壳层仍执行草稿恢复、宝贝识物异步草稿解析、RPG 编辑导航和错误展示。
+- `resolvePlatformPublicWorkEditIntent` 的 `deps` 只接编辑决策所需的当前拼图详情、当前 RPG 详情、视觉小说作品缓存、汪汪声浪作品缓存，以及抓大鹅 public detail -> work 的 Adapter。抓大鹅 Adapter 必须来自 Match3D Runtime Profile Module，以保留 `generatedItemAssets` 归一化与背景资产提升的 Locality。
+- `resolvePlatformPublicWorkLikeIntent` 只表达公开作品点赞意图：大鱼吃小鱼、拼图和旧 RPG gallery fallback 返回可执行 intent；宝贝识物、汪汪声浪、方洞挑战和视觉小说返回不可用文案。壳层只按 intent 调用 API、写缓存和展示错误，不再持有这组能力矩阵。
+- `resolvePlatformPublicWorkRemixIntent` 只表达公开作品改造意图：大鱼吃小鱼和拼图返回可执行 intent 与成功后目标 stage，旧 RPG gallery fallback 返回可执行 intent，其它玩法返回原未开放文案。壳层只按 intent 调用 remix API、写 session / 缓存、切 stage 和展示错误。
+- `resolvePlatformPublicWorkStartIntent` 只表达公开作品“开始游玩”意图：大鱼吃小鱼、拼图、跳一跳、敲木鱼、抓大鹅、方洞挑战、视觉小说、汪汪声浪和宝贝识物返回对应启动目标；旧 RPG gallery fallback 只在完整 RPG 详情已补读且 profile 匹配时返回记录游玩 intent，否则返回原阻断文案。壳层仍执行登录保护、运行态启动、RPG 游玩记录、详情更新、busy 状态和错误展示。
+- `resolvePlatformPublicWorkStartIntent` 的 `deps` 只接启动决策所需的当前拼图详情、当前 RPG 详情、汪汪声浪作品缓存，以及抓大鹅 public detail -> work 的 Adapter。抓大鹅 Adapter 必须来自 Match3D Runtime Profile Module，以保留 `generatedItemAssets` 归一化与背景资产提升的 Locality。
+- `resolvePlatformPublicWorkDetailOpenDecision` 只表达直接展示公开详情的打开 / 阻断结果、错误文案、目标 stage 与可写入历史的路径；真正执行 setter、push history 的副作用仍由壳层 Adapter 执行。
+- `resolveActivePlatformPublicWorkAuthorEntry` 只在 `work-detail` 阶段选择统一公开详情 entry，在 RPG `detail` 阶段只选择非 draft 的 RPG 详情 entry；作者请求、竞态 request key 和缓存仍留壳层。
+- `map*WorkToPublicWorkDetail` 只把各玩法已存在的 work / gallery summary 映射为统一详情 entry；公开码、封面、统计与标题字段继续复用 `rpgEntryWorldPresentation.ts` 的平台公开卡片映射。
+- `mapPublicWorkDetailToPuzzleWork`、`mapPublicWorkDetailToBigFishWork`、`mapPublicWorkDetailToSquareHoleWork` 和 `mapBarkBattlePublicDetailToWorkSummary` 只用于公开详情 CTA、推荐缓存或运行态启动前的兼容 work 摘要拼装；缺省值必须留在 Module 测试中固定，壳层不得重复推导。
+- `resolveVisiblePuzzleDetailCoverCount` 只表达拼图公开详情封面解锁规则：非拼图、无当前 run 或 run 不属于当前公开详情时只展示首图；当前 run 属于该公开详情时按 `clearedLevelCount + 1` 解锁，但至少为 1。`PlatformWorkDetailView` 只接收 `visibleCoverCount` 展示，不读取 run。
+- Match3D 的公开详情与 work 摘要互转仍属于 Match3D Runtime Profile Module，因为它依赖 `generatedItemAssets` 归一化与背景资产提升。公开详情 Flow 只接统一详情策略，不复制该运行态规则。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层传入公开作品 entry、玩法 work summary、当前用户 id、当前拼图 run 或少量启动 / 编辑 deps，即可得到详情打开策略、动作模式、编辑 / 点赞 / 改造 / 启动意图、统一详情映射和封面可见数；玩法判定、能力矩阵与 DTO 默认值藏在 Module Implementation 内。
+- **Leverage**：新增玩法公开详情时先补 Strategy / Mapping 单测，再接壳层 Adapter，不必在多个 JSX / callback 位置重复 sourceType 判断或 DTO 回填。
+- **Locality**：公开作品详情入口的纯策略与通用映射集中到一个小 Module；Match3D 素材归一仍在 Match3D Module；启动运行态、点赞、改造、编辑等副作用仍留在壳层，避免伪 Seam。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformPublicWorkDetailFlow.test.ts`
+- `npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`
+- `npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`
+- `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx`
+- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "public detail|owned public puzzle detail|direct missing public work detail"`
+- `npx eslint src/components/platform-entry/platformPublicWorkDetailFlow.ts src/components/platform-entry/platformPublicWorkDetailFlow.test.ts --max-warnings 0`
+- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md

@@ -0,0 +1,44 @@
+# 【前端架构】Platform Puzzle Draft Recovery Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾内联维护拼图生成完成后刷新恢复的两个纯函数：`normalizeRecoveredPuzzleDraftSession` 与 `hasRecoverableGeneratedPuzzleDraft`。旧逻辑只要草稿有 `coverImageSrc`、首关 cover 或候选图，就会把恢复会话的 draft 和首关 `generationStatus` 抬成 `ready`，再进入结果页。
+
+`.hermes/shared-memory/pitfalls.md` 已记录：拼图待发布判定偏弱时，只有首图但缺关卡画面、UI spritesheet 或关卡背景的半成品会被误当完成，用户进入结果页后仍可能空图或无法发布。
+
+本切片先修前端恢复链路：只有完整首关资产包存在时，恢复流程才视为可完成。后端 `build_result_preview` / `validate_publish_requirements` / `is_puzzle_session_snapshot_publish_ready` 的发布门槛收紧另作后续切片，不混入本次前端模型收口。
+
+## 决策
+
+新增 `src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts` 作为 Platform Puzzle Draft Recovery **Module**。其公开 **Interface** 为：
+
+- `normalizeRecoveredPuzzleDraftSession(session)`：从恢复会话里补齐首图 cover、assetId 和 selectedCandidateId；只有完整资产包满足时，才把 draft 与首关 `generationStatus` 改为 `ready`。
+- `hasRecoverableGeneratedPuzzleDraft(session)`：判断恢复会话是否拥有完整首关资产包。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它继续负责拉取 session、写 background task、写 React state、打开结果页和切换 stage。
+
+## Interface 约束
+
+- 无 draft 时保持原 session，并判定不可恢复完成态。
+- 首图可来自 `draft.coverImageSrc`、首关 `coverImageSrc` 或选中 / 首个候选图。
+- 完整首关资产包必须同时具备：
+  - 首图 cover；
+  - `levelSceneImageSrc` 或 `levelSceneImageObjectKey`；
+  - `uiSpritesheetImageSrc` 或 `uiSpritesheetImageObjectKey`；
+  - `levelBackgroundImageSrc` 或 `levelBackgroundImageObjectKey`。
+- cover / assetId / selectedCandidateId 可按旧优先级从 draft、首关、候选图回填；但若完整资产包不满足，不得把 `generationStatus` 抬为 `ready`。
+- 只修复前端恢复判定，不改变拼图发布接口、后端 session stage 或后端 preview compiler。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层以两个函数表达“恢复会话归一化”和“是否可作为生成完成态恢复”；完整资产门槛和候选图 fallback 藏入 Module Implementation。
+- **Leverage**：后续后端补齐发布门槛时，可用同一资产语言对齐前端恢复模型，避免壳层再散落条件判断。
+- **Locality**：拼图恢复判定集中到纯测试面，避免在异步恢复 callback 中把半成品 ready 规则继续隐身。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformPuzzleDraftRecoveryModel.test.ts`
+- `npx eslint src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts src/components/platform-entry/platformPuzzleDraftRecoveryModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `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/【前端架构】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`

docs/technical/【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md

@@ -0,0 +1,36 @@
+# 【前端架构】Platform Recommend Runtime Auth Model 收口计划
+
+## 背景
+
+平台首页推荐流会以 embedded runtime 方式启动跳一跳、抓大鹅、方洞挑战、拼图、敲木鱼、视觉小说、大鱼吃小鱼和汪汪声浪等玩法。旧规则散在 `PlatformEntryFlowShellImpl.tsx` 顶层 helper 与多个启动 callback：匿名访客应申请 Runtime Guest Token，已登录或已有 access token 时应走 background auth，非 embedded 正常启动则不改普通鉴权。拼图还额外维护 `isolated` / `default` runtime auth mode，容易与通用推荐流口径漂移。
+
+## 决策
+
+新增 `src/components/platform-entry/platformRecommendRuntimeAuthModel.ts`，以纯 **Module** 收口推荐 runtime 鉴权计划：
+
+- `resolvePlatformRecommendRuntimeAuthPlan(input)`：返回 `requestKind` 为 `none`、`background` 或 `runtime-guest`，并给出拼图 runtime 应落到 `default` 还是 `isolated`。
+- `shouldUsePlatformRecommendRuntimeGuestAuth(input)`：只判断当前用户状态和是否允许 guest auth，不读取本地 token。
+
+`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它读取 `getStoredAccessToken()`、调用 `ensureRuntimeGuestToken()`、拼装具体 request options，并在启动拼图时写入 `setPuzzleRuntimeAuthMode(...)`。
+
+## Interface 约束
+
+- 非 embedded 且未显式允许 runtime guest auth 时，计划为 `none`。
+- embedded 推荐 runtime 若无登录用户且无本地 access token，计划为 `runtime-guest`。
+- embedded 推荐 runtime 若已有登录用户或本地 access token，计划为 `background`。
+- 拼图公开详情要求 `authMode='isolated'` 时，匿名状态应返回 `runtime-guest` 且 `puzzleRuntimeAuthMode='isolated'`。
+- 拼图公开详情要求 `authMode='isolated'` 但已登录或已有 access token 时，应回到 `default`，避免把账号态伪装成匿名 isolated guest。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层传入 embedded、是否允许 guest、用户 ID 与本地 token 布尔值，即得 request 计划和拼图 runtime auth mode。
+- **Leverage**：所有推荐 runtime 启动复用同一鉴权矩阵；新增玩法只需消费计划，不再重写匿名 / 已登录分支。
+- **Locality**：guest token 选择规则集中在纯测试面，具体 token 获取和 request options 仍留在壳层副作用 Adapter。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformRecommendRuntimeAuthModel.test.ts`
+- `npx eslint --max-warnings 0 src/components/platform-entry/platformRecommendRuntimeAuthModel.ts src/components/platform-entry/platformRecommendRuntimeAuthModel.test.ts`
+- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md

@@ -0,0 +1,40 @@
+# 【前端架构】Platform Recommend Runtime Auto Start 收口计划
+
+## 背景
+
+平台推荐页的 embedded runtime 会在移动端首页自动选择当前推荐作品并启动对应玩法。旧 `useEffect` 同时判断桌面断点、当前 stage、当前 Tab、平台 loading、推荐列表是否为空、active entry 是否仍存在、对应 runtime 是否 ready、是否已有启动请求，以及下一条 entry 应选谁。
+
+这组判断是纯推荐流自动启动决策，但留在 `PlatformEntryFlowShellImpl.tsx` 会让 effect 依赖很长，也让后续新增玩法时容易把 ready 判定和启动时机混在副作用里。
+
+## 决策
+
+扩展 `src/components/platform-entry/platformPublicGalleryFlow.ts`，新增 `resolvePlatformRecommendRuntimeAutoStartDecision(input)`：
+
+- `noop`：当前不需要改变推荐 runtime。
+- `clear`：推荐列表为空，壳层应清空 active entry、runtime kind 和错误。
+- `start`：壳层应调用既有 `selectRecommendRuntimeEntry(entry)` 启动指定作品。
+
+`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它负责收集 React state、清空 state、调用 `selectRecommendRuntimeEntry(...)` 和执行各玩法 runtime 副作用。
+
+## Interface 约束
+
+- 桌面端、非 `platform` stage、非 `home` Tab 或平台仍在 loading 时返回 `noop`。
+- 推荐列表为空时返回 `clear`。
+- active entry 存在且对应 runtime 已 ready 时返回 `noop`。
+- 当前已有启动请求时返回 `noop`。
+- active entry 存在但未 ready 时返回 `start(activeEntry)`。
+- active key 缺失或已不在列表中时返回 `start(firstEntry)`。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层只消费三态决策；列表查找、ready 判定和自动启动门禁藏入 Flow Module Implementation。
+- **Leverage**：后续推荐流新增玩法或改 ready 判定，只需补 `platformPublicGalleryFlow.ts` 的模型测试。
+- **Locality**：effect 只保留副作用动作，不再承载推荐流状态机知识。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`
+- `npx eslint --max-warnings 0 src/components/platform-entry/platformPublicGalleryFlow.ts src/components/platform-entry/platformPublicGalleryFlow.test.ts`
+- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md

@@ -0,0 +1,38 @@
+# 【前端架构】Platform RPG Agent Result Preview Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾内联维护 RPG Agent 结果页的发布门禁展示规则：从 `CustomWorldProfile` 顶层字段、`creatorIntent`、`anchorContent`、章节蓝图和场景章节中反证服务端返回的 legacy blocker 是否已经被当前结果页 profile 补齐，并同时在壳层内把 result preview source 映射成展示标签。
+
+这些逻辑不读取 React state，不请求网络，不写 URL，也不操作弹窗；它们属于 RPG Agent 结果预览展示的纯判定。壳层继续负责 session、profile、发布动作和结果页 props 编排。
+
+## 决策
+
+新增 `src/components/platform-entry/platformRpgAgentResultPreviewModel.ts` 作为 Platform RPG Agent Result Preview **Module**。其公开 **Interface** 为：
+
+- `buildPlatformRpgAgentResultPublishGateView(profile, fallbackBlockers, fallbackPublishReady)`：无 profile 时沿用服务端 fallback；有 profile 时过滤已经被当前 profile 结构字段满足的发布 blocker，并按剩余 blocker 重算展示态 `publishReady`。
+- `resolvePlatformRpgAgentResultPreviewSourceLabel(source)`：把 `published_profile`、`session_preview` 和未知 future source 映射成结果页预览来源标签。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它只把 `agentResultPreview` 与 `generatedCustomWorldProfile` 交给 Module，并将返回的 blocker / label 传入结果页组件。
+
+## Interface 约束
+
+- 无 profile 时不得自行修正 blocker，必须保留 fallback blocker message 与 fallback `publishReady`。
+- 有 profile 时只过滤已知结构 blocker：`publish_missing_world_hook`、`publish_missing_player_premise`、`publish_missing_core_conflict`、`publish_missing_main_chapter`、`publish_missing_first_act`。
+- 世界钩子兼容读取 `worldHook`、`creatorIntent.worldHook`、`anchorContent.worldPromise`、`anchorContent.worldPromise.hook` 和 `settingText`。
+- 玩家前提兼容读取 `playerPremise`、`creatorIntent.playerPremise`、`anchorContent.playerEntryPoint.openingIdentity`、`openingProblem`、`entryMotivation`。
+- 主章节兼容读取 `chapters`、`sceneChapterBlueprints`、`sceneChapters`；首幕读取 `sceneChapterBlueprints` / `sceneChapters` 下的 `acts`。
+- 未知 blocker code 不得被前端过滤；未知 source 保留“服务端预览”兜底，不做穷尽删除。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层以两个函数取得发布门禁展示和 source label；profile 兼容字段路径、legacy blocker code 与兜底规则藏入 Module Implementation。
+- **Leverage**：后续后端调整 RPG result preview blocker 或新增 source 时，先改 Module 与单测，再让壳层 Adapter 保持结果页 props 编排不变。
+- **Locality**：RPG Agent 结果预览展示规则集中到一个纯测试面，避免在大型平台壳中继续混杂 profile 结构探测。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformRpgAgentResultPreviewModel.test.ts`
+- `npx eslint src/components/platform-entry/platformRpgAgentResultPreviewModel.ts src/components/platform-entry/platformRpgAgentResultPreviewModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md

@@ -0,0 +1,32 @@
+# 【前端架构】Platform Selection Stage Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 在受保护数据失效后会清空当前用户的私有作品、运行态、草稿 notice 和生成状态。清理完成后，壳层还要判断当前 `SelectionStage` 是否还能继续展示：公开首页、公开详情、工作台入口等阶段可保留；结果页、生成页、运行态、个人反馈等依赖私有数据或运行态快照的阶段必须回到首页。
+
+此外，平台壳还曾在多个 `useEffect` 中分别判断 big-fish、match3d、square-hole、visual-novel、baby-object-match 缺少草稿、作品或 run 时应回工作台、结果页还是首页。这类“当前 stage 已不能被现有状态支撑”的规则同样属于 stage 纯判定，不应散在壳层。
+
+此前这些规则以内联长否定串或多段相似 effect 维护在壳层 **Implementation** 内。新增玩法 stage 或调整登录态行为时，维护者必须在巨型壳层中查找白名单和状态缺失回退，缺少独立测试面。
+
+## 决策
+
+新增 `src/components/platform-entry/platformSelectionStageModel.ts` 作为 Platform Selection Stage **Module**。其公开 **Interface** 为：
+
+- `resolveSelectionStageAfterProtectedDataLoss(stage)`：输入当前 `SelectionStage`，输出受保护数据失效后应停留的 stage；可保留则原样返回，否则返回 `platform`。
+- `resolveSelectionStageAfterMissingCreationState(params)`：输入当前 `SelectionStage` 与各玩法“是否有 session / draft / run / work / formPayload”等可渲染事实，输出状态缺失后应停留的 stage；仍可展示则原样返回。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 **Adapter**：负责检测受保护数据从可读变为不可读、清空各玩法缓存、重置生成和错误状态，或把当前 React state 汇总为布尔事实，并只在模型输出与当前 stage 不一致时调用 `setSelectionStage(nextStage)`。
+
+## 约定
+
+- 新增 `SelectionStage` 时，必须判断它在退出登录或鉴权上下文收回后是否仍可展示，并在本 **Module** 的全量 `Record<SelectionStage, boolean>` 与测试中列明。
+- 公开列表、公开详情和创作工作台入口可保留；依赖当前用户私有数据、生成 session、运行态 run 或个人资料的 stage 默认回 `platform`。
+- 缺失状态回退只读取壳层传入的布尔事实，不直接读取玩法 session / work / run 对象。big-fish、match3d、square-hole 的草稿事实必须来自 `Boolean(session?.draft)`；visual-novel 的 session draft 与 work draft 可独立支撑结果页；baby-object-match runtime 缺 draft 时不看 formPayload，直接回 `platform`。
+- 此 **Module** 不清理 state、不调用路由、不触发登录弹窗，只表达纯 stage 决策。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformSelectionStageModel.test.ts`
+- `npx eslint src/components/platform-entry/platformSelectionStageModel.ts src/components/platform-entry/platformSelectionStageModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`

docs/technical/【前端架构】ProfileDashboardPresentation收口计划-2026-06-03.md

@@ -0,0 +1,30 @@
+# 【前端架构】Profile Dashboard Presentation 收口计划
+
+## 背景
+
+`RpgEntryHomeView.tsx` 的“我的数据”、钱包 chip 和“玩过”弹窗共用一批展示规则：泥点数量压缩、累计时长固定小时展示、单作品游玩时长压缩、作品类型标签和作品 ID 兜底。原先这些规则散在页面 **Implementation** 内，导致格式口径只能靠 UI 集成测试间接保护。
+
+## 决策
+
+新增 `src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts`，作为个人数据展示 **Module**。该 **Module** 的 **Interface** 收口为：
+
+- `buildProfileDashboardPresentation(dashboard)`：统一生成钱包余额、钱包文案、累计时长文案和已玩数量文案。
+- `formatDashboardCount(value)`：统一泥点和计数压缩规则。
+- `formatTotalPlayTimeHours(playTimeMs)`：统一“累计游戏时长”固定小时口径。
+- `formatCompactPlayTime(playTimeMs)`：统一“玩过”单作品紧凑时长。
+- `formatPlayedWorkType(value)` 与 `formatPlayedWorkId(work)`：统一“玩过”列表里的玩法标签和作品号兜底。
+
+`RpgEntryHomeView.tsx` 只消费这些 presentation 函数，保留卡片、弹窗和点击处理。个人数据展示规则的 **Locality** 转移到该 **Module** 与纯测试，后续修改计数、时长或作品类型标签不再穿透页面 JSX。
+
+## 约定
+
+- `formatDashboardCount` 与公开作品卡片的 `formatCompactCount` 不合并，二者展示口径不同。
+- “累计游戏时长”固定以小时展示，避免个人数据卡在分钟 / 天之间跳动。
+- “玩过”列表当前仍按历史契约用 `profileId || worldKey` 展示作品号；若后端未来下发 `publicWorkCode`，应在此 **Module** 改口径。
+
+## 验证
+
+- `npm run test -- src/components/rpg-entry/rpgEntryProfileDashboardPresentation.test.ts`
+- `npm run typecheck`
+- `npm run check:encoding`
+- 针对变更文件执行 ESLint