122 lines
3.1 KiB
Markdown
122 lines
3.1 KiB
Markdown
# `/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 成功响应
|
||
|
||
```json
|
||
{
|
||
"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. 手机验证码登录
|
||
|
||
微信登录继续按“暂缓执行”处理。
|