Genarrative/docs/technical/RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md

推荐页运行态鉴权失败隔离修复

日期：2026-05-09

背景

登录成功进入平台推荐页后，推荐页会自动加载一个公开作品并启动嵌入式运行态。实际联调中出现过：作品刚加载出来，前端又瞬间回到未登录状态；停留在其他页面，或推荐页没有成功加载出作品时不会复现。

根因

推荐页首屏的作品运行态启动是后台自动副作用，不是用户主动点击的账号操作。它会触发多条受保护请求，例如：

1. 拼图、抓大鹅、方洞挑战、视觉小说的 start run。
2. 大鱼吃小鱼的 start run 与游玩记录上报。
3. 视觉小说运行前的作品详情读取。

这些请求一旦遇到本地代理错配、后端短暂不可用或 token 刷新失败，原请求层会按普通受保护请求处理 401，清空 access token 并广播全局鉴权变更。AuthGate 收到事件后重新 hydrate，于是当前用户界面被切回未登录态。

修复

本次把推荐页自动运行态请求定义为“卡片级后台请求”：

1. apiClient 增加 clearAuthOnUnauthorized 选项，允许局部请求在 401 时不清空全局 token。
2. 推荐页嵌入式运行态请求统一传入 skipRefresh: true、notifyAuthStateChange: false、clearAuthOnUnauthorized: false。
3. 推荐页自动启动作品前必须满足 canReadProtectedData，避免 AuthGate 仍在恢复阶段就提前发起受保护写请求。
4. 普通用户主动点击“启动”、Remix、发布、点赞等路径继续保留默认全局鉴权处理。

验证

1. npm run test -- src/services/apiClient.test.ts
2. npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation starts embedded puzzle"
3. npm run typecheck
4. npm run check:encoding

关联文件

1. src/services/apiClient.ts
2. src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
3. src/services/*-runtime/*RuntimeClient.ts
4. src/services/visual-novel-works/visualNovelWorksClient.ts