---
schema: "hl-changelog/v2"
ticket: "6392"
title: "供应商暂停合作与拉黑原因必填接口"
consumer: "admin"
author: "lc(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "49b071b0"
target_release: ""
verified_at: "2026-08-26"
status_note: "PR #6403 已合并 dev-v3；两个状态命令已部署 TEST，ACTIVE→SUSPENDED、ACTIVE/SUSPENDED→BLACKLIST、原因审计、权限、并发、幂等和失败零写入均经真实 Gateway 验证。前端待接入原因弹窗与并发版本。"
updated_at: "2026-08-26"
base: "dev-v3"
---

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

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

## 变更接口

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

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

## 公共请求

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

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

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

## 成功响应

暂停合作成功：

```json
{
  "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](https://git.1814.love:8443/wx/HL/issues/6392)
- **PR**: [#6403](https://git.1814.love:8443/wx/HL/pulls/6403)
- **合并提交**: [3f3a0bf73](https://git.1814.love:8443/wx/HL/commit/3f3a0bf734737ca0e84ed1cfcad1801835cd46d5)
- **后端负责人**: @lc