认证与授权

登录/注册流程

系统使用手机号 + 短信验证码进行登录和注册（一体化流程）。

获取验证码

GET /api/v1/auth/verification-code?phone_number={11位手机号}&code_type={sms|voice}

参数	类型	必填	说明
phone_number	string	是	11 位中国大陆手机号
code_type	string	否	sms（默认）或 voice（语音验证码）

响应：204 No Content

错误：

• 429 — 发送过于频繁（默认 1 分钟冷却）
• 501 — 未配置短信服务

登录/注册

POST /api/v1/auth/token

{
  "phone": "13800138000",
  "verification_code": "123456",
  "source": "web"
}

字段	类型	必填	说明
phone	string	是	手机号
verification_code	string	是	短信验证码
source	string	是	来源标识（如 web、app）

响应：

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

错误：

• 400 — 验证码错误或已过期
• 403 — 账号被禁用或封禁
• 429 — 登录尝试次数过多

Token 使用

REST API

在请求头中携带 Bearer Token：

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

WebSocket

通过 URL 查询参数传递：

ws://host/api/v1/conversations/{conversation_id}/ws?token=eyJhbGci...

Token 结构

JWT Token 的 payload 包含以下字段（解码后）：

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "permission": {
    "is_admin": false
  },
  "iat": 1735686000,
  "exp": 1735689600
}

字段	说明
sub	用户 UUID
is_active	账户是否启用
permission.is_admin	是否为管理员
iat	签发时间（Unix 时间戳）
exp	过期时间（Unix 时间戳）

权限模型

系统使用三维度权限控制：资源:操作:作用域

• 资源：user、character、conversation、project、file 等
• 操作：create、read、update、delete
• 作用域：own（自有）、public（公开）、all（全部，仅管理员）

普通用户默认拥有对自有资源和公开资源的操作权限，管理员拥有通配符权限。

注意

• Token 过期后所有请求返回 401，需重新登录获取新 Token
• 账户被封禁后即使 Token 未过期也会返回 403
• WebSocket 连接建立后不会因 Token 过期而主动断开，但新消息处理会校验