From f68b6d80d431c38aaa75e92cbdb72c98316b0057 Mon Sep 17 00:00:00 2001
From: lc <liuchang@1814.love>
Date: Thu, 3 Sep 2026 08:10:43 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#6979=20=E4=BE=9B=E5=BA=94?=
 =?UTF-8?q?=E5=95=86=E7=8A=B6=E6=80=81=E6=B5=81=E8=BD=AC=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...”商暂å�œçŠ¶æ€�与拉黑归档æµ�转-修改接å�£-管ç�†å�Žå�°.md | 511 ++++++++++++++++++
 1 file changed, 511 insertions(+)
 create mode 100644 changelogs-v2/2026-09/03_6979_统一供应商暂�状�与拉黑归档�转-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/03_6979_统一供应商暂�状�与拉黑归档�转-修改接�-管���.md b/changelogs-v2/2026-09/03_6979_统一供应商暂�状�与拉黑归档�转-修改接�-管���.md
new file mode 100644
index 00000000..d80bec36
--- /dev/null
+++ b/changelogs-v2/2026-09/03_6979_统一供应商暂�状�与拉黑归档�转-修改接�-管���.md
@@ -0,0 +1,511 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6979"
+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-03"
+status_note: "PR #7007 已�并 dev-v3 并部署 TEST；当�状�统一使用 SUSPENDED，新增���作和解除黑��接�，�端需按状�矩阵调整��。"
+updated_at: "2026-09-03"
+base: "dev-v3"
+---
+
+# 供应商模�：统一暂�状�与拉黑归档�转
+
+> **�务**: `hl-resource-service`（8082）
+> **Issue**: #6979
+> **PR**: #7007
+> **影�范围**: 管���供应商列表�详情与状��作��
+
+## ⚠� 关键�化
+
+- 当�供应商状���返回 `FROZEN`，暂��作统一为 `SUSPENDED`。
+- 新增“���作�和“解除黑���接�；拉黑��许从 `SUSPENDED` �起。
+- 归档��许从 `SUSPENDED` 或 `BLACKLIST` 进入门�；清账能力未交付时�返回 `395032`，�会归档。
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 分页查询供应商 | GET | `/admin/supplier/items/page` | �应枚举修改 | 当�状���返回 `FROZEN` |
+| 2 | 有界查询供应商 | GET | `/admin/supplier/items/list` | �应枚举修改 | 当�状���返回 `FROZEN` |
+| 3 | 查询供应商详情 | GET | `/admin/supplier/items/{supplierId}/basic-info/view` | �应枚举修改 | 暂�状�统一返回 `SUSPENDED` |
+| 4 | 暂��作 | POST | `/admin/supplier/items/{supplierId}/suspend` | 行为修改 | `ACTIVE → SUSPENDED` |
+| 5 | ���作 | POST | `/admin/supplier/items/{supplierId}/resume` | 新增接� | `SUSPENDED → ACTIVE` |
+| 6 | 拉入黑�� | POST | `/admin/supplier/items/{supplierId}/blacklist` | 行为修改 | 仅�许 `SUSPENDED → BLACKLIST` |
+| 7 | 解除黑�� | POST | `/admin/supplier/items/{supplierId}/unblacklist` | 新增接� | `BLACKLIST → SUSPENDED` |
+| 8 | 清账归档 | POST | `/admin/supplier/items/{supplierId}/archive` | 行为修改 | 仅 `SUSPENDED/BLACKLIST` �进入清账门� |
+
+## 三�接�详情
+
+### 1. 分页查询供应商 `GET /admin/supplier/items/page`
+
+**VO**: `SupplierPageReqVO / PageResult<SupplierListItemRespVO>`
+
+#### 使用场景
+
+供应商列表页分页查询，并���行 `status` 显示状���。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| page / pageSize | Query | Integer | � | 页� ≥ 1；�页 ≤ 100 | 分页�数 |
+| status | Query | String | � | 当�六状�之一 | 状�筛选 |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| records[].status | String | 当�状�；��返回 `FROZEN` |
+| records[].updateTime | LocalDateTime | 状�动作的�观�版本 |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/page?page=1&pageSize=20&status=SUSPENDED
+```
+
+#### �应示例
+
+```json
+{"code":200,"data":{"records":[{"supplierId":"2094672459314745346","status":"SUSPENDED","updateTime":"2026-09-03 08:03:00"}],"total":1,"page":1,"pageSize":20},"success":true}
+```
+
+#### 空数� / �级�应
+
+无匹�数�返回 `records: []`；本接�无业务�级分支。
+
+#### 错误�应
+
+```json
+{"code":401,"message":"缺少有效的 Authorization 头","data":null,"success":false}
+```
+
+#### 业务边界
+
+- `status=FROZEN` ��是�法筛选值；请改用 `SUSPENDED`。
+
+### 2. 有界查询供应商 `GET /admin/supplier/items/list`
+
+**VO**: `SupplierListReqVO / List<SupplierListItemRespVO>`
+
+#### 使用场景
+
+供应商选择器或短列表查询，并�� `status` 显示状���。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| status | Query | String | � | 当�六状�之一 | 状�筛选 |
+| limit | Query | Integer | � | 1～200，默认 50 | 最大返回数 |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data[].status | String | 当�状�；暂��作为 `SUSPENDED` |
+| data[].updateTime | LocalDateTime | 状�动作的�观�版本 |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/list?status=BLACKLIST&limit=50
+```
+
+#### �应示例
+
+```json
+{"code":200,"data":[{"supplierId":"2094672459314745346","status":"BLACKLIST","updateTime":"2026-09-03 08:04:00"}],"success":true}
+```
+
+#### 空数� / �级�应
+
+无匹�数�返回 `data: []`；本接�无业务�级分支。
+
+#### 错误�应
+
+```json
+{"code":400,"message":"供应商状���法","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 当�状��接� `DRAFT/VETTING/ACTIVE/SUSPENDED/BLACKLIST/ARCHIVED`。
+
+### 3. 查询供应商详情 `GET /admin/supplier/items/{supplierId}/basic-info/view`
+
+**VO**: `SupplierBasicInfoRespVO`
+
+#### 使用场景
+
+进入供应商详情或执行状�动作�，读�当�状�和最新并�版本。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数雪花 ID | 供应商 ID |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| status | String | 当�六状�之一 |
+| updateTime | LocalDateTime | �续状�动作原样回传 |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/2094672459314745346/basic-info/view
+```
+
+#### �应示例
+
+```json
+{"code":200,"data":{"supplierId":"2094672459314745346","status":"ACTIVE","updateTime":"2026-09-03 08:05:00"},"success":true}
+```
+
+#### 空数� / �级�应
+
+详情无空对象或�级结果；目标�存在时返回业务错误。
+
+#### 错误�应
+
+```json
+{"code":395001,"message":"供应商�存在","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 暂��作的当�主表状�统一返回 `SUSPENDED`，历�记录��能展示旧快照 `FROZEN`。
+
+### 4. 暂��作 `POST /admin/supplier/items/{supplierId}/suspend`
+
+**VO**: `SupplierStatusChangeReqVO / SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+在 `ACTIVE` 行点击“暂��作�。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数雪花 ID | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 审计原因 |
+| expectedUpdateTime | Body | LocalDateTime | 是 | `yyyy-MM-dd HH:mm:ss` | 最近读�的版本 |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| status | String | 固定为 `SUSPENDED` |
+| updateTime | LocalDateTime | 新并�版本 |
+
+#### 请求示例
+
+```json
+{"reason":"暂�业务�作","expectedUpdateTime":"2026-09-03 08:02:00"}
+```
+
+#### �应示例
+
+```json
+{"code":200,"data":{"supplierId":"2094672459314745346","status":"SUSPENDED","updateTime":"2026-09-03 08:03:00"},"success":true}
+```
+
+#### 空数� / �级�应
+
+写接�无空�功结果，也��供�级�功。
+
+#### 错误�应
+
+```json
+{"code":395005,"message":"当�状���许执行该�作","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 仅 `ACTIVE` �调用；�功�继续通知车务�用关�车队。
+
+### 5. ���作 `POST /admin/supplier/items/{supplierId}/resume`
+
+**VO**: `SupplierStatusChangeReqVO / SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+在 `SUSPENDED` 行点击“���作�。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数雪花 ID | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 审计原因 |
+| expectedUpdateTime | Body | LocalDateTime | 是 | `yyyy-MM-dd HH:mm:ss` | 最近读�的版本 |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| status | String | 固定为 `ACTIVE` |
+| updateTime | LocalDateTime | 新并�版本 |
+
+#### 请求示例
+
+```json
+{"reason":"��业务�作","expectedUpdateTime":"2026-09-03 08:03:00"}
+```
+
+#### �应示例
+
+```json
+{"code":200,"data":{"supplierId":"2094672459314745346","status":"ACTIVE","updateTime":"2026-09-03 08:04:00"},"success":true}
+```
+
+#### 空数� / �级�应
+
+写接�无空�功结果，也��供�级�功。
+
+#### 错误�应
+
+```json
+{"code":395014,"message":"数�已被他人修改，请刷新��试","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 仅 `SUSPENDED` �调用；��供应商�会自动�用车队。
+
+### 6. 拉入黑�� `POST /admin/supplier/items/{supplierId}/blacklist`
+
+**VO**: `SupplierStatusChangeReqVO / SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+在 `SUSPENDED` 行点击“拉入黑���。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数雪花 ID | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 审计原因 |
+| expectedUpdateTime | Body | LocalDateTime | 是 | `yyyy-MM-dd HH:mm:ss` | 最近读�的版本 |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| status | String | 固定为 `BLACKLIST` |
+| updateTime | LocalDateTime | 新并�版本 |
+
+#### 请求示例
+
+```json
+{"reason":"列入�作黑��","expectedUpdateTime":"2026-09-03 08:03:00"}
+```
+
+#### �应示例
+
+```json
+{"code":200,"data":{"supplierId":"2094672459314745346","status":"BLACKLIST","updateTime":"2026-09-03 08:04:00"},"success":true}
+```
+
+#### 空数� / �级�应
+
+写接�无空�功结果，也��供�级�功。
+
+#### 错误�应
+
+```json
+{"code":395005,"message":"当�状���许执行该�作","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 仅 `SUSPENDED` �调用；`ACTIVE` 直接拉黑返回 `395005`，�功�通知车务�用关�车队。
+
+### 7. 解除黑�� `POST /admin/supplier/items/{supplierId}/unblacklist`
+
+**VO**: `SupplierStatusChangeReqVO / SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+在 `BLACKLIST` 行点击“解除黑���。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数雪花 ID | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 审计原因 |
+| expectedUpdateTime | Body | LocalDateTime | 是 | `yyyy-MM-dd HH:mm:ss` | 最近读�的版本 |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| status | String | 固定为 `SUSPENDED` |
+| updateTime | LocalDateTime | 新并�版本 |
+
+#### 请求示例
+
+```json
+{"reason":"解除�作黑��","expectedUpdateTime":"2026-09-03 08:04:00"}
+```
+
+#### �应示例
+
+```json
+{"code":200,"data":{"supplierId":"2094672459314745346","status":"SUSPENDED","updateTime":"2026-09-03 08:05:00"},"success":true}
+```
+
+#### 空数� / �级�应
+
+写接�无空�功结果，也��供�级�功。
+
+#### 错误�应
+
+```json
+{"code":395005,"message":"当�状���许执行该�作","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 仅 `BLACKLIST` �调用；�功�回到 `SUSPENDED`，�会直接��交易或自动�用车队。
+
+### 8. 清账归档 `POST /admin/supplier/items/{supplierId}/archive`
+
+**VO**: `SupplierArchiveRespVO`
+
+#### 使用场景
+
+在 `SUSPENDED` 或 `BLACKLIST` 行点击“清账归档�。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数雪花 ID | 供应商 ID；无请求体 |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data | SupplierArchiveRespVO | 当�清账能力未交付，�会返回�功数� |
+
+#### 请求示例
+
+```http
+POST /admin/supplier/items/2094672459314745346/archive
+```
+
+#### �应示例
+
+```json
+{"code":395032,"message":"暂无法确认财务已清账，�能归档","data":null,"success":false}
+```
+
+#### 空数� / �级�应
+
+当�固定失败关闭，��供空数�或�级�功。
+
+#### 错误�应
+
+```json
+{"code":395005,"message":"当�状���许执行该�作","data":null,"success":false}
+```
+
+#### 业务边界
+
+- `ACTIVE` 先返回 `395005`；`SUSPENDED/BLACKLIST` 进入清账门��返回 `395032`，两者�零写入。
+
+## 四�契约约�与正确调用方�
+
+| 当�状� | 仅显示以下�作 | 正确接� |
+|---|---|---|
+| `ACTIVE` | 暂��作 | `/suspend` |
+| `SUSPENDED` | ���作�拉入黑���清账归档 | `/resume`�`/blacklist`�`/archive` |
+| `BLACKLIST` | 解除黑���清账归档 | `/unblacklist`�`/archive` |
+
+- `expectedUpdateTime` 必须使用最近一次详情或列表返回值；�功�使用�应的新版本刷新页�。
+- 统一�应�能由 HTTP 200 承载业务失败，必须�时判断 `code` 和 `success`。
+
+## 五�数�库行为
+
+- 当�主表中的旧 `FROZEN` 已转�为 `SUSPENDED`；历�审批与�更快照�改写。
+- 四个状�接��功时更新当�状�和版本，并�写一�既有�更审计；失败路径�写主体�审批或审计。
+
+## 六�边界行为
+
+- 未登录返回业务� `401`。
+- 生命周期写�作�求 `SUPER_ADMIN` 和 `supplier:status:manage`；�满足返回 `395004`。
+- `395005` 表示��状�错误；`395014` 表示版本过期；`395032` 表示清账能力��用；`100502` 表示 5 秒内���交。
+- 暂��拉黑继续通知车务�用关�车队；���解除黑���会自动�用车队。
+
+## 六.5�枚举 / 数�字典
+
+### `status`（供应商当�生命周期）
+
+| 值 | 中文 | ��语义 |
+|---|---|---|
+| `ACTIVE` | �作中 | 仅暂��作 |
+| `SUSPENDED` | 暂��作 | ���拉黑�清账归档 |
+| `BLACKLIST` | 黑�� | 解除黑���清账归档 |
+
+`DRAFT/VETTING/ARCHIVED` ��既有语义；当�接���产生或返回主表状� `FROZEN`。
+
+## 六.6�修改��对比
+
+| 场景 | 修改� | 修改� |
+|---|---|---|
+| 暂��作 | 当�状�进入 `FROZEN` | 当�状�进入 `SUSPENDED` |
+| ���作 | 无独立接� | 新增 `/resume` |
+| `ACTIVE` 直接拉黑 | �进入黑�� | 返回 `395005`，零写入 |
+| 解除黑�� | 无独立接� | 新增 `/unblacklist`，返回 `SUSPENDED` |
+| 归档�� | `ACTIVE/BLACKLIST` | `SUSPENDED/BLACKLIST` |
+
+## 六.7�影�评估
+
+- **是�破���兼容**: 是。�赖当�� `FROZEN` 或 `ACTIVE` 直接拉黑的调用方�必须调整。
+- **�端是�必须�步上线**: 是。
+- **�端 workaround 清�点**: 删除当�� `FROZEN` 的筛选�文案与按钮分支。
+
+## 七��影�范围
+
+- **仅影�**: 管���供应商当�状�展示与生命周期�作。
+- **零影�**: �稿建档�注册审批�收款账户�资�绑定��程�与历�审批/�更快照展示。
+
+## 八�测试环境已验�
+
+- `ACTIVE → SUSPENDED → BLACKLIST → SUSPENDED → ACTIVE` 全链路通过，列表与详情状�一致。
+- `ACTIVE` 直接拉黑/归档返回 `395005`；两��归档���返回 `395032` 且零写入。
+- �观�����交�未认�门�通过；四次�功动作写四��更审计，审批记录未增加。
+- 部署�交：[`8d38f69d2d6ebd99fb25fb6b0f5dc50ce4cfa1c0`](https://git.1814.love:8443/wx/HL/commit/8d38f69d2d6ebd99fb25fb6b0f5dc50ce4cfa1c0)。
+
+## ��相关文档
+
+- [Issue #6979](https://git.1814.love:8443/wx/HL/issues/6979)
+- [PR #7007](https://git.1814.love:8443/wx/HL/pulls/7007)
+
+## �端动作与当�状�
+
+- 移除当�� `FROZEN`，统一映射 `SUSPENDED` 为“暂��作�。
+- 按状�矩阵接入两个新增接�并收紧按钮显�；`395032` �得更新页�为已归档。
+- **当�状�：待�端接入。**
+
+## 关� / �系人
+
+- **Issue**: [#6979](https://git.1814.love:8443/wx/HL/issues/6979)
+- **PR**: [#7007](https://git.1814.love:8443/wx/HL/pulls/7007)
+- **�端负责人**: @lc