1

docs/technical/CREATION_ENTRY_AUTH_ERROR_GUARD_FIX_2026-04-22.md

@@ -0,0 +1,85 @@
+# 创作入口鉴权错误串味修复
+
+日期：`2026-04-22`
+
+## 1. 问题现象
+
+平台首页点击“创作”后，用户在创作入口浮层或创作中心起始卡片中会看到：
+
+- `缺少 Authorization Bearer Token`
+
+该文案直接暴露了后端鉴权实现细节，不符合平台入口的产品语义，也会让用户误以为“点击创作弹窗本身就失败了”。
+
+## 2. 根因拆解
+
+本次问题实际由两层叠加造成：
+
+1. `useRpgCreationSessionController` 把“恢复旧 Agent 会话失败”的错误写入 `creationTypeError`。
+2. `PlatformEntryFlowShellImpl` 又把 `creationTypeError` 同时透传给：
+   - 创作中心起始卡片 `createError`
+   - 创作类型浮窗 `error`
+   - 平台首页 `platformError`
+
+结果是：
+
+- 旧会话恢复失败
+- 未登录态残留会话恢复
+- 本地 access token 丢失但 refresh cookie 仍在
+
+这些与“当前点击新建创作”并不完全等价的错误，被错误地展示到了新建创作入口上。
+
+## 3. 修复策略
+
+### 3.1 错误分层
+
+在 `useRpgCreationSessionController` 中新增：
+
+- `agentWorkspaceRestoreError`
+
+约束：
+
+1. 旧 Agent 会话恢复失败只写入 `agentWorkspaceRestoreError`
+2. 用户主动点击新建创作失败才写入 `creationTypeError`
+3. 创作中心起始卡片和创作类型浮窗只展示“新建入口错误”
+4. 平台页和工作区恢复占位文案展示“恢复态错误”
+
+### 3.2 鉴权兜底
+
+在 `fetchWithApiAuth` 中补充规则：
+
+1. 受保护请求若本地没有 bearer token
+2. 且请求未声明 `skipAuth / skipRefresh`
+3. 先尝试 `ensureStoredAccessToken()` 静默补票
+4. 补票失败再继续原始请求
+
+这样可以覆盖“refresh cookie 仍有效，但本地 access token 丢失”的场景，避免后端直接返回“缺少 Authorization Bearer Token”。
+
+### 3.3 用户态错误文案收敛
+
+`resolveRpgEntryErrorMessage` 对 `401 UNAUTHORIZED` 与 `缺少 Authorization Bearer Token` 统一映射为：
+
+- `当前登录状态已失效，请重新登录后继续。`
+
+目标是把后端实现细节收束成平台用户可理解的恢复动作。
+
+## 4. 影响范围
+
+本轮覆盖：
+
+1. RPG / Custom World 创作入口
+2. 平台创作中心起始卡片
+3. 平台创作类型浮窗
+4. 统一前端 API 鉴权请求层
+
+本轮不改：
+
+1. 后端 `401` 契约
+2. 登录弹窗交互
+3. Big Fish / Puzzle 的后端路由鉴权策略
+
+## 5. 验收
+
+1. 点击“创作”后，不再出现原始 `Authorization Bearer Token` 报错文案
+2. 旧会话恢复失败时，错误只停留在恢复上下文，不污染新建创作入口
+3. 本地 token 丢失但 refresh 仍有效时，前端可自动补票后继续请求
+4. 相关测试与编码检查通过