133 lines
7.0 KiB
Markdown
133 lines
7.0 KiB
Markdown
---
|
||
name: genarrative-auth-session-flow
|
||
description: 在 Genarrative 中排查或修改登录、access token、refresh cookie、AuthGate 会话恢复、登录态刷新、认证埋点链路时使用。
|
||
version: 1.0.0
|
||
author: Hermes Agent
|
||
license: MIT
|
||
metadata:
|
||
hermes:
|
||
tags: [Genarrative, auth, session, cookie, refresh-token, AuthGate, tracking]
|
||
related_skills: [systematic-debugging, test-driven-development, genarrative-profile-features]
|
||
---
|
||
|
||
# Genarrative 认证会话与登录埋点链路
|
||
|
||
用于 Genarrative 中登录、会话恢复、refresh cookie 续期、access token 补票、AuthGate 恢复登录态，以及每日登录/认证相关埋点的排查与修改。
|
||
|
||
## 适用场景
|
||
|
||
- 用户反馈登录态、cookie、自动续期、刷新页面后状态异常。
|
||
- 修改 `AuthGate`、`apiClient`、`authService` 或 Rust `api-server` 认证接口。
|
||
- 排查“已登录但打开网页没有触发登录埋点”等 session restore 场景。
|
||
- 修改手机验证码登录、密码登录、微信登录、重置密码后自动登录、refresh session rotate。
|
||
- 需要判断某个前端动作是否真正调用了后端 refresh/session 或埋点 procedure。
|
||
|
||
## 关键代码路径
|
||
|
||
前端：
|
||
|
||
- `src/components/auth/AuthGate.tsx`
|
||
- 登录态 hydrate / restore 的入口。
|
||
- 监听 `AUTH_STATE_EVENT` 后重新 hydrate。
|
||
- 是否先 refresh、再 `/api/auth/me`，决定打开页面是否进入后端 refresh 链路。
|
||
- `src/services/apiClient.ts`
|
||
- access token 本地保存、`ensureStoredAccessToken()`、`refreshStoredAccessToken()`、`fetchWithApiAuth()`。
|
||
- `ensureStoredAccessToken()` 有 token 时会直接复用，不一定触发后端 refresh。
|
||
- `refreshStoredAccessToken()` 应直接调用 refresh 接口，用于必须轮换 cookie / 写续期埋点的场景。
|
||
- `src/services/authService.ts`
|
||
- `getCurrentAuthUser()` 请求 `/api/auth/me`。
|
||
- 登录、登出、账号安全相关 API client。
|
||
|
||
后端：
|
||
|
||
- `server-rs/crates/api-server/src/auth_session.rs`
|
||
- 创建 refresh cookie / access token。
|
||
- `record_daily_login_tracking_event_after_auth_success(...)` 统一写每日登录埋点；失败 warning，不阻断认证流程。
|
||
- `server-rs/crates/api-server/src/refresh_session.rs`
|
||
- `POST /api/auth/session/refresh`。
|
||
- rotate refresh session、签发新 access token、记录每日登录埋点。
|
||
- `server-rs/crates/api-server/src/auth_me.rs`
|
||
- `/api/auth/me` 只读取当前 access token 对应用户，不应假设它会触发 refresh 或登录埋点。
|
||
- `server-rs/crates/api-server/src/phone_auth.rs`
|
||
- `server-rs/crates/api-server/src/password_entry.rs`
|
||
- `server-rs/crates/api-server/src/password_management.rs`
|
||
- `server-rs/crates/api-server/src/wechat_auth.rs`
|
||
- 各真实认证成功入口。
|
||
- `server-rs/crates/spacetime-client/src/runtime.rs`
|
||
- `record_daily_login_tracking_event(user_id)` 调用 SpacetimeDB procedure。
|
||
- `server-rs/crates/spacetime-module/src/runtime/profile.rs`
|
||
- `record_daily_login_tracking_event_and_return` procedure。
|
||
- 任务中心读取不应污染每日登录埋点；如看到 `get_profile_task_center` 顺手写 `daily_login`，优先复核是否回归。
|
||
|
||
## 调试顺序
|
||
|
||
1. 先明确用户场景属于哪类：
|
||
- 新登录成功。
|
||
- cookie/access token 已过期后的自动刷新。
|
||
- 已登录且 cookie/access token 未过期时打开网页。
|
||
- 只调用 `/api/auth/me` 或某个受保护业务接口。
|
||
2. 查前端实际调用链，不要只看后端埋点点位：
|
||
- `AuthGate` hydrate 是否调用 `refreshStoredAccessToken()`？
|
||
- 是否只是 `ensureStoredAccessToken()` + `/api/auth/me`？
|
||
- `fetchWithApiAuth()` 是否因为已有 access token 而跳过 refresh？
|
||
3. 查后端实际埋点点位：
|
||
- 登录成功入口是否在 session 创建后调用 helper。
|
||
- refresh session 是否在 rotate 与 access token 签发成功后调用 helper。
|
||
- 失败策略是否只 warning、不阻断响应。
|
||
4. 如涉及 SpacetimeDB procedure/table/binding，按项目 SpacetimeDB skills 与文档同步检查绑定生成、`migration.rs`、private table 限制。
|
||
5. 修改前补齐 `docs/technical/` 中对应方案/根因；修改后同步更新。
|
||
|
||
## 关键经验：已登录打开网页也要主动 refresh 才能写登录埋点
|
||
|
||
常见误判：后端已经在 refresh cookie 续期时写每日登录埋点，就以为“打开网页”会触发埋点。
|
||
|
||
实际链路中，如果用户已经登录且本地 access token 还有效：
|
||
|
||
1. `ensureStoredAccessToken()` 会直接返回已有 token。
|
||
2. `AuthGate` 随后请求 `/api/auth/me`。
|
||
3. `/api/auth/me` 只校验/读取用户，不会 rotate refresh session。
|
||
4. 因此后端 refresh/session 埋点不会触发。
|
||
|
||
若产品要求“已登录且 cookie 没过期时打开网页也记录登录埋点”，`AuthGate` 的 restore/hydrate 应主动调用 `refreshStoredAccessToken()`，再调用 `getCurrentAuthUser()`。
|
||
|
||
## 每日登录埋点原则
|
||
|
||
- 真实登录成功：在 refresh session / access token 创建成功后记录。
|
||
- cookie refresh 续期：在 rotate refresh session 成功且新 access token 签发成功后记录。
|
||
- 已登录打开网页：前端必须主动走 refresh 续期链路，不能只请求 `/api/auth/me`。
|
||
- `login_method` 对于 refresh 场景使用 refresh session 保存的 `issued_by_provider`。
|
||
- 埋点失败不阻断登录、续期、会话恢复或 token 返回，只记录 warning。
|
||
- 任务中心读取不应作为登录埋点来源，避免后台查看/刷新任务中心污染登录数据。
|
||
|
||
## 测试与验证命令
|
||
|
||
按改动范围选择：
|
||
|
||
```bash
|
||
npm run test -- AuthGate.test.tsx
|
||
npm run typecheck
|
||
cd server-rs && cargo test -p api-server auth_session -- --nocapture
|
||
cd server-rs && cargo test -p api-server refresh_session_rotates_cookie_and_returns_new_access_token -- --nocapture
|
||
cd server-rs && cargo check -p api-server
|
||
cd server-rs && cargo check -p spacetime-client
|
||
cd server-rs && cargo check -p spacetime-module
|
||
npm run check:encoding
|
||
git diff --check
|
||
```
|
||
|
||
注意：Vitest 0.34 不支持 Jest 的 `--runInBand`；不要把 `--runInBand` 加到 `npm run test -- AuthGate.test.tsx` 后面。
|
||
|
||
## 常见坑
|
||
|
||
1. 把 `/api/auth/me` 当作 refresh：它只读当前 access token，不会写 refresh 埋点。
|
||
2. 只在后端 refresh handler 加埋点，但前端有有效 access token 时根本不调用 refresh。
|
||
3. `ensureStoredAccessToken()` 有 token 时会直接返回；需要强制 refresh 时应使用 `refreshStoredAccessToken()`。
|
||
4. 在埋点 helper 中返回错误并阻断登录/续期，会破坏认证主链路。
|
||
5. refresh 场景把 `login_method` 写死为 password，会丢失手机/微信来源。
|
||
6. 修改中文文件后忘记 `npm run check:encoding`。
|
||
7. `cargo fmt -p api-server` 或前端测试可能让 `.env.local`、`.gitignore` 出现非业务改动；提交前用 `git status --short` 检查并撤回无关敏感/环境文件。
|
||
|
||
## 参考资料
|
||
|
||
- `references/session-restore-daily-login-tracking-2026-05-08.md`：已登录且 cookie 未过期时打开网页未触发每日登录埋点的根因与修复案例。
|