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

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

请求体：

{
  "phone": "13800138000",
  "scene": "login"
}

当前允许的 scene：

1. login
2. bind_phone
3. change_phone

成功响应：

{
  "ok": true,
  "cooldownSeconds": 60,
  "expiresInSeconds": 300,
  "providerRequestId": null
}

4.2 POST /api/auth/phone/login

请求体：

{
  "phone": "13800138000",
  "code": "123456"
}

成功响应：

{
  "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. 文档、任务清单与测试已同步更新