label_backend/specs/001-label-backend-spec/contracts/auth.md

# 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`: 角色值不合法