realizemultiagent/shared/specs/user-auth-spec.md

用户认证模块规格说明书

背景

用户使用产品前需要完成注册和登录，建立身份体系。

目标

• 3 分钟内完成注册并登录
• 安全的身份验证机制
• 支持多设备登录管理

功能列表

F1: 用户注册

• 手机号 + 短信验证码注册
• 图形验证码校验（防机器人）
• 设置登录密码（6位以上）

F2: 用户登录

• 手机号 + 密码登录
• 返回 JWT Token

F3: 修改密码

• 通过短信验证码验证身份后修改

F4: 多设备管理

• 查看已登录设备列表
• 强制下线指定设备
• 最多同时 3 个设备

接口设计

POST /api/auth/send-code

发送短信验证码

• 入参: { phone: string, captchaKey: string, captchaCode: string }
• 出参: { code: 0, message: "发送成功" }

POST /api/auth/register

注册

• 入参: { phone: string, code: string, password: string }
• 出参: { code: 0, token: string, user: {...} }

POST /api/auth/login

登录

• 入参: { phone: string, password: string }
• 出参: { code: 0, token: string, user: {...} }

POST /api/auth/change-password

修改密码

• 入参: { phone: string, code: string, newPassword: string }
• 出参: { code: 0, message: "修改成功" }

GET /api/auth/devices

获取登录设备列表

• 入参: Header: Authorization: Bearer {token}
• 出参: { code: 0, devices: [...] }

DELETE /api/auth/devices/:id

下线指定设备

• 入参: Header: Authorization: Bearer {token}
• 出参: { code: 0, message: "已下线" }

数据模型

User

{
  id: string,           // UUID
  phone: string,        // 手机号（唯一）
  passwordHash: string, // 密码哈希
  createdAt: Date,
  updatedAt: Date
}

Device

{
  id: string,
  userId: string,
  deviceName: string,   // 如 "iPhone 14"
  deviceToken: string,  // 极光/FCM Token（用于推送）
  lastActiveAt: Date,
  createdAt: Date
}

验收标准

ID	标准	测试方式
V1	同一手机号不能重复注册	注册两次
V2	验证码 5 分钟内有效	等待 6 分钟再验证
V3	密码 6 位以下注册被拒绝	测试 5 位密码
V4	Token 过期后无法访问需要认证的接口	手动修改 Token
V5	第 4 个设备登录时最早的设备被自动踢出	登录 4 个设备