4054a1133b
Phase 0：research.md（10项技术决策，无需澄清项） Phase 1：data-model.md（11张表+Redis结构），contracts/（8个模块API契约），quickstart.md（Docker Compose启动+流水线验证） plan.md：宪章11条全部通过，项目结构确认
149 lines
2.9 KiB
Markdown
149 lines
2.9 KiB
Markdown
# API 契约：认证与用户管理
|
||
|
||
**统一响应格式**:
|
||
- 成功：`{"code": "SUCCESS", "data": {...}}`
|
||
- 成功（无数据）：`{"code": "SUCCESS", "data": null}`
|
||
- 失败：`{"code": "ERROR_CODE", "message": "描述"}`
|
||
- 分页成功：`{"code": "SUCCESS", "data": {"items": [...], "total": 100, "page": 1, "pageSize": 20}}`
|
||
|
||
---
|
||
|
||
## POST /api/auth/login
|
||
|
||
**权限**: 匿名
|
||
**描述**: 用户登录，返回会话凭证
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"companyCode": "COMPANY_A",
|
||
"username": "zhangsan",
|
||
"password": "plaintext_password"
|
||
}
|
||
```
|
||
|
||
**成功响应** `200`:
|
||
```json
|
||
{
|
||
"code": "SUCCESS",
|
||
"data": {
|
||
"token": "550e8400-e29b-41d4-a716-446655440000",
|
||
"userId": 1,
|
||
"username": "zhangsan",
|
||
"role": "ANNOTATOR",
|
||
"expiresIn": 7200
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应**:
|
||
- `401` `USER_NOT_FOUND`: 用户名或密码错误（不区分哪个错误，防止枚举）
|
||
- `403` `USER_DISABLED`: 账号已禁用
|
||
|
||
---
|
||
|
||
## POST /api/auth/logout
|
||
|
||
**权限**: 已登录（Bearer Token）
|
||
**描述**: 退出登录，立即删除 Redis 会话
|
||
|
||
**请求头**: `Authorization: Bearer {token}`
|
||
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
||
|
||
---
|
||
|
||
## GET /api/auth/me
|
||
|
||
**权限**: 已登录
|
||
**描述**: 获取当前用户信息
|
||
|
||
**响应** `200`:
|
||
```json
|
||
{
|
||
"code": "SUCCESS",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "zhangsan",
|
||
"realName": "张三",
|
||
"role": "ANNOTATOR",
|
||
"companyId": 10,
|
||
"companyName": "测试公司"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## GET /api/users
|
||
|
||
**权限**: ADMIN
|
||
**描述**: 分页查询本公司用户列表
|
||
|
||
**查询参数**: `page`（默认 1）、`pageSize`（默认 20，最大 100）、`role`（可选过滤）、`status`（可选过滤）
|
||
|
||
**响应** `200`:
|
||
```json
|
||
{
|
||
"code": "SUCCESS",
|
||
"data": {
|
||
"items": [
|
||
{"id": 1, "username": "zhangsan", "realName": "张三", "role": "ANNOTATOR", "status": "ACTIVE"}
|
||
],
|
||
"total": 50,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## POST /api/users
|
||
|
||
**权限**: ADMIN
|
||
**描述**: 创建用户
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "lisi",
|
||
"password": "initial_password",
|
||
"realName": "李四",
|
||
"role": "ANNOTATOR"
|
||
}
|
||
```
|
||
|
||
**响应** `201`: `{"code": "SUCCESS", "data": {"id": 2, "username": "lisi", ...}}`
|
||
**失败**: `409` `USERNAME_EXISTS`: 用户名已存在
|
||
|
||
---
|
||
|
||
## PUT /api/users/{id}
|
||
|
||
**权限**: ADMIN
|
||
**描述**: 更新用户基本信息
|
||
|
||
**请求体**: `{"realName": "新姓名"}`
|
||
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
||
|
||
---
|
||
|
||
## PUT /api/users/{id}/status
|
||
|
||
**权限**: ADMIN
|
||
**描述**: 启用或禁用账号，立即驱逐权限缓存
|
||
|
||
**请求体**: `{"status": "DISABLED"}`
|
||
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
||
|
||
---
|
||
|
||
## PUT /api/users/{id}/role
|
||
|
||
**权限**: ADMIN
|
||
**描述**: 变更用户角色，立即驱逐权限缓存
|
||
|
||
**请求体**: `{"role": "REVIEWER"}`
|
||
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
||
**失败**: `400` `INVALID_ROLE`: 角色值不合法
|