Files

wh 4054a1133b 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条全部通过，项目结构确认

2026-04-09 12:27:16 +08:00

2.9 KiB

Raw Blame History

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

权限: 匿名
描述: 用户登录，返回会话凭证

请求体:

{
  "companyCode": "COMPANY_A",
  "username": "zhangsan",
  "password": "plaintext_password"
}

成功响应 200:

{
  "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:

{
  "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:

{
  "code": "SUCCESS",
  "data": {
    "items": [
      {"id": 1, "username": "zhangsan", "realName": "张三", "role": "ANNOTATOR", "status": "ACTIVE"}
    ],
    "total": 50,
    "page": 1,
    "pageSize": 20
  }
}

POST /api/users

权限: ADMIN
描述: 创建用户

请求体:

{
  "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: 角色值不合法

2.9 KiB Raw Blame History Unescape Escape