docs(changelog): #7013 启用供应商清账归档

2026-09-03 10:42:52 +08:00
@@ -0,0 +1,175 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7013"
+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: "归档接口已可成功归档；前端需移除旧 395032 禁用提示并接入归档请求。"
+updated_at: "2026-09-03"
+base: "dev-v3"
+---
+
+# 供应商模块：清账归档启用
+
+> **服务**: `hl-resource-service`（8082）
+> **Issue**: #7013
+> **PR**: #7017
+> **影响范围**: 管理后台供应商列表与详情的“归档”操作
+
+## ⚠️ 关键变化
+
+此前“归档固定返回 `395032`、前端保持禁用”的约定已失效。符合条件的供应商现在可调用归档接口，成功后状态变为 `ARCHIVED`。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 归档供应商 | POST | `/admin/supplier/items/{supplierId}/archive` | 行为修改 | `SUSPENDED/BLACKLIST → ARCHIVED` |
+
+## 三、接口详情
+
+### 1. 归档供应商 `POST /admin/supplier/items/{supplierId}/archive`
+
+**VO**: `SupplierArchiveRespVO`
+
+#### 使用场景
+
+在供应商列表或详情中归档当前状态为 `SUSPENDED` 或 `BLACKLIST` 的供应商。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数雪花 ID | 无请求体 |
+
+#### 出参 `Result<SupplierArchiveRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| supplierId | String | 已归档供应商 ID |
+| status | String | 固定为 `ARCHIVED` |
+| clearanceRequestId | String / null | 当前固定为 `null` |
+| checkedAt | String / null | 当前固定为 `null` |
+| ledgerRevision | String / null | 当前固定为 `null` |
+| updateTime | String | 归档后的并发版本，格式 `yyyy-MM-dd HH:mm:ss` |
+
+#### 请求示例
+
+```http
+POST /admin/supplier/items/2094672459314745346/archive
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "supplierId": "2094672459314745346",
+    "status": "ARCHIVED",
+    "clearanceRequestId": null,
+    "checkedAt": null,
+    "ledgerRevision": null,
+    "updateTime": "2026-09-03 10:20:00"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+写接口无空成功结果，也不提供降级成功。
+
+#### 错误响应
+
+```json
+{
+  "code": 395005,
+  "message": "当前状态不允许执行该操作",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+| code | 场景 | 前端处理 |
+|---|---|---|
+| `401` | 未登录 | 进入既有登录失效流程 |
+| `395004` | 无归档权限 | 不展示或禁止操作 |
+| `395005` | 当前状态不是 `SUSPENDED/BLACKLIST`，或已归档后重复请求 | 刷新列表或详情状态 |
+| `100502` | 短时间重复提交 | 保持当前页面并提示勿重复操作 |
+
+- `395032` 仅为历史兼容错误码，当前归档入口不再主动返回。
+
+## 四、契约约束与正确调用方式
+
+- 当前状态为 `SUSPENDED` 或 `BLACKLIST` 且用户具备归档权限时，显示可点击的“归档”。
+- 点击后调用 `POST /admin/supplier/items/{supplierId}/archive`，不传请求体。
+- 必须同时判断 `success` 与 `code`；成功后使用响应中的 `ARCHIVED` 和 `updateTime` 刷新列表或详情。
+
+## 五、数据库行为
+
+归档成功会写入审核记录与状态变更审计，并在同一事务中把供应商主表状态更新为 `ARCHIVED`。
+
+## 六、边界行为
+
+- 仅 `SUSPENDED` 和 `BLACKLIST` 可归档；其他状态返回 `395005`。
+- 归档成功后供应商只允许查看，前端不得继续显示写操作。
+- 接口路径、请求方式和响应字段均未改变。
+
+## 六.5、枚举 / 数据字典
+
+| 值 | 中文 | 菜单语义 |
+|---|---|---|
+| `SUSPENDED` | 暂停合作 | 可归档 |
+| `BLACKLIST` | 黑名单 | 可归档 |
+| `ARCHIVED` | 已归档 | 仅查看，不再显示归档操作 |
+
+## 六.6、修改前后对比
+
+| 场景 | 修改前 | 修改后 |
+|---|---|---|
+| 合法来源状态归档 | 固定返回 `395032`，前端禁用 | 返回成功结果，状态更新为 `ARCHIVED` |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否；接口路径和响应字段未变，仅启用成功行为。
+- **前端是否必须同步上线**: 是。
+- **前端 workaround 清理点**: 删除“归档（暂无法确认财务已清账）”禁用项及 `395032` 固定失败判断。
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台供应商归档操作。
+- **零影响**: 其他供应商状态操作、收款账户、合同、资源绑定及小程序接口。
+
+## 八、测试环境已验证
+
+TEST Gateway 已验证合法来源状态归档返回 `ARCHIVED`，审核记录与主表状态同步更新。
+
+## 十、相关文档
+
+- [Issue #7013](https://git.1814.love:8443/wx/HL/issues/7013)
+- [PR #7017](https://git.1814.love:8443/wx/HL/pulls/7017)
+- 本条覆盖 [#6979 旧归档约定](https://git.1814.love:8443/wx/hl-api-changelog/src/branch/main/changelogs-v2/2026-09/03_6979_%E7%BB%9F%E4%B8%80%E4%BE%9B%E5%BA%94%E5%95%86%E6%9A%82%E5%81%9C%E7%8A%B6%E6%80%81%E4%B8%8E%E6%8B%89%E9%BB%91%E5%BD%92%E6%A1%A3%E6%B5%81%E8%BD%AC-%E4%BF%AE%E6%94%B9%E6%8E%A5%E5%8F%A3-%E7%AE%A1%E7%90%86%E5%90%8E%E5%8F%B0.md) 中“固定返回 `395032`”的说明。
+
+## 前端动作与当前状态
+
+- 移除归档菜单的固定禁用状态和旧清账提示。
+- 对 `SUSPENDED/BLACKLIST` 接入归档请求；成功后刷新为 `ARCHIVED`。
+- **当前状态：待前端处理。**
+
+## 关联 / 联系人
+
+- **Issue**: [#7013](https://git.1814.love:8443/wx/HL/issues/7013)
+- **PR**: [#7017](https://git.1814.love:8443/wx/HL/pulls/7017)
+- **后端负责人**: @lc