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

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