# 真实登录成功链路接入每日登录埋点（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。

## 验证命令

```bash
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/*` 文档。