fix auth login state race

docs/technical/AUTH_GATE_LOGIN_RACE_GUARD_FIX_2026-05-09.md

@@ -0,0 +1,37 @@
+# `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`