hl-api-changelog/changelogs-v2/2026-08/23_6174_供应商归档无清账契约时失败关闭-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	6174	供应商归档在权威清账契约缺失时失败关闭	admin	lc(GIT)	修改接口	deployed	verified	not_required					PR #6203 已合并 dev-v3，提交 041fb6d492 已部署 TEST。真实 Token 经 Gateway 实测：SUPER_ADMIN 且拥有生命周期权限时稳定返回 395032；ADMIN 先返回 395004；匿名与伪造身份返回 401。失败路径未进入供应商数据库，未创建审批或变更记录。	2026-08-23	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 权限通过，但无法取得权威清账结果

{
  "code": 395032,
  "message": "暂无法确认财务已清账，不能归档",
  "data": null,
  "success": false
}

ADMIN 或 FINANCE 请求归档

{
  "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
• PR: #6203
• 依赖 Issue: #6173
• 合并提交: 041fb6d492

联系人

• 后端负责人: @lc