# 05-API接口契约

BasePath: `/api`
端口: `8080`（见 docs/07 § 二，可在 application.yml 覆盖）

## 全局约定

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

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

### 鉴权
除登录接口外，所有接口均需在请求头携带 `Authorization: Bearer <access_token>`。Token 由 REQ-USR-004 登录接口签发，有效期 24 小时。

### 分页参数
列表查询接口统一使用以下分页入参：`pageNum`（页码，从 1 起）、`pageSize`（每页条数，默认 20，最大 100）。响应体 `data` 字段格式：`{ list: [], total: N, pageNum: N, pageSize: N }`。

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

---

## module_usr 用户管理

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

- **Method**: POST
- **Path**: `/api/auth/login`
- **Auth**: 无（公开接口）
- **Permission**: —
- **请求**: `{ "username": "string", "password": "string", "brandNo": "string" }` — 用户名、密码（明文，HTTPS 传输）、公司编号（对应 brand.sNo）
- **响应**: `{ "accessToken": "string", "refreshToken": "string", "expiresIn": 86400, "userInfo": { "userId": "string", "username": "string", "userType": "string", "language": "string" } }`

#### 错误码
- `40100` — 用户名或密码错误（不区分哪个错，防信息泄露）
- `40101` — 账号已被禁用
- `40102` — 账号已被锁定，请 N 分钟后重试
- `40400` — 公司编号不存在

---

### REQ-USR-001 增加用户

- **Method**: POST
- **Path**: `/api/usr/users`
- **Auth**: Bearer Token
- **Permission**: `usr:create`
- **请求**: `{ "userCode": "string", "username": "string", "userType": "普通用户|超级管理员", "language": "中文|英文|繁体", "canEditDoc": false, "employeeId": "string|null", "permGroupIds": ["string"] }` — 初始密码由后端自动设为系统默认值（666666 哈希）
- **响应**: `{ "userId": "string", "userCode": "string", "username": "string" }`

#### 错误码
- `40001` — 参数校验失败（缺必填 / 格式错）
- `40300` — 权限不足
- `40901` — 用户名已存在
- `40902` — 用户号已存在

---

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

- **Method**: GET
- **Path**: `/api/usr/users`
- **Auth**: Bearer Token
- **Permission**: `usr:query`
- **请求**: Query 参数：`queryField=username|staffName|userCode|department|userType|disabled|lastLoginDate|creator`（默认 username）、`matchType=contains|notContains|equals`（默认 contains）、`queryValue=string`、`page=int`（默认 1）、`pageSize=int`（默认 20，最大 100）
- **响应**: `{ list: [{ "sId", "sUsername", "sUserCode", "sUserType", "sLanguage", "bIsDisabled", "tLastLoginDate", "sCreatorUsername", "tCreateDate", "sStaffName", "sDepartment" }], total, page, pageSize }` — sPasswordHash / iLoginFailCount / tLockUntil 不返回

#### 错误码
- `40001` — 参数校验失败
- `40300` — 权限不足

---

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

- **Method**: PUT
- **Path**: `/api/usr/users/{userId}`
- **Auth**: Bearer Token
- **Permission**: `usr:edit`
- **请求**: Path 参数 `userId`（usr_user.sId）；Body：`{ "userType": "普通用户|超级管理员", "language": "中文|英文|繁体", "canEditDoc": false, "isDisabled": false, "employeeId": "string|null", "permGroupIds": ["string"] }` — 用户名不可修改；密码由单独接口重置
- **响应**: `{ "userId": "string", "username": "string", "updatedAt": "datetime" }`

#### 错误码
- `40001` — 参数校验失败
- `40300` — 权限不足
- `40301` — 禁止修改自己的管理员角色
- `40400` — 用户不存在