Genarrative/docs/technical/AUTH_GATE_LOGIN_RACE_GUARD_FIX_2026-05-09.md

AuthGate 登录后又回到未登录状态修复

日期：2026-05-09

背景

本地联调中，手机号验证码登录有时会先显示登录成功，随后又瞬间回到未登录态。

根因

AuthGate 首次挂载时会异步 hydrate：

1. 先轮换 refresh cookie
2. 再请求 /api/auth/me
3. 再根据结果写入 user 和 status

如果用户在这轮 hydrate 尚未完成时已经完成了登录，后到达的旧 hydrate 结果仍可能把刚写入的 user 覆盖回 null，导致登录态闪回未登录。

修复

AuthGate 增加 hydrate 版本号保护：

1. 每次启动 hydrate 都分配独立版本号。
2. 登录成功、退出登录、收到全局 auth state 事件时递增版本号。
3. 旧版本 hydrate 的结果到达后直接丢弃，不再覆盖当前 user / status。

验证

1. npm run test -- src/components/auth/AuthGate.test.tsx
2. npm run test -- src/services/apiClient.test.ts src/services/authService.test.ts
3. npm run check:encoding

关联

• src/components/auth/AuthGate.tsx
• src/components/auth/AuthGate.test.tsx
• .hermes/shared-memory/pitfalls.md