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

登录恢复与推荐页加载态收口修复

日期：2026-05-09

背景

推荐页作品卡偶发一直停留在“加载中...”，同时刷新网页后可能从已登录态回到未登录态。两类问题都发生在平台入口首屏和登录态恢复链路中，表现上像推荐页问题，实际涉及 AuthGate、请求层 token 处理和推荐页嵌入运行态的启动状态机。

根因

刷新网页掉线的关键根因是 AuthGate hydrate 先强制调用 refreshStoredAccessToken()。如果 refresh cookie 临时不可用、代理错配或后端短暂返回 401，该方法会清掉本地 access token，随后 /api/auth/me 只能恢复成未登录。

推荐页作品卡卡住加载中的根因是推荐页自动启动运行态时，activeRecommendEntryKey 和 activeRecommendRuntimeKind 先被设置，失败时只把 kind 置空或由玩法内部写错误；外层没有稳定的 activeRecommendRuntimeError 收口。并发切换作品时，旧启动请求也可能晚到覆盖新启动状态。

修复

1. refreshStoredAccessToken() 增加 clearOnFailure 选项，默认保持原全局恢复语义；显式传 false 时 refresh 失败不会清空现有 access token。
2. AuthGate 已有本地 access token 时，先用 /api/auth/me 确认当前用户；确认成功后再后台调用 refresh 续期与写每日登录埋点。后台 refresh 失败只静默忽略，不再把已确认账号改成未登录。
3. 本地没有 access token 时，AuthGate 仍通过 refresh cookie 补票；该路径失败会清 token 并落到未登录，保持原有安全语义。
4. 推荐页 selectRecommendRuntimeEntry 增加启动请求版本号。旧请求晚到后直接丢弃，不能覆盖当前作品。
5. 推荐页运行态启动失败时统一写入 activeRecommendRuntimeError = "作品暂时无法进入，请稍后再试。"，并关闭 isStartingRecommendEntry，避免作品卡永久显示加载态。
6. 推荐页入口继续保持登录门禁。未登录用户点击推荐 Tab 只切到推荐封面并弹出登录弹窗；未登录状态下点击推荐封面再次弹出登录弹窗，不打开详情、不启动运行态。
7. RpgEntryHomeView 将公开作品详情入口与推荐页入口拆成 onOpenGalleryDetail 和 onOpenRecommendGalleryDetail：发现页、搜索结果和排行榜仍可按公开浏览能力打开详情；推荐页封面、推荐运行态错误重试、桌面推荐模块统一走推荐门禁入口。

验证

1. npm run test -- src/services/apiClient.test.ts src/components/auth/AuthGate.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "explicit refresh opts out|auth gate keeps a valid local token login|home recommendation"
2. 后续完整收口仍建议执行：
   • npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx src/components/auth/AuthGate.test.tsx src/services/apiClient.test.ts
   • npm run test -- src/services/apiClient.test.ts src/components/auth/AuthGate.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
   • npm run typecheck
   • npm run check:encoding

关联文件

1. src/services/apiClient.ts
2. src/components/auth/AuthGate.tsx
3. src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
4. src/components/rpg-entry/RpgEntryHomeView.tsx
5. src/components/auth/AuthGate.test.tsx
6. src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
7. src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx