docs(changelog): 供应商审批记录新增变更前后状态字段（#7587）

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DdmjgoN68L7TUP4oRosfTu
2026-09-12 16:50:43 +08:00
@@ -0,0 +1,66 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7587"
+title: "供应商详情审批记录补充变更前后状态"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-12"
+status_note: "PR #7588 已合并 dev-v3，合并提交 7b31f7628 由部署任务 7acf6380 精确发布到 TEST，并经真实 Gateway 身份对 40 个供应商的 166 条审批记录逐行验证。审批记录每行新增变更前后状态编码与中文文案，原有 13 个字段取值不变。"
+updated_at: "2026-09-12"
+base: "dev-v3"
+---
+
+# 供应商详情审批记录补充变更前后状态
+
+供应商详情「审批记录」列表每行新增本次审批的供应商状态变化，便于在表格中直接展示「暂停合作 → 黑名单」这类状态流转。不改变状态的审批返回占位符。
+
+## 变更接口
+
+| 方法 | 路径 | 行为变化 |
+|---|---|---|
+| GET | `/admin/supplier/items/{supplierId}/approval-history/page` | `records[]` 新增 `statusBefore`、`statusAfter`、`statusChangeText` |
+
+原有 `bizType`、`bizTypeName`、`applicantName`、`approvalStatus`、`approvalStatusName`、`action`、`actionName`、`chainLevel`、`chainLevelText`、`approverName`、`opinion`、`submittedAt`、`finishedAt` 共 13 个字段的字段名、JSON 类型与取值均不变。
+
+响应片段示例：
+
+```json
+{
+  "bizType": "STATUS_CHANGE",
+  "bizTypeName": "供应商状态变更审批",
+  "chainLevelText": "第1级通过",
+  "statusBefore": "SUSPENDED",
+  "statusAfter": "BLACKLIST",
+  "statusChangeText": "暂停合作 → 黑名单"
+}
+```
+
+## 字段语义
+
+- `statusChangeText`：可直接展示的中文文案，形如「暂停合作 → 黑名单」；本次审批不改变供应商状态，或历史记录信息不足以判定时固定返回占位符 `—`（与该接口 `opinion` 的空值占位一致）。该字段始终有值，不会为 `null`。
+- `statusBefore` / `statusAfter`：对应的生命周期状态编码，取值范围 `DRAFT` 草稿、`VETTING` 审核中、`ACTIVE` 合作中、`SUSPENDED` 暂停合作、`BLACKLIST` 黑名单、`ARCHIVED` 已归档。当 `statusChangeText` 为 `—` 时这两个字段为 `null`。
+- 各业务类型的取值规则：建档审批为「草稿 → 合作中」；状态变更审批按业务子类型给出「暂停合作 → 黑名单」「黑名单 → 暂停合作」「暂停合作 → 已归档」「黑名单 → 已归档」；资料变更审批不改变状态，返回 `—`。
+- 同一张审批单拆出的多个层级行（第 1 级、第 2 级……）三个字段取值相同。
+- 该列表达的是本次审批申请要把供应商改成什么状态，与审批是否通过无关；审批结果仍由既有 `approvalStatusName` 表达，已驳回的申请同样显示其申请的目标状态。
+
+## 管理端接入事项
+
+1. 审批记录表格新增一列展示状态变化，取 `statusChangeText` 直接渲染即可，无需前端拼接箭头或翻译编码。
+2. 需要按状态做筛选、着色或图标时使用 `statusBefore` / `statusAfter` 编码，不要解析中文文案。
+3. 该列在资料变更审批行会显示 `—`，属于正常业务结果，不是数据缺失。
+4. 暂停合作与恢复合作由后台直接改状态、不走审批，因此审批记录中不会出现这两类状态变化。
+
+## 兼容性与未变化范围
+
+- 本次是既有 GET 响应的向后兼容扩展，不新增接口、请求参数、业务错误码、Gateway 路由或权限点；分页、排序、筛选参数与语义不变。
+- 不修改任何数据库数据与表结构，不新增 migration，不回填历史数据。
+- 不改变审批链路、状态机、供应商变更记录接口（`/change-records/page`、`/approval-records/page`）与账户审批展示。
+- 不修改配置、Redis、MQ 或跨服务写契约。
+- 本工单只交付后端；管理端源码未在后端仓库修改，前端状态保持 `pending`，直至完成该列展示并提供验证提交。