hl-api-changelog/changelogs-v2/2026-08/26_6392_供应商暂停合作与拉黑原因必填接口-新增接口-管理后台.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	6392	供应商暂停合作与拉黑原因必填接口	admin	lc(GIT)	新增接口	deployed	verified	verified	mmg	49b071b0		2026-08-26	PR #6403 已合并 dev-v3；两个状态命令已部署 TEST，ACTIVE→SUSPENDED、ACTIVE/SUSPENDED→BLACKLIST、原因审计、权限、并发、幂等和失败零写入均经真实 Gateway 验证。前端待接入原因弹窗与并发版本。	2026-08-26	dev-v3

供应商暂停合作与拉黑原因必填接口

供应商管理新增两个窄状态命令：暂停合作与列入黑名单。服务端强制要求业务原因和调用方读取到的并发版本，并沿用可信管理员身份、专用平台权限、聚合锁、短窗幂等、行锁、状态机及同事务审计。

变更接口

方法	路径	允许来源状态	目标状态
POST	/admin/supplier/items/{supplierId}/suspend	ACTIVE	SUSPENDED
POST	/admin/supplier/items/{supplierId}/blacklist	ACTIVE、SUSPENDED	BLACKLIST

两个接口都要求真实 SUPER_ADMIN 身份且拥有 supplier:status:manage 平台权限。前端按钮可按角色和状态控制展示，但不能替代服务端门禁。

公共请求

{
  "reason": "供应商连续违约，暂停合作复核",
  "expectedUpdateTime": "2026-08-26 15:40:00"
}

字段	类型	必填	规则
reason	string	是	去除首尾空白后必须非空，最长 500 字符；规范化后的原因为状态审计内容
expectedUpdateTime	string	是	调用方最近一次读取到的供应商 updateTime，格式 yyyy-MM-dd HH:mm:ss

路径参数 supplierId 必须为正 Long。请求体不接受角色、操作者或目标状态，身份仅来自 Gateway 验证后的可信属性。

成功响应

暂停合作成功：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "1900000000000000001",
    "status": "SUSPENDED",
    "updateTime": "2026-08-26 15:40:01"
  }
}

拉黑成功时结构相同，status 为 BLACKLIST。supplierId 固定为 JSON string；后续状态命令必须使用响应或详情中的新 updateTime，不能继续提交旧版本。

每次成功迁移与一条 supplier_change_log 状态审计在同一本地事务内提交。审计记录包含 fromStatus、toStatus、操作者、角色、Trace ID 和规范化后的 reason；审计写入失败时状态整体回滚。

失败语义

场景	业务码	结果
未登录或 Token 无效	401	Gateway/服务认证拒绝，零业务写入
reason 缺失、空白、纯空格、超过 500 字符，或缺少版本	400	参数/服务双层拒绝，零业务写入
供应商不存在或已软删除	395001	零业务写入
非 SUPER_ADMIN 或缺少 supplier:status:manage	395004	专用状态权限失败关闭，零业务写入
suspend 来源不是 ACTIVE；blacklist 来源不是 ACTIVE/SUSPENDED	395005	状态机拒绝，零业务写入
expectedUpdateTime 与数据库秒级版本不一致	395014	状态和审计均不写入，调用方应刷新后重试
5 秒内同操作者、供应商和相同请求重复提交	100502	重复请求被拒绝，不产生第二条状态审计

统一响应可能以 HTTP 200 承载业务失败，客户端必须同时检查 code、success、message 和 data。

前端联调事项

• 在合作中供应商上提供“暂停合作”和“列入黑名单”；暂停合作供应商仅提供“列入黑名单”。其他状态不展示这两个动作。
• 点击动作后弹出必填原因输入框，前端限制 500 字符；提交详情或列表中最近一次读取到的 updateTime。
• 395014 应提示数据已变化并刷新详情；395005 应刷新当前状态；100502 应提示不要重复提交。
• 成功后使用响应中的 status 和 updateTime 更新页面或重新拉取详情/列表。
• 前端显示控制不构成授权；不得从请求体传入操作者、角色或目标状态。

验证证据

• 代码：PR #6403 合并提交为 3f3a0bf734737ca0e84ed1cfcad1801835cd46d5；供应商目标测试 62 项通过，Resource 全量 2100 项通过、0 失败、0 错误（38 项既有条件跳过），Gateway 路由/认证 9 项通过，hl-verify 全部通过。
• 部署：原规范任务 d08c52f6 成功，目标/实际提交均为 4b31612aeba5c0d3ac690cc6af15b66290bd8b48；只读恢复绑定原任务期样本，5 个可验证样本均健康、3 个本地不可验证样本、0 个故障样本，没有重复部署。
• 当前制品：后续同服务规范任务 da90f211 将 TEST 更新为 dev-v3@692547a5989ec1f8fa1b1495fc8dd501cddc0fe0，该提交包含本工单合并提交；6/6 个任务期样本均为双进程、Nacos 双 healthy/enabled 且端口匹配，0 不可验证、0 故障样本。本工单最终业务验收在该当前制品上完成。
• 真实 Gateway：验证 ACTIVE→SUSPENDED→BLACKLIST 和 ACTIVE→BLACKLIST，成功响应、详情状态、并发版本与同事务审计一致；原因首尾空白按规范化值入审计。
• 失败分支：未认证、真实 CUSTOMIZER 越权、原因缺失/空白/超长、缺版本、旧版本、DRAFT 来源、不存在对象、重复状态与短窗重复请求全部返回预期错误，主体版本、状态和审计计数均保持不变。
• 清理：仅创建 3 个随机 TEST 草稿，并以 ID、随机全名、当前状态三重条件设置 2 个 ACTIVE 夹具；未触碰既有供应商。验收后精确恢复 2 行为 DRAFT，再通过业务删除接口软删除全部 3 个夹具；有效供应商总量恢复为 4，HL6392- 活跃命名空间为 0。9 条脱敏审计按系统约定保留；两枚验收会话已注销，幂等键等待 6 秒自然过期，未手工修改 Redis。

撤回

1. 从最新 dev-v3 创建独立回退分支，执行 git revert -m 1 --no-edit 3f3a0bf734737ca0e84ed1cfcad1801835cd46d5，经评审 PR 合入；不要回退后续无关提交。
2. 通过 Deploy Panel API 对精确回退目标执行新鲜预检和显式部署 hl-resource-service，复核双实例、Nacos、日志以及既有供应商查询、建档、资料更新和审批链路。
3. 本次无 DDL、配置、Redis、MQ 或跨服务写入变更，不执行 schema、缓存或消息回退。
4. 已实际发生的 SUSPENDED、BLACKLIST 状态和审计不会随代码回退自动反转；禁止直接改库，只能由后续合法恢复合作/解除黑名单业务流程处理。
5. 回退后两个新增 POST 接口恢复不可用；前端在回退部署前隐藏/停用对应动作，并继续兼容既有供应商接口。

关联 / 联系人

• Issue: #6392
• PR: #6403
• 合并提交: 3f3a0bf73
• 后端负责人: @lc