9.6 KiB
schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
| schema | ticket | title | consumer | author | change_type | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 6195 | 供应商模块前端联调接口汇总 | admin | lc(GIT) | 修改接口 | deployed | verified | verified | mmg | 9e1aba14 | 2026-08-23 | 汇总 #6153、#6161-#6164、#6174、#6195、#6197、#6200、#6205 的当前管理端接口契约，新增前端联调版单文件 HTML；16 个接口已实现可联调，SUP-ADM-010 保持 395032 失败关闭。 | 2026-08-23 | dev-v3 |
供应商模块前端联调接口汇总
存放目录: 二期 v3 →
changelogs-v2/2026-08/服务:hl-resource-service（8082） PR: 供应商模块各实现工单对应合并请求 Issue: #6195（汇总 #6153、#6161–#6164、#6174、#6197、#6200、#6205） 日期: 2026-08-23 影响范围: 管理后台供应商档案、账户和资源关联页面
⚠️ 关键变化
本条目将已交付的供应商接口统一整理为前端联调契约；共 16 个接口。归档接口 SUP-ADM-010 仅完成权限门禁和失败关闭，清账提供方未接入时固定返回 395032，不可按成功归档流程处理。
一、背景
本条目汇总已 TEST 验收并关闭的供应商工单，统一接口路径、权限、字典和失败语义，避免前端继续使用旧版设计稿或静态枚举。
本条目为前端联调索引，不替代接口卡片中的完整请求、响应、字段和错误码说明。完整契约见：供应商模块 API 接口规范 v2.1 前端联调版。原始 v2.0 设计/生成基线保留不改。
变更接口
| 编号 | 方法 | 路径 | 权限 | 前端状态 |
|---|---|---|---|---|
| SUP-ADM-001 | GET | /admin/supplier/items/page |
supplier:list |
已实现 · 可联调 |
| SUP-ADM-043 | GET | /admin/supplier/items/list |
supplier:list |
已实现 · 可联调 |
| SUP-ADM-002 | GET | /admin/supplier/items/{supplierId}/basic-info/view |
supplier:view |
已实现 · 可联调 |
| SUP-ADM-003 | POST | /admin/supplier/items/add |
supplier:create |
已实现 · 可联调 |
| SUP-ADM-004 | PUT | /admin/supplier/items/{supplierId}/update |
supplier:update |
已实现 · 可联调 |
| SUP-ADM-007 | POST | /admin/supplier/items/{supplierId}/submit |
supplier:update + supplier:approval:submit |
已实现 · 可联调 |
| SUP-ADM-010 | POST | /admin/supplier/items/{supplierId}/archive |
supplier:status:manage |
已实现 · 失败关闭 |
| SUP-ADM-011 | DELETE | /admin/supplier/items/{supplierId}/del |
supplier:delete |
已实现 · 可联调 |
| SUP-ADM-012 | GET | /admin/supplier/items/{supplierId}/approval-records/page |
supplier:approval:read |
已实现 · 可联调 |
| SUP-ADM-034 | GET | /admin/supplier/items/{supplierId}/account-info/list |
supplier:view |
已实现 · 可联调 |
| SUP-ADM-035 | POST | /admin/supplier/items/{supplierId}/bank-accounts/add |
supplier:account:manage + supplier:approval:submit |
已实现 · 可联调 |
| SUP-ADM-036 | GET | /admin/supplier/bank-accounts/{accountId}/view |
supplier:view；证明附件另需 supplier:account:proof:read |
已实现 · 可联调 |
| SUP-ADM-041 | PUT | /admin/supplier/bank-accounts/{accountId}/default/update |
supplier:account:manage |
已实现 · 可联调 |
| SUP-ADM-048 | GET | /admin/supplier/resource-relations/{resourceModule}/{resourceId}/view |
supplier:view |
已实现 · 可联调 |
| SUP-ADM-049 | PUT | /admin/supplier/resource-relations/{resourceModule}/{resourceId}/update |
supplier:update |
已实现 · 可联调 |
| SUP-ADM-050 | POST | /admin/supplier/resource-relations/{resourceModule}/{resourceId}/unbind |
supplier:update |
已实现 · 可联调 |
三、接口详情
完整字段级请求、响应、错误码和接口约束见联调版 HTML；本表为入口索引，避免与 HTML 维护两份字段定义。
四、契约约束与正确调用方式
- 所有管理端请求必须经 Gateway 并携带真实管理员认证；不得伪造
X-Admin-Id。 - 字典接口返回的
dictValue才是业务提交值；不得提交中文标签或dictDataId。 - 更新、提交、资源改绑和解绑必须携带服务端返回的并发时间字段。
qualType、contactRole当前为自由文本，不按未确认字典拦截。
五、数据库行为
本条目不新增或修改数据库结构；供应商接口按既有事务、软删除、审计和敏感字段脱敏规则执行。
六、边界行为
- 未认证或无权限：由 Gateway/服务端拒绝，不产生业务写入。
- 业务失败可能使用 HTTP 200，必须同时判断
code、success和data。 SUP-ADM-010返回395032时不进入审批、状态迁移或审计写入。
六.5、枚举 / 数据字典
供应商类型（平台字典 supplier_type）
所属字段: typeCode / types[].typeCode | 类型: String
运行时启用项、标签和排序以 GET /admin/dict/data/supplier_type 返回为准。
供应商生命周期（平台字典 supplier_lifecycle_status）
所属字段: status | 类型: String
运行时启用项、标签和排序以 GET /admin/dict/data/supplier_lifecycle_status 返回为准；字典项不是全部可跳转状态。
六.7、影响评估
- 是否破坏向后兼容: 否
- 前端是否必须同步上线: 是，需按本联调契约接入
- 前端 workaround 清理点: 清理页面内硬编码的供应商类型和生命周期中文文案
七、不影响范围
- 仅影响: 管理后台供应商模块
- 零影响: 小程序接口、订单服务、Fleet 业务数据、Finance 清账能力
统一接入约束
- 所有
/admin/supplier/**请求必须经 Gateway，认证级别为MANDATORY；客户端不得使用自报X-Admin-Id或角色替代有效登录态。 - 服务端按可信管理员身份校验平台权限；隐藏菜单或按钮不构成授权。
- Snowflake ID 按 JSON 字符串传输；
LocalDateTime使用yyyy-MM-dd HH:mm:ss。 - 供应商类型和生命周期状态从平台字典读取，业务请求只提交
dictValue，前端不应写死中文标签。 - 本次字典范围仅确认
supplier_type与supplier_lifecycle_status；两者的运行时启用项、标签和排序以/admin/dict/data/{dictType}返回为准，文档中的编码表只是契约基线，不是环境现状。 qualType、contactRole暂不接入平台字典，保持自由文本；前端不得按未确认候选值做字典校验或自行新增下拉选项。- 账号、税号、电话和证照号只返回脱敏值。
proofFileUrls可能因权限缺失而整个字段不返回。 - 更新、提交、资源改绑和解绑必须原样携带响应中的并发时间字段；收到
395014或并发错误时重新查询后再操作。 - 统一响应可能以 HTTP 200 承载业务失败，必须同时判断
code、success和data。
归档限制
SUP-ADM-010 当前只完成权限门禁和失败关闭：权限通过后返回 395032 SUPPLIER_CLEARANCE_CHECK_UNAVAILABLE，不进入审批、状态迁移或审计写入。本期没有 Finance 清账提供方，因此前端不应按成功归档流程重试或伪造成功状态。
TEST 验收证据
- 目标提交：
03685ac24520dea5917c708cda76942dee89c2e2，已部署隔离 TEST。 - 真实管理员经 Gateway 完成 105 项 E2E 断言，覆盖认证、角色权限、参数校验、失败零写入、创建/提交、账户批量管理、默认账户、资源关系、版本并发、敏感字段和归档失败关闭。
- 自动化回归：Supplier 聚焦测试
150/150，Resource 全量1906项零失败（38 项既有条件跳过），Gateway 供应商路由/JWT8/8，#6205 定向5/5。 - 测试使用独立一次性 schema；测试数据、临时账号、Token 和临时服务已清理，原环境已恢复。
八、测试环境已验证
真实管理员经 Gateway 完成 105 项 E2E 断言；Supplier 聚焦测试 150/150、Resource 全量 1906 零失败、Gateway 供应商路由/JWT 8/8、#6205 定向 5/5。
九、相关历史 PR
本条目关联工单均已合并、部署、TEST 验收并关闭；具体工单链接见下方关联工单清单。
十、相关文档
- 联调版接口文档：供应商模块 API 接口规范 v2.1 前端联调版
关联工单
- 主档与账户：#6153、#6161、#6162、#6163、#6164
- Gateway 与权限：#6191
- 归档失败关闭：#6174
- 资源关系：#6195、#6197、#6200
- 创建版本时间：#6205
撤回
本条目和联调文档为文档变更，撤回时删除本汇总文件并下架联调版 HTML 即可，不改后端数据库、配置、Redis 或 MQ。后端功能撤回按各工单已有撤回方案执行；已应用的 migration 和业务数据不得删除或回滚覆盖。