朱子纯 / test2

05-API接口契约.md 6.05 KB

05-API接口契约

BasePath: /api 端口: 8080

全局约定

响应格式

{"code": 200, "message": "操作成功", "data": {}, "timestamp": 1700000000000}

错误码

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

鉴权

除登录接口（POST /api/auth/login）外，所有接口要求 Authorization: Bearer <accessToken> 请求头。token 由 POST /api/auth/login 签发，HS256，有效期 2 小时；过期返回 40101，前端需用 refreshToken 换新或重新登录。

分页参数

  • 入参（query）：pageNum（≥1，默认 1）、pageSize（1~100，默认 20）、keyword（可选模糊查询）、sort（可选，形如 field,asc|desc）。
  • 出参（data）：{ "total": 0, "list": [], "pageNum": 1, "pageSize": 20 }。

接口清单

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

module_mod 模块管理

REQ-MOD-001 模块新增

  • Method: POST
  • Path: /api/modules
  • Auth: 需要
  • Permission: MOD:CREATE
  • 请求: JSON body：sDisplayType（必填，枚举：手机端 / 前端业务 / 系统配置 / 接口）、sProcedureName（必填，唯一）、sModuleType（必填）、sManageDeptEn（必填）、bShowPermission（可选，默认 false）、sModuleNameZh（必填）、iParentId（可选）、iSortOrder（可选，默认 0）
  • 响应: data.iIncrement 新模块主键 + 完整模块对象（VO）

错误码

  • 40010 — 参数缺失或格式错误
  • 40911 — sProcedureName 已存在（唯一性冲突）
  • 40411 — iParentId 指向的父模块不存在或已删除

REQ-MOD-002 模块修改

  • Method: PUT
  • Path: /api/modules/{id}
  • Auth: 需要
  • Permission: MOD:UPDATE
  • 请求: 路径参数 id = iIncrement；JSON body 同新增（sProcedureName 不可改），未提供字段保持原值
  • 响应: data = 更新后的模块 VO

错误码

  • 40010 — 参数缺失或格式错误
  • 40421 — 模块不存在或已删除
  • 40921 — 同级名称冲突或不能将自身/后代设为父模块
  • 40911 — sProcedureName 冲突（如尝试修改）

REQ-MOD-003 模块删除

  • Method: DELETE
  • Path: /api/modules/{id}
  • Auth: 需要
  • Permission: MOD:DELETE
  • 请求: 路径参数 id = iIncrement
  • 响应: data = { "iIncrement": <id>, "bDeleted": 1 }（软删除标记）

错误码

  • 40421 — 模块不存在或已被删除
  • 40912 — 存在子模块或外部业务引用，禁止删除（响应附 data.references）

REQ-MOD-004 模块查询

  • Method: GET
  • Path: /api/modules
  • Auth: 需要
  • Permission: MOD:READ
  • 请求: query 参数 keyword（可选，对 sModuleNameZh 模糊匹配）；返回完整树而非分页
  • 响应: data = 模块树数组，节点结构：{ iIncrement, sModuleNameZh, sDisplayType, sManageDeptEn, iParentId, iSortOrder, children: [] }

错误码

  • 40010 — keyword 长度超限

module_usr 用户管理

REQ-USR-001 用户新增

  • Method: POST
  • Path: /api/users
  • Auth: 需要
  • Permission: USR:CREATE
  • 请求: JSON body：sUserNo（必填）、sUserName（必填）、iStaffId（可选）、sUserType（必填）、sLanguage（必填）、bCanModifyDocs（可选，默认 false）、permissionCategoryIds（数组，对应 REQ-USR-001 表 2 选中行写入 tUserPermission）；密码不在请求中传，后端使用初始密码 666666 经 BCrypt 哈希后落库
  • 响应: data.iIncrement 新用户主键 + 用户 VO（不含密码哈希）

错误码

  • 40020 — 参数缺失或格式错误
  • 40921 — sUserName 或 sUserNo 唯一性冲突
  • 40421 — iStaffId 不存在或已软删除
  • 40422 — permissionCategoryIds 含不存在的权限分类

REQ-USR-002 用户修改

  • Method: PUT
  • Path: /api/users/{id}
  • Auth: 需要
  • Permission: USR:UPDATE
  • 请求: 路径参数 id = iIncrement；JSON body 同新增（sUserNo 不可改）；permissionCategoryIds 重新覆盖当前权限关联（先删后插）
  • 响应: data = 更新后的用户 VO

错误码

  • 40020 — 参数缺失或格式错误
  • 40431 — 用户不存在或已软删除
  • 40931 — sUserName 唯一性冲突
  • 40331 — 当前操作员无权变更目标角色

REQ-USR-003 用户查询

  • Method: GET
  • Path: /api/users
  • Auth: 需要
  • Permission: USR:READ
  • 请求: query 参数：pageNum / pageSize（标准分页）、queryField（枚举：username / staffname / userno / department / usertype / deleted / lastLoginDate / createdBy）、matchType（contains / notContains / equals）、queryValue（可空）
  • 响应: data = PageResult<UserListVO>，VO 字段：iIncrement、sUserName、sStaffName（join tStaff）、sUserNo、sDepartment（join tStaff）、sUserType、sLanguage、bDeleted、tLastLoginDate、sCreatedBy、tCreateDate

错误码

  • 40020 — queryField / matchType 非枚举值
  • 40021 — pageSize 超出 1~100

REQ-USR-004 用户登录

  • Method: POST
  • Path: /api/auth/login
  • Auth: 不需要
  • Permission: 无
  • 请求: JSON body：sUserName（必填）、sPassword（必填，明文，HTTPS 传输）、sVersion（必填，枚举：standard）
  • 响应: data = { "accessToken": "...", "refreshToken": "...", "expiresIn": 7200, "user": { "iIncrement", "sUserNo", "sUserName", "sUserType", "sLanguage" } }；登录成功同时回写 tUser.tLastLoginDate

错误码

  • 40101 — 用户名或密码错误（统一提示，不区分原因）
  • 40102 — 账号已禁用 / 已软删除
  • 40301 — 账号被临时锁定（响应附 data.cooldownSeconds 剩余秒数）
  • 40020 — 参数缺失或格式错误