修复报错

docs/technical/SPACETIME_AUTH_TOKEN_FALLBACK_HOTFIX_2026-04-20.md

@@ -0,0 +1,67 @@
+# Spacetime 账号连接过期回退热修 2026-04-20
+
+## 背景
+
+当前网页启动时会先尝试复用本地保存的 Spacetime token 建立账号连接。
+
+问题表现：
+
+- 页面长时间停留在“正在建立账号连接...”
+- 本地 token 已失效时，前端没有稳定降级到匿名账号
+- 用户看不到明确的“登录已过期”提示，只会感觉页面卡住
+
+## 目标
+
+本次热修只处理登录恢复链路，不扩散到其他运行时模块：
+
+- 本地 token 登录失败或超时后，自动清理失效 token
+- 立即改走匿名连接，恢复页面可用性
+- 在进入匿名账号后给出一次明确提示：登录已过期，已切换为匿名账号
+
+## 落地方案
+
+### 1. 账号恢复层增加 token 失效回退
+
+文件：
+
+- `src/services/authService.ts`
+
+调整点：
+
+- `getCurrentAuthUser()` 底层恢复流程增加 `recoveryNotice`
+- 当浏览器本地存在 token 时，首次建连增加短超时保护
+- 若首次建连失败或超时：
+  - 断开当前 Spacetime 连接
+  - 清空本地 access token
+  - 重新以匿名身份建连
+- 匿名建连成功后，返回 `login_expired` 恢复结果给 UI
+
+### 2. 认证门面增加非阻塞提示
+
+文件：
+
+- `src/components/auth/AuthGate.tsx`
+
+调整点：
+
+- `AuthGate` 成功恢复到匿名账号后，展示顶部轻量提示条
+- 文案为“登录已过期，已切换为匿名账号。”
+- 提示条会自动收起，也允许用户手动关闭
+- 不阻断页面继续进入主内容
+
+## 验证
+
+已完成：
+
+- `npx vitest run src/services/authService.test.ts src/components/auth/AuthGate.test.tsx`
+- `npm run check:encoding`
+
+新增覆盖：
+
+- 本地 token 连接卡住时，会自动回退到匿名账号
+- 匿名回退成功后，页面会显示“登录已过期”提示
+
+## 备注
+
+- `npm run typecheck` 当前仓库仍存在其他模块的存量报错，本次热修没有继续扩散处理
+- 本次已消除本热修涉及文件新增的类型问题，剩余报错集中在 `storageService`、`CustomWorld*` 与 `runtimeStoryService.test.ts`