docs(supplier): align frontend changelog with template

2026-08-23 17:14:43 +08:00
@@ -12,13 +12,28 @@ frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: ""
-status_note: "汇总 #6153、#6161-#6164、#6174、#6195、#6197、#6200、#6205 的当前管理端接口契约，新增前端联调版单文件 HTML；15 个接口已实现可联调，SUP-ADM-010 保持 395032 失败关闭。"
+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 设计/生成基线保留不改。

 ## 变更接口
@@ -42,12 +57,60 @@ base: "dev-v3"
 | 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`。
@@ -63,6 +126,18 @@ base: "dev-v3"
 - 自动化回归：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)