Genarrative/docs/technical/AUTH_ME_QUERY_DESIGN_2026-04-21.md

/api/auth/me 查询落地设计

日期：2026-04-21

1. 文档目的

这份文档用于指导 M2 中 实现 me 查询 任务的首版落地，冻结：

1. GET /api/auth/me 的请求与响应 contract。
2. 当前阶段 Bearer JWT 与用户快照读取的衔接方式。
3. availableLoginMethods 的返回口径。
4. JWT 有效但本地用户不存在时的错误处理语义。

2. 当前基线

当前 Node /api/auth/me 具备以下最小语义：

1. 必须先通过 Bearer JWT 校验。
2. 用 sub = user_id 读取当前用户。
3. 返回 user + availableLoginMethods。
4. availableLoginMethods 只返回当前对外开启的补充登录方式，不包含 password。

Rust 首版需要保留这条最小 contract，但当前阶段允许继续使用进程内仓储承接用户真相。

3. 当前阶段范围

本阶段只落以下内容：

1. module-auth 增加按 user_id 查询当前用户能力。
2. api-server 暴露 GET /api/auth/me。
3. 返回与当前前端兼容的 user + availableLoginMethods。

本阶段不包含：

1. refresh token 轮换。
2. 会话列表、审计、风控等扩展信息。
3. SpacetimeDB 真正的身份表读取。

4. contract

4.1 请求

1. 方法：GET
2. 路径：/api/auth/me
3. 鉴权：Authorization: Bearer <token>

4.2 成功响应

{
  "user": {
    "id": "user_00000001",
    "username": "guest_001",
    "displayName": "guest_001",
    "phoneNumberMasked": null,
    "loginMethod": "password",
    "bindingStatus": "active",
    "wechatBound": false
  },
  "availableLoginMethods": []
}

说明：

1. 当前阶段 user 字段固定返回当前登录用户快照，不返回 null。
2. availableLoginMethods 只按当前对外配置返回：
   • SMS_AUTH_ENABLED=true 时包含 phone
   • WECHAT_AUTH_ENABLED=true 时包含 wechat
3. password 不进入 availableLoginMethods，保持和 Node 现状一致。

5. 错误语义

5.1 缺少或非法 Bearer token

1. 返回 401 UNAUTHORIZED

5.2 JWT 有效但用户不存在

1. 返回 401 UNAUTHORIZED
2. 语义视为“当前登录态已失效，需要重新登录”

说明：

1. 当前阶段不把这种情况返回为 404。
2. 这样可以与后续 token_version、会话吊销和用户禁用策略保持同一类恢复路径。

6. crate 边界

6.1 module-auth

负责：

1. 提供按 user_id 查询当前用户快照的能力。
2. 继续复用密码登录阶段已经建立的同一份进程内用户真相。

6.2 api-server

负责：

1. 复用现有 Bearer JWT 中间件拿到 sub。
2. 调用 module-auth 查询用户。
3. 组装 AuthMeResponse。

7. 测试策略

至少覆盖：

1. 已登录用户可通过 /api/auth/me 取回当前用户。
2. 当短信/微信开关开启时，availableLoginMethods 返回对应值。
3. JWT 有效但用户不存在时返回 401。

8. 后续衔接

这条任务完成后，下一步顺序固定为：

1. refresh token 轮换
2. 会话吊销
3. 手机验证码登录

微信登录继续按“暂缓执行”处理。