hl-api-changelog/changelogs-v2/2026-09/03_7013_供应商清账归档启用-修改接口-管理后台.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	7013	供应商清账归档启用	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	f3134941		2026-09-03	归档接口已可成功归档；前端需移除旧 395032 禁用提示并接入归档请求。	2026-09-03	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

请求示例

POST /admin/supplier/items/2094672459314745346/archive

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "supplierId": "2094672459314745346",
    "status": "ARCHIVED",
    "clearanceRequestId": null,
    "checkedAt": null,
    "ledgerRevision": null,
    "updateTime": "2026-09-03 10:20:00"
  },
  "success": true
}

空数据 / 降级响应

写接口无空成功结果，也不提供降级成功。

错误响应

{
  "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
• PR #7017
• 本条覆盖 #6979 旧归档约定 中“固定返回 395032”的说明。

前端动作与当前状态

• 移除归档菜单的固定禁用状态和旧清账提示。
• 对 SUSPENDED/BLACKLIST 接入归档请求；成功后刷新为 ARCHIVED。
• 当前状态：待前端处理。

关联 / 联系人

• Issue: #7013
• PR: #7017
• 后端负责人: @lc