From d58a2baca51b62ea0fbdc760dc68d95b2180e338 Mon Sep 17 00:00:00 2001
From: lc <liuchang@1814.love>
Date: Sun, 23 Aug 2026 13:57:49 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=8F=91=E5=B8=83=E4=BE=9B?=
 =?UTF-8?q?=E5=BA=94=E5=95=86=E5=BD=92=E6=A1=A3=E5=A4=B1=E8=B4=A5=E5=85=B3?=
 =?UTF-8?q?=E9=97=AD=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refs #6174
---
 ...归档无清账契约时失败关闭-修改接口-管理后台.md | 106 ++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 changelogs-v2/2026-08/23_6174_供应商归档无清账契约时失败关闭-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-08/23_6174_供应商归档无清账契约时失败关闭-修改接口-管理后台.md b/changelogs-v2/2026-08/23_6174_供应商归档无清账契约时失败关闭-修改接口-管理后台.md
new file mode 100644
index 00000000..8123bf6d
--- /dev/null
+++ b/changelogs-v2/2026-08/23_6174_供应商归档无清账契约时失败关闭-修改接口-管理后台.md
@@ -0,0 +1,106 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6174"
+title: "供应商归档在权威清账契约缺失时失败关闭"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #6203 已合并 dev-v3，提交 041fb6d492 已部署 TEST。真实 Token 经 Gateway 实测：SUPER_ADMIN 且拥有生命周期权限时稳定返回 395032；ADMIN 先返回 395004；匿名与伪造身份返回 401。失败路径未进入供应商数据库，未创建审批或变更记录。"
+updated_at: "2026-08-23"
+base: "dev-v3"
+---
+
+# 供应商归档：无权威清账契约时失败关闭
+
+供应商归档是不可逆生命周期操作。在 Finance 权威清账契约尚未交付时，现有接口不再创建本地审批或返回清账证据为空的假成功，而是在服务端权限校验后稳定失败关闭。
+
+## 修改接口
+
+| 方法 | 路径 | 请求体 | 权限 |
+|------|------|--------|------|
+| POST | `/admin/supplier/items/{supplierId}/archive` | 无 | 可信角色必须为 `SUPER_ADMIN`，且拥有 `supplier:status:manage` |
+
+请求路径、请求参数和响应包络均未改变；本次修改的是业务失败语义。
+
+## 行为变化
+
+| 场景 | 修改前 | 修改后 |
+|------|--------|--------|
+| 清账能力尚未提供，权限通过 | 仍可能创建审批并把供应商推进至 `ARCHIVED` | 返回 `395032`，不进入审批准备、Provider 或结果应用 |
+| ADMIN / FINANCE 请求归档 | 由既有生命周期角色门禁拒绝 | 保持不变，返回 `395004` |
+| 未认证或伪造 `X-Admin-*` | Gateway 拒绝 | 保持不变，返回 `401` |
+| 非法 `supplierId` | 参数绑定失败 | 保持不变，返回 `400` |
+
+## 代表性响应
+
+### SUPER_ADMIN 权限通过，但无法取得权威清账结果
+
+```json
+{
+  "code": 395032,
+  "message": "暂无法确认财务已清账，不能归档",
+  "data": null,
+  "success": false
+}
+```
+
+### ADMIN 或 FINANCE 请求归档
+
+```json
+{
+  "code": 395004,
+  "message": "无权执行该供应商状态操作",
+  "data": null,
+  "success": false
+}
+```
+
+统一响应可能以 HTTP 200 承载业务失败，调用方必须同时检查 `code` 和 `success`。
+
+## 边界与兼容性
+
+- 本次未新增错误码；`395032` 已在供应商错误码契约中冻结。
+- 未修改 DTO 字段、数据库 migration、Redis、MQ、Nacos、Gateway 路由或 User 权限数据。
+- 失败路径不调用审批 Provider、准备事务或结果应用器，不新增 `supplier_approval_log` / `supplier_change_log`，也不更新 `supplier_main`。
+- 正向清账查询、账本版本证据和归档成功能力由后续工单 #6173 承接。在该依赖交付前，客户端应把 `395032` 视为暂不可归档，不应重试为“已归档”。
+- 既有客户端已经按统一业务失败包络处理，无前端代码同步要求。
+
+## 验证证据
+
+- 最终部署提交：`041fb6d492cfe9552f443c592160dbd5dc5d6965`。
+- 自动化回归：Supplier 套件 `149/149` 通过且 0 跳过；Resource 全量 `1905` 项，0 失败、0 错误；独立审计定向 `17/17` 通过。
+- 真实登录经 Gateway 验收：
+  - 匿名和仅伪造身份头均返回 `401`；
+  - SUPER_ADMIN 连续两次请求均返回 `395032`；
+  - 切换 ADMIN 后先返回 `395004`；
+  - 非法 `supplierId` 返回 `400`。
+- TEST 的本地 `hl_resource_service` 当前未初始化 `supplier_*` 表，且 Flyway 明确关闭；本接口在任何供应商数据库访问前返回 `395032`，验证前后未创建表、未产生供应商业务写入。
+- 验收后已恢复原 `SUPER_ADMIN` 角色并注销访问令牌与刷新令牌，Redis Token 键无残留；正常登录和失败操作审计按合规要求保留。
+- Gateway、User、Resource 健康检查均为 200；Nacos 中 Resource 仅有 `127.0.0.1:8082` 健康实例。
+
+## 撤回
+
+1. 停止归档流量，revert 合并提交 `041fb6d492` 并重新构建、部署 `hl-resource-service`。
+2. 本次无数据库、配置、Redis 或 MQ 恢复项。
+3. 若 #6173 尚未交付，代码撤回会重新暴露“未清账即归档”风险，必须同时阻断本接口流量；只有在权威清账门禁及其成功/失败测试均已交付后才能恢复归档成功路径。
+4. 撤回后经 Gateway 验证归档不可达，供应商查询、更新、提交等其他接口保持正常。
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#6174](https://git.1814.love:8443/wx/HL/issues/6174)
+- **PR**: [#6203](https://git.1814.love:8443/wx/HL/pulls/6203)
+- **依赖 Issue**: [#6173](https://git.1814.love:8443/wx/HL/issues/6173)
+- **合并提交**: [041fb6d492](https://git.1814.love:8443/wx/HL/commit/041fb6d492cfe9552f443c592160dbd5dc5d6965)
+
+### 联系人
+
+- **后端负责人**: @lc