---
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