152 行
9.6 KiB
Markdown
152 行
9.6 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6195"
|
||
title: "供应商模块前端联调接口汇总"
|
||
consumer: "admin"
|
||
author: "lc(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "9e1aba14"
|
||
target_release: ""
|
||
verified_at: "2026-08-23"
|
||
status_note: "汇总 #6153、#6161-#6164、#6174、#6195、#6197、#6200、#6205 的当前管理端接口契约，新增前端联调版单文件 HTML；16 个接口已实现可联调，SUP-ADM-010 保持 395032 失败关闭。"
|
||
updated_at: "2026-08-23"
|
||
base: "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 前端联调版](../../api-docs/supplier/%E4%BE%9B%E5%BA%94%E5%95%86%E6%A8%A1%E5%9D%97%20API%20%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83-v2.1-%E5%89%8D%E7%AB%AF%E8%81%94%E8%B0%83%E7%89%88.html)。原始 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 供应商路由/JWT `8/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 前端联调版](../../api-docs/supplier/%E4%BE%9B%E5%BA%94%E5%95%86%E6%A8%A1%E5%9D%97%20API%20%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83-v2.1-%E5%89%8D%E7%AB%AF%E8%81%94%E8%B0%83%E7%89%88.html)
|
||
|
||
## 关联工单
|
||
|
||
- 主档与账户：[#6153](https://git.1814.love:8443/wx/HL/issues/6153)、[#6161](https://git.1814.love:8443/wx/HL/issues/6161)、[#6162](https://git.1814.love:8443/wx/HL/issues/6162)、[#6163](https://git.1814.love:8443/wx/HL/issues/6163)、[#6164](https://git.1814.love:8443/wx/HL/issues/6164)
|
||
- Gateway 与权限：[#6191](https://git.1814.love:8443/wx/HL/issues/6191)
|
||
- 归档失败关闭：[#6174](https://git.1814.love:8443/wx/HL/issues/6174)
|
||
- 资源关系：[#6195](https://git.1814.love:8443/wx/HL/issues/6195)、[#6197](https://git.1814.love:8443/wx/HL/issues/6197)、[#6200](https://git.1814.love:8443/wx/HL/issues/6200)
|
||
- 创建版本时间：[#6205](https://git.1814.love:8443/wx/HL/issues/6205)
|
||
|
||
## 撤回
|
||
|
||
本条目和联调文档为文档变更，撤回时删除本汇总文件并下架联调版 HTML 即可，不改后端数据库、配置、Redis 或 MQ。后端功能撤回按各工单已有撤回方案执行；已应用的 migration 和业务数据不得删除或回滚覆盖。
|