认证模块接口文档（Sprint 1）
版本：v1.0 | 更新：2026-03-12 | 基于 spec v0.2.4
通用约定
Base URL
https://admin.clawzone.ai/api/v1
认证方式
Authorization: Bearer ACCESS_TOKEN
响应格式
成功时 code 为 0，data 包含业务数据。失败时 code 为错误码，message 为描述。
错误码
| code | 含义 | HTTP Status |
|---|---|---|
| 0 | 成功 | 200 |
| 10001 | 未登录或 Token 无效 | 401 |
| 10002 | Token 已过期 | 401 |
| 10003 | 会话已失效 | 401 |
| 10004 | 权限不足 | 403 |
| 10005 | 用户名或密码错误 | 200 |
| 10006 | 账号已禁用 | 200 |
| 10007 | 旧密码错误 / 密码强度不足 | 200 |
| 10008 | 参数校验失败 | 200 |
1. 登录
POST /api/v1/auth/login
认证： 不需要
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| username | string | ✅ | 用户名 |
| password | string | ✅ | 密码（明文） |
成功响应： code=0，data 包含 access_token（JWT，有效期 2 小时）
JWT Payload 包含： sid（session UUID）、role、sub（user_id）、exp、iat
失败： 10005（密码错误）/ 10006（账号禁用）/ 10008（参数缺失）
2. 获取当前用户信息
GET /api/v1/auth/me
认证： Bearer Token
成功响应字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| user_id | int | 用户 ID |
| username | string | 用户名 |
| nickname | string | 昵称 |
| role_type | string | 角色（superadmin/admin/user） |
| status | int | 1=正常，0=禁用 |
失败： 10001（未登录）/ 10002（过期）/ 10003（会话失效）
3. 登出
POST /api/v1/auth/logout
认证： Bearer Token
请求： 空 JSON 对象
成功响应： code=0，message="已登出"
登出后 Redis session 删除，token 立即失效。
4. 修改密码
PUT /api/v1/users/me/password
认证： Bearer Token
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| old_password | string | ✅ | 当前密码 |
| new_password | string | ✅ | 新密码（≥8位，含大小写+数字） |
成功响应： code=0，message="密码修改成功"
修改后 auth_version +1，所有其他 session 立即失效。
失败： 10005（旧密码错误）/ 10007（密码强度不足）
5. Permission Middleware
非接口，影响所有受保护路由：
- 链路：sys_user → sys_user_group → sys_group_permission → sys_permission
- Redis 缓存 key：perm:USER_ID（TTL 5min）
- auth_version 比对：不一致则踢出
- superadmin 跳过权限检查