feat(plan): 生成 label_backend 完整实施规划文档
Phase 0:research.md(10项技术决策,无需澄清项) Phase 1:data-model.md(11张表+Redis结构),contracts/(8个模块API契约),quickstart.md(Docker Compose启动+流水线验证) plan.md:宪章11条全部通过,项目结构确认
This commit is contained in:
148
specs/001-label-backend-spec/contracts/auth.md
Normal file
148
specs/001-label-backend-spec/contracts/auth.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 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`: 角色值不合法
|
||||
Reference in New Issue
Block a user