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

日期：`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`