Genarrative/.hermes/skills/genarrative-admin-backoffice/references/daily-login-auth-closure.md

真实登录成功链路接入每日登录埋点（2026-05-08）

背景

后台“埋点数据”页要能看到真实登录产生的 daily_login。此前已完成方案 A：把“读取任务中心时顺手写每日登录埋点”拆成独立 SpacetimeDB procedure/client 方法，避免后台查看或刷新任务中心污染登录数据。

闭环时不要再把写入点放回任务中心读取流程；应在认证成功且会话签发后显式调用每日登录埋点入口。

推荐接入点

在 api-server 认证成功路径中，先创建/签发会话，再非阻断记录埋点，再同步认证快照并返回：

1. create_auth_session / create_password_auth_session 成功。
2. 调用统一 helper：record_daily_login_tracking_event_after_auth_success(...)。
3. helper 调用 state.spacetime_client().record_daily_login_tracking_event(user_id.to_string()).await。
4. 成功写 info，失败写 warn，不能把埋点失败返回给用户。

已验证的真实登录链路包括：

• 手机验证码登录：server-rs/crates/api-server/src/phone_auth.rs 的 phone_login。
• 密码登录入口：server-rs/crates/api-server/src/password_entry.rs 的 password_entry。
• 重置密码后自动登录：server-rs/crates/api-server/src/password_management.rs 的 reset_password。
• 微信 OAuth 回调登录：server-rs/crates/api-server/src/wechat_auth.rs 的 handle_wechat_callback。
• 微信绑定手机号后自动登录：server-rs/crates/api-server/src/wechat_auth.rs 的 bind_wechat_phone。
• refresh cookie 续期：server-rs/crates/api-server/src/refresh_session.rs 的 refresh_session。在 rotate_session 成功并签发新 access token 后记录，login_method 应使用 rotated.session.issued_by_provider.clone()，不要固定写成 Password。

关键实现约束

• 埋点是运营数据，必须保持非阻断：SpacetimeDB 调用失败只记录日志，不影响登录成功返回。
• helper 建议放在 auth_session.rs，避免各登录 handler 重复错误处理。
• refresh cookie 续期也被产品视为一次每日登录触发；接入 refresh_session.rs 时必须放在 token rotate 和 access token 签发成功之后，且保持非阻断，避免刷新失败或缺 cookie 时误写埋点。
• handle_wechat_callback 如果要记录 request_id/operation，需要在 handler 参数中补 Extension<RequestContext>；确认路由层已注入 RequestContext。
• 单元测试默认不启动 SpacetimeDB。若直接调用真实 spacetime_client 会让既有认证测试依赖外部服务；可在 #[cfg(test)] 下让 helper no-op，仅用编译和现有登录成功测试覆盖调用点不破坏返回。
• 后续如需要严格断言“helper 被调用”，应优先为 Spacetime client 引入可注入 trait/mock，而不是让 API 单测连接真实 SpacetimeDB。

验证命令

cd server-rs
cargo fmt -p api-server --check
cargo check -p api-server
cargo check -p spacetime-client
cargo test -p api-server auth_session -- --nocapture
cargo test -p api-server refresh_session_rotates_cookie_and_returns_new_access_token -- --nocapture
cargo test -p api-server password_entry_logs_in_existing_phone_user_and_sets_refresh_cookie -- --nocapture
cargo test -p api-server phone_login_creates_user_and_sets_refresh_cookie -- --nocapture
cd ..
npm run check:encoding
git diff --check

提交注意

• 不要提交 .env.local、.env.secrets.local 或任何 token/密码/连接串。
• 若工作区里有本地敏感文件，只提交明确改动的 Rust 文件和 docs/technical/* 文档。