Appearance
认证与安全
后台管理接口使用 JWT 作为主要认证手段，辅以验证码与角色切换机制。以下接口均位于 /auth 路径下。
获取验证码
- Method：
GET - Path：
/auth/captcha - 说明：返回 SVG 图片。后端会将验证码存入 session (
req.session.code) 并通过响应头下发Set-Cookie。前端需在登录前调用此接口并保持 Cookie。
登录
- Method：
POST - Path：
/auth/login - 守卫：
LocalGuard
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
username | string | ✓ | 用户名（6~20 位）。 |
password | string | ✓ | 密码（6~20 位）。 |
captcha | string | ✓ | 验证码，忽略大小写。预览模式且 isQuick=true 时可省略。 |
isQuick | boolean | ✗ | 仅在 IS_PREVIEW=true 时启用，无需验证码快速登录。 |
响应
json
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}后端会在 Redis 中缓存 token，键名形如 user:access:token:<userId>。
常见错误：
10003：验证码未匹配或缺失。10002：用户名/密码错误。11003：当前用户无启用的角色。
刷新 Token
- Method：
GET - Path：
/auth/refresh/token - 守卫：
JwtGuard - 说明：使用仍在有效期内的旧 token 调用，返回新的
accessToken。
切换角色
- Method：
POST - Path：
/auth/current-role/switch/:roleCode - 守卫：
JwtGuard
Params
| 参数 | 说明 |
|---|---|
roleCode | 目标角色编码，例如 super_admin。 |
若用户未拥有该角色，会返回 ERR_11005。
登出
- Method：
POST - Path：
/auth/logout - 守卫：
JwtGuard - 说明：清除 Redis 中的 token 缓存，客户端需删除本地 token。
修改密码
- Method：
POST - Path：
/auth/password - 守卫：
JwtGuard+PreviewGuard（仅预览环境开放）
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
oldPassword | string | ✓ | 旧密码。 |
newPassword | string | ✓ | 新密码。 |
成功后会自动调用 logout 使 token 失效，需要重新登录。
注册（预览环境）
- Method：
POST - Path：
/auth/register - 守卫：
PreviewGuard - 说明：仅在
IS_PREVIEW=true时允许注册新账号，正式环境请通过数据库脚本或后台管理创建。