Genarrative/docs/technical/SPACETIME_AUTH_TOKEN_FALLBACK_HOTFIX_2026-04-20.md

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