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 — 参数校验失败（缺用户名/密码/版本）