feat: add auth me endpoint

2026-04-21 14:57:17 +08:00
parent c23088539e
commit 70dbefda2b
10 changed files with 360 additions and 2 deletions
--- a/docs/technical/AUTH_ME_QUERY_DESIGN_2026-04-21.md
+++ b/docs/technical/AUTH_ME_QUERY_DESIGN_2026-04-21.md
@@ -0,0 +1,121 @@
+# `/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. 手机验证码登录
+
+微信登录继续按“暂缓执行”处理。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -4,6 +4,7 @@

 ## 文档列表

+- [AUTH_ME_QUERY_DESIGN_2026-04-21.md](./AUTH_ME_QUERY_DESIGN_2026-04-21.md)：`/api/auth/me` 首版查询设计，冻结 Bearer JWT 衔接、`user + availableLoginMethods` 返回 contract，以及用户不存在时的 `401` 语义。
 - [PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md](./PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md)：密码登录与自动建号落地设计，冻结 `/api/auth/entry`、幂等兼容策略、模块边界以及与 JWT / refresh cookie 的衔接方式。
 - [PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md](./PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md)：`platform-auth` refresh cookie 适配设计，冻结 cookie 配置结构、读取规则与 `api-server` 最小读取链路。
 - [PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md](./PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md)：`platform-auth` 首版 JWT 适配设计，冻结 `JwtConfig`、claims 结构、`HS256` 签发/校验、`api-server` Bearer 中间件与内部验收路由边界。