Genarrative/docs/technical/CREATION_ENTRY_AUTH_ERROR_GUARD_FIX_2026-04-22.md

创作入口鉴权错误串味修复

日期：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. 相关测试与编码检查通过