refactor: 收口推荐 runtime 鉴权计划

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`