# 05-API接口契约

BasePath: `/api`
端口: 见 `config-vars.yaml` 的 `backend.http_port`（单一来源，不在此重复填）

## 全局约定

响应格式 / 异常 / 错误码 / 认证 / 分页等全局约定的 SSoT 在 `docs/04`（响应格式见 § 1.4、异常处理见 § 1.5、认证见 § 1.7、分页查询见 § 3.2），此处不重复。各端点专属的请求 / 响应 / 错误码见下方接口清单。

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

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

- **Method**: POST
- **Path**: `/api/usr/users`
- **Auth**: 需要（Bearer JWT，仅管理员/超级管理员可调用）
- **请求**: JSON body `{ sUserName(必填,3-20位字母数字下划线,全局唯一), sUserNo(可选), iEmployeeId(可选,关联职员), sUserType(必填,普通用户/超级管理员,默认普通用户), sLanguage(必填,中文/英文/繁体), iCanModifyBill(可选,0/1,默认0), permissionIds(可选,number[],权限组勾选), initialPassword(可选,默认 666666) }`。密码以 BCrypt 哈希入库。
- **响应**: `Result<{ id: number }>`，返回新建用户主键 id（`data.id`）。

#### 错误码
- `40001` — 参数校验失败（字段格式/必填项不满足）
- `40901` — 用户名已存在（sUserName 全局唯一冲突）
- `40301` — 无权限（非管理员调用）

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

- **Method**: PUT
- **Path**: `/api/usr/users/{id}`
- **Auth**: 需要（Bearer JWT，仅管理员/超级管理员可调用）
- **请求**: 路径参数 `id`（用户主键）；JSON body `{ sUserNo, iEmployeeId, sUserType, sLanguage, iCanModifyBill, iIsVoid, permissionIds }`（sUserName 作为唯一标识不可修改；密码不在本接口修改）。
- **响应**: `Result<{ id: number }>`，返回被修改用户的 id；持久化变更。

#### 错误码
- `40001` — 参数校验失败
- `40401` — 用户不存在（id 无对应记录）
- `40301` — 无权限（非管理员调用）

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

- **Method**: GET
- **Path**: `/api/usr/users`
- **Auth**: 需要（Bearer JWT）
- **请求**: query 参数 `{ queryField(可选,用户名/员工名/用户号/部门/用户类型/作废/登录日期/制单人), matchType(可选,包含/不包含/等于,默认包含), queryValue(可选), pageNum(默认1), pageSize(默认10,最大100) }`。空条件返回全量分页；密码字段不返回。
- **响应**: `Result<PageResult<UserVO>>`，`UserVO = { id, sUserName, 员工名, sUserNo, 部门, sUserType, sLanguage, iIsVoid, tLastLoginDate, sCreator, tCreateDate }`；`PageResult = { records, total, pageNum, pageSize }`。

#### 错误码
- `42201` — 分页参数非法（pageNum<1 或 pageSize 超上限）
- `40001` — 查询参数校验失败

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

- **Method**: POST
- **Path**: `/api/usr/login`
- **Auth**: 否（登录端点，放行）
- **请求**: JSON body `{ sUserName(必填), password(必填,提交明文经 HTTPS，服务端 BCrypt 比对), companyId(必填,登录"版本"下拉选中的 usr_company.id) }`。
- **响应**: `Result<{ token: string, user: { id, sUserName, sUserType, sLanguage } }>`，签发 JWT（有过期时间，无状态）；登录成功更新 `tLastLoginDate`。

#### 错误码
- `40101` — 认证失败（用户名或密码错误；不区分以防账号枚举）
- `40302` — 账号已禁用（iIsVoid=1，禁止登录）
- `40001` — 参数校验失败（缺用户名/密码/版本）