# `/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. 手机验证码登录

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