fix recommend runtime auth isolation

docs/technical/RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md

@@ -0,0 +1,40 @@
+# 推荐页运行态鉴权失败隔离修复
+
+日期：`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`