05-API接口契约

BasePath: /api/v1 端口: 9090

全局约定

响应格式

{"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>：

{
  "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 — 当前用户非超级管理员，无权调用