refactor: 收口抓大鹅运行资料模型

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，不在本切片扩大处理。