重写

2026-04-21 19:17:31 +08:00
parent d234d27cc0
commit 89129ef1f4
83 changed files with 13329 additions and 176 deletions
--- a/docs/technical/PHONE_AUTH_AXUM_MINIMAL_FLOW_DESIGN_2026-04-21.md
+++ b/docs/technical/PHONE_AUTH_AXUM_MINIMAL_FLOW_DESIGN_2026-04-21.md
@@ -0,0 +1,152 @@
+# Axum 手机验证码登录最小闭环设计
+
+日期：`2026-04-21`
+
+## 1. 文档目的
+
+这份文档用于冻结 Rust `api-server + module-auth` 当前阶段手机号验证码登录的最小实现边界，避免在接入真实阿里云短信 adapter 前，把接口 contract、mock 行为和后续 SpacetimeDB 数据模型混在一起。
+
+## 2. 当前阶段范围
+
+本阶段只落以下内容：
+
+1. `POST /api/auth/phone/send-code`
+2. `POST /api/auth/phone/login`
+3. 进程内 mock 验证码存储与校验
+4. 登录成功后签发 access token 与 refresh cookie
+
+本阶段明确不包含：
+
+1. 真实阿里云短信发送
+2. 图形验证码
+3. 风控封禁
+4. 手机号换绑
+5. 微信补绑手机号
+
+## 3. 固定 mock 规则
+
+当前阶段统一使用以下 mock 约束：
+
+1. 固定验证码：`123456`
+2. 验证码 TTL：`5` 分钟
+3. 冷却秒数：`60`
+4. 手机号必须按中国大陆手机号规则校验
+
+## 4. 接口 contract
+
+### 4.1 `POST /api/auth/phone/send-code`
+
+请求体：
+
+```json
+{
+  "phone": "13800138000",
+  "scene": "login"
+}
+```
+
+当前允许的 `scene`：
+
+1. `login`
+2. `bind_phone`
+3. `change_phone`
+
+成功响应：
+
+```json
+{
+  "ok": true,
+  "cooldownSeconds": 60,
+  "expiresInSeconds": 300,
+  "providerRequestId": null
+}
+```
+
+### 4.2 `POST /api/auth/phone/login`
+
+请求体：
+
+```json
+{
+  "phone": "13800138000",
+  "code": "123456"
+}
+```
+
+成功响应：
+
+```json
+{
+  "token": "access-token",
+  "user": {
+    "id": "user_00000001",
+    "username": "phone_00000002",
+    "displayName": "138****8000",
+    "phoneNumberMasked": "138****8000",
+    "loginMethod": "phone",
+    "bindingStatus": "active",
+    "wechatBound": false
+  }
+}
+```
+
+同时必须写回 refresh cookie。
+
+## 5. 用户创建与复用规则
+
+1. 手机号首次登录时自动建号
+2. 同一手机号再次登录时复用同一系统用户
+3. access token 的 `provider` 固定为 `phone`
+4. 用户快照中的 `loginMethod` 固定为 `phone`
+
+## 6. 错误语义
+
+当前阶段统一约束为：
+
+1. 手机号格式错误：`400`
+2. 场景非法：`400`
+3. 验证码不存在、错误或过期：`400`
+4. 服务内部存储或签发失败：`500`
+
+## 7. crate 边界
+
+### 7.1 `module-auth`
+
+负责：
+
+1. 手机号规范化
+2. mock 验证码写入与校验
+3. 手机号用户创建与复用
+
+### 7.2 `api-server`
+
+负责：
+
+1. HTTP 请求解析
+2. 场景字符串映射
+3. 登录成功后创建会话、签发 JWT、写回 refresh cookie
+
+### 7.3 `platform-auth`
+
+负责：
+
+1. 签发 access token
+2. 生成 refresh cookie
+
+## 8. 测试要求
+
+至少覆盖：
+
+1. `send-code` 成功返回 mock 冷却与过期秒数
+2. 默认错误场景返回 `400`
+3. 首次手机号登录会自动建号并写 refresh cookie
+4. 同一手机号重复登录复用同一用户
+
+## 9. 完成定义
+
+满足以下条件时，本任务视为完成：
+
+1. Rust 侧已提供 `send-code` 与 `phone/login`
+2. mock 验证码链路可跑通
+3. 手机号登录成功后能拿到 access token 与 refresh cookie
+4. 文档、任务清单与测试已同步更新