Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,59 +0,0 @@
|
||||
# 推荐页运行态鉴权失败隔离修复
|
||||
|
||||
日期：`2026-05-09`
|
||||
|
||||
## 背景
|
||||
|
||||
登录成功进入平台推荐页后，推荐页会自动加载一个公开作品并启动嵌入式运行态。实际联调中出现过：作品刚加载出来，前端又瞬间回到未登录状态；停留在其他页面，或推荐页没有成功加载出作品时不会复现。
|
||||
|
||||
后续复测又发现：登录成功后，从推荐页点进拼图公开作品详情并启动完整拼图运行态，也可能在开局或通关后瞬间退回未登录。两类现象的底层问题一致，都是玩法/展示层局部请求把 `401` 扩散成全局鉴权事件。
|
||||
|
||||
## 根因
|
||||
|
||||
推荐页首屏的作品运行态启动是后台自动副作用，不是用户主动点击的账号操作。它会触发多条受保护请求，例如：
|
||||
|
||||
1. 拼图、抓大鹅、方洞挑战、视觉小说的 `start run`。
|
||||
2. 大鱼吃小鱼的 `start run` 与游玩记录上报。
|
||||
3. 视觉小说运行前的作品详情读取。
|
||||
|
||||
这些请求一旦遇到本地代理错配、后端短暂不可用或 token 刷新失败，原请求层会按普通受保护请求处理 `401`，清空 access token 并广播全局鉴权变更。`AuthGate` 收到事件后重新 hydrate，于是当前用户界面被切回未登录态。
|
||||
|
||||
再次复测确认还有更深一层根因：即使单个业务请求显式传了 `clearAuthOnUnauthorized: false`，`refreshAccessToken()` 自身在 refresh 失败时也会先静默清空本地 access token。这样局部请求可能没有广播事件，却已经把本地凭证掏空；后续任意一次默认鉴权探测或 `AuthGate` hydrate 都会变成未登录。
|
||||
|
||||
推荐页进入公开拼图作品后还会伴随平台侧私有投影刷新，例如存档列表、浏览历史、个人看板和作品架列表。这些请求用于页面展示与局部缓存同步，不是账号会话权威；其中任意一个 401 都不应把整站登录态改写为未登录。
|
||||
|
||||
推荐页里还有一类更隐蔽的触发点：`ResolvedAssetImage` / `useResolvedAssetReadUrl` 在挂载时会请求 `/api/assets/read-url` 给 generated 私有图片换签。它本质上也是展示层后台请求，若按普通受保护请求处理 `401`，同样会把一次图片换签失败放大成全局掉线。
|
||||
|
||||
公开拼图作品的完整运行态还会在用户进入作品后自动发起 `startPuzzleRun`，通关后自动 `submitPuzzleLeaderboard`，点击下一关时 `advancePuzzleNextLevel`。这些请求属于当前玩法的运行态同步，失败时应该落到当前拼图错误态；它们不能清空全局 access token，也不能触发 `AuthGate` 重新 hydrate。
|
||||
|
||||
## 修复
|
||||
|
||||
本次把推荐页自动运行态请求定义为“卡片级后台请求”：
|
||||
|
||||
1. `apiClient` 增加 `authImpact: 'global' | 'local'` 策略，并导出 `BACKGROUND_AUTH_REQUEST_OPTIONS`。`local` 请求统一跳过 refresh，不清空 token，不广播 `AUTH_STATE_EVENT`。
|
||||
2. `refreshAccessToken()` 不再自行清空 token；只有 `refreshStoredAccessToken()` 这类全局会话恢复入口和默认全局请求策略能决定清 token。
|
||||
3. 推荐页嵌入式运行态请求统一使用 `BACKGROUND_AUTH_REQUEST_OPTIONS`。
|
||||
3. 推荐页自动启动作品前必须满足 `canReadProtectedData`，避免 `AuthGate` 仍在恢复阶段就提前发起受保护写请求。
|
||||
4. generated 图片换签请求同样使用局部后台鉴权选项并跳过 refresh，失败只让当前图片为空，不触发全局登录态清理。
|
||||
5. 公开拼图作品进入完整运行态后，把本次 run 标记为 `isolated` 鉴权模式；开局、重开、排行榜提交和下一关推进都沿用局部鉴权选项。
|
||||
6. 平台 bootstrap 的私有投影读写，包括个人看板、私有作品架、创作作品列表、浏览历史写入和存档列表刷新，也统一作为局部后台请求处理。
|
||||
7. Remix、发布、点赞、账号设置、退出登录等真正账号动作继续保留默认全局鉴权处理。
|
||||
|
||||
## 验证
|
||||
|
||||
1. `npm run test -- src/services/apiClient.test.ts src/services/assetReadUrlService.test.ts`
|
||||
2. `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation starts embedded puzzle"`
|
||||
3. `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle runtime uses frontend move merge logic and backend leaderboard"`
|
||||
4. `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle similar work keeps current run level progression"`
|
||||
5. `npm run typecheck`
|
||||
6. `npm run check:encoding`
|
||||
|
||||
## 关联文件
|
||||
|
||||
1. `src/services/apiClient.ts`
|
||||
2. `src/services/rpg-runtime/rpgRuntimeRequest.ts`
|
||||
3. `src/services/rpg-creation/rpgCreationRuntimeClient.ts`
|
||||
4. `src/components/rpg-entry/useRpgEntryBootstrap.ts`
|
||||
5. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
6. `src/services/*-runtime/*RuntimeClient.ts`
|
||||
7. `src/services/visual-novel-works/visualNovelWorksClient.ts`
|
||||
Reference in New Issue
Block a user