# 05-API接口契约

BasePath: `/api/v1`
端口: `9090`

## 全局约定

### 响应格式
```json
{"code": 200, "message": "操作成功", "data": {}, "timestamp": 1700000000000}
```

### 错误码
| 范围 | 含义 |
|---|---|
| 200 | 成功 |
| 400xx | 客户端参数错误 |
| 401xx | 认证/授权错误 |
| 403xx | 权限不足 |
| 404xx | 资源不存在 |
| 500xx | 服务端内部错误 |

### 鉴权

除 `POST /api/v1/auth/login` 和 `GET /api/v1/companies`（登录页"版本"下拉）之外的全部接口需在请求头携带 `Authorization: Bearer <accessToken>`。Token 由 `/auth/login` 签发，TTL 2 小时，HS256 签名（密钥 `JWT_SECRET` 来自 `.env.local`）。鉴权失败统一返回 `40101 token 无效或已过期` / `40102 用户已被作废或锁定`。详见 docs/04 § 1.6。

### 分页参数

请求入参：

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | 否 | 1 | 页码，从 1 开始 |
| `size` | int | 否 | 20 | 每页条数，上限 100 |
| `sortField` | string | 否 | — | 排序字段，白名单内 |
| `sortOrder` | string | 否 | `desc` | `asc` / `desc` |

响应 `data` 结构 `PageResult<T>`：

```json
{
  "records": [],
  "total": 0,
  "page": 1,
  "size": 20
}
```

## 接口清单
（各模块接口段落见下方，由 `downstream-gen` 按 REQ 填入）

## module_usr 用户管理

### REQ-USR-001 用户登录

- **Method**: POST
- **Path**: `/api/v1/auth/login`
- **Auth**: 无需（公开接口）
- **请求**: JSON body `LoginReq { username: string (3-20), password: string (8-20, 明文，HTTPS 传输), companyCode: string (sys_company.sCompanyCode) }`
- **响应**: JSON `LoginVo { accessToken: string (JWT), tokenType: "Bearer", expiresInSec: 7200, userInfo: { userId: int, username: string, userType: "NORMAL"|"SUPER_ADMIN", language: string, employeeName?: string, companyCode: string } }`

#### 错误码
- `40001` — 用户名或密码格式错误
- `40101` — 用户名或密码错误（统一文案，不区分两者）
- `40103` — 账号已被作废，禁止登录
- `42301` — 账号已锁定，请稍后再试（HTTP 423；锁定剩余时间见 `data.lockUntil`）
- `40004` — 公司不存在或已删除

### REQ-USR-002 新增用户

- **Method**: POST
- **Path**: `/api/v1/users`
- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
- **请求**: JSON body `CreateUserReq { username: string (3-20，正则 ^[A-Za-z0-9_]{3,20}$), userCode: string (max 50), userType: "NORMAL"|"SUPER_ADMIN", language: "zh-CN"|"en-US"|"zh-TW", canEditDocument: boolean, employeeId?: int, permissionCategoryIds?: int[] }`。**初始密码由系统统一设为 `"666666"`（BCrypt 哈希后入库），请求体不接受 `password` 字段（出现即返 40001）。**
- **响应**: JSON `CreateUserVo { userId: int, username: string, userCode: string }`（HTTP 201）

#### 错误码
- `40001` — 必填字段缺失或格式错误（含携带未知字段如 `password`）
- `40004` — 指定的员工 / 权限分类不存在
- `40101` — 未携带或无效 Token
- `40301` — 当前用户非超级管理员，无权调用
- `40901` — 用户名已存在
- `40902` — 用户号已存在

### REQ-USR-003 GET 用户详情

- **Method**: GET
- **Path**: `/api/v1/users/{userId}`
- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
- **请求**: Path `userId: int`
- **响应**: JSON `UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds: int[], updatedBy, updatedDate }`

#### 错误码
- `40101` — 未携带或无效 Token
- `40301` — 当前用户非超级管理员，无权调用
- `40401` — 用户不存在

### REQ-USR-003 修改用户

- **Method**: PUT
- **Path**: `/api/v1/users/{userId}`
- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
- **请求**: Path `userId: int`；JSON body `UpdateUserReq { userCode?: string, userType?: "NORMAL"|"SUPER_ADMIN", language?: "zh-CN"|"en-US"|"zh-TW", canEditDocument?: boolean, employeeId?: int|null, isDeleted?: boolean, permissionCategoryIds?: int[] }`（username 与 password 字段不接受）
- **响应**: JSON `UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds, updatedBy, updatedDate }`

#### 错误码
- `40001` — 字段格式错误或试图修改 username / password
- `40004` — 指定的员工 / 权限分类不存在
- `40101` — 未携带或无效 Token
- `40301` — 当前用户非超级管理员，无权调用
- `40302` — 试图停用当前登录用户自己
- `40401` — 用户不存在
- `40902` — 用户号已被占用

### REQ-USR-004 查询用户

- **Method**: GET
- **Path**: `/api/v1/users`
- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
- **请求**: Query 参数 `page=1&size=20&sortField=tCreateDate&sortOrder=desc&queryField=username&matchMode=contains&queryValue=张&userType=NORMAL&isDeleted=false`
  - `queryField`: 枚举 `username|employeeName|userCode|departmentName|userType|isDeleted|lastLoginDate|createdBy`
  - `matchMode`: 枚举 `contains|notContains|equals`，缺省 `contains`
  - `queryValue`: 字符串，空字符串表示不限
- **响应**: `PageResult<UserListItemVo>`，`UserListItemVo { userId, username, employeeName, userCode, departmentName, userType, language, isDeleted, lastLoginDate, createdBy, createdDate }`（密码字段不返回）

#### 错误码
- `40001` — 分页参数越界或类型错误（page<1 / size 越界 / sortOrder 非 asc-desc / userType 非枚举 / lastLoginDate 入参非法日期 / isDeleted 入参非布尔）
- `40003` — `sortField` / `queryField` / `matchMode` 不在白名单
- `40101` — 未携带或无效 Token
- `40301` — 当前用户非超级管理员，无权调用