调用约定与文档发现

适用基线：测试环境目标 / dev 分支 / 2026-07-15。 阅读对象：测试、实施、运维（主）；集成开发（顺带）。配合API 参考概述使用。

业务目的与适用范围

调不通时，先分清是协议/认证问题，还是业务校验或权限问题。本页给出管理端 API 的调用约定，以及在环境中发现完整字段定义的方式。

读完本页，应能：知道优先打开 Knife4j；区分登录会话、功能权限与数据范围；按步骤把一条新接口取证回业务页，而不是在本站抄全量 OpenAPI。

如何使用本页

你的目的	建议阅读
找在线文档入口	「协议与报文」→ Knife4j/Swagger
登录后调不通	「认证与会话」+ RBAC 链接
看返回码/失败类型	「通用结果与错误」
怕重复提交 / 要重试	「幂等、重试与审计」+ 数据交换
补一条新接口到文档	「如何取证一条新接口」

协议与报文

项	当前口径
风格	管理端以 REST 风格 JSON 接口为主。
数据格式	请求/响应体一般为 JSON。
传输	生产环境应使用 HTTPS（部署细节见基础设施部署说明，环境以实测为准）。
在线文档	各业务服务普遍集成 springdoc + Knife4j，Swagger UI 路径常见为 /swagger-ui.html（具体主机与网关前缀以环境为准）。

完整入参/出参、枚举与示例，优先在对应环境的 Knife4j 中按 Tag/Controller 查阅，再回写到业务页或本索引的抽样表。

认证与会话

能力	业务含义	线索
登录与会话	账号登录后获得可调用管理 API 的凭证（Token 类会话）。	租户与认证分组；具体登录报文以环境/Swagger 为准。
权限信息	登录后可拉取角色、菜单树与权限标识集合。	已证实：GET /system/auth/get-permission-info。
租户边界	多租户下请求落在当前租户数据与套餐能力内。	租户与认证。
功能权限	后端接口常按权限标识校验；前端按钮显隐不等于后端已放行。	RBAC；GAP-014。
数据范围	部门/本人等数据权限与岗位库位等是不同机制。	数据权限。

未在本页写死 Header 名称与网关前缀的唯一真值——以当前环境网关与前端封装为准；变更时更新证据页。

通用结果与错误

项	口径
业务成功/失败	统一包装结果对象（成功标志、错误码、提示文案、数据载荷）在多数模块沿用；具体字段名以 Swagger 模型为准。
校验失败	参数校验与业务校验通常返回可展示提示，不直接当 HTTP 仅 500 处理。
权限失败	未登录/无权限与业务失败区分处理；联查 RBAC 与菜单权限标识。
集成失败	外部调用应能在「接口调用信息」中按业务单号联查，并可走异步失败重试（见数据交换页）。

幂等、重试与审计

场景	建议
页面重复提交	业务侧常有状态机约束；集成方应自备幂等键或先查后写。
异步交换	失败可人工/自动重试；重试前核业务单状态，避免双写。
审计	操作日志、访问日志、登录日志分层；见日志页。

已证实的完工上报等场景存在事务 UUID 类幂等线索（见 MES 完工证据）；不能推广为全站统一幂等头。

如何取证一条新接口

1. 在 Knife4j 定位 Tag → 方法 → 路径。
2. 对照菜单权限标识与后端权限注解是否一致（不一致记 GAP-014 类问题）。
3. 若涉及外部系统：查接口调用信息是否落业务单号。
4. 业务影响回写到对应模块页；技术细节进 project-docs 证据。

写实示例：约定核验

给定： 已登录租户 A，调用某 WMS 写接口返回无权限。 期望排查： 先确认 Token/租户上下文有效 → 查角色是否含对应权限标识 → 再看业务校验文案。前端按钮可见不能当作后端已放行。

建议验证点

• 能打开目标服务 Knife4j，并按 Tag 找到与业务动作对应的方法。
• get-permission-info（或等价权限接口）在登录后可返回权限集合。
• 无权限账号调用受保护接口时，失败类型可与业务失败区分。
• 涉及外部回写时，能在接口调用信息中按业务单号联查（见数据交换页）。

当前限制

• 网关统一前缀、Token Header 名、租户 Header 名待环境抓包固化到证据页。
• 不要假设所有模块共享同一 OpenAPI 聚合入口；可能按服务分别打开文档。
• SCP 可能在独立部署单元，文档入口与主站 MOM 服务分开（以环境为准）。