---
schema: "hl-changelog/v2"
ticket: "7078"
title: "供应商企微审核中冻结资料修改"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "f4d3e1c9"
target_release: ""
verified_at: "2026-09-04"
status_note: '后端已部署并通过 TEST；前端需在 statusName="审核中" 时制灰供应商、账户、合同及冲突状态写操作。'
updated_at: "2026-09-04"
base: "dev-v3"
---

# 供应商模块：企微审核中冻结资料修改

> **服务**: `hl-resource-service`
> **Issue**: [#7078](https://git.1814.love:8443/wx/HL/issues/7078)
> **PR**: [#7086](https://git.1814.love:8443/wx/HL/pulls/7086)
> **日期**: 2026-09-04
> **影响范围**: 管理后台供应商详情、账户、合同和状态操作

## ⚠️ 关键变化

`statusName="审核中"` 时，前端统一制灰供应商资料、账户、合同及冲突状态写入口；详情和审批记录仍可查看，注册审批撤销等合法审批退出路径保持可用。`statusName` 是 #7069 已交付字段，本次未新增请求字段、响应字段或错误码。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 更新供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 行为修改 | 企微主体审批中返回 `395005` |
| 2 | 新增合同 | POST | `/admin/supplier/items/{supplierId}/contracts/add` | 行为修改 | 企微主体审批中返回 `395005` |
| 3 | 更新合同 | PUT | `/admin/supplier/items/{supplierId}/contracts/{contractId}/update` | 行为修改 | 企微主体审批中返回 `395005` |
| 4 | 删除合同 | DELETE | `/admin/supplier/items/{supplierId}/contracts/{contractId}/del` | 行为修改 | 企微主体审批中返回 `395005` |
| 5 | 恢复合作 | POST | `/admin/supplier/items/{supplierId}/resume` | 行为修改 | 状态审批中不得绕过审批恢复合作 |

## 三、接口详情

### 1. 更新供应商 `PUT /admin/supplier/items/{supplierId}/update`

**VO**: `SupplierUpdateReqVO → SupplierWriteRespVO`

#### 使用场景

修改供应商主体、类型、联系人、资质、评价或其他档案资料。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 当前供应商版本 |
| `changeReason` | Body | String | 条件必填 | 最长 500 | 非草稿修改必填 |
| 资料字段 | Body | 原类型 | 否 | 沿用原契约 | 至少提交一个可变更字段 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | `SupplierWriteRespVO` | 成功响应结构不变 |

#### 请求示例

```json
{"remark":"更新备注","changeReason":"资料修正","expectedUpdateTime":"2026-09-04 10:00:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"2095000000000000001","status":"ACTIVE","updateTime":"2026-09-04 10:01:00"},"success":true}
```

#### 空数据 / 降级响应

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

#### 错误响应

```json
{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
```

#### 业务边界

- 企微注册或主体状态审批为 `PENDING` 时拒绝，供应商主档及聚合子项均保持不变。
- 其他权限、字段校验、并发和审计规则不变。

### 2. 新增合同 `POST /admin/supplier/items/{supplierId}/contracts/add`

**VO**: `SupplierContractCreateReqVO → SupplierContractRespVO`

#### 使用场景

为供应商独立登记一份线下合同。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
| `changeReason` | Body | String | 是 | 最长 500 | 登记原因 |
| 合同资料字段 | Body | 原类型 | 否 | 沿用原契约 | 名称、编号、日期、金额等字段不变 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | `SupplierContractRespVO` | 成功响应结构不变 |

#### 请求示例

```json
{"contractName":"年度框架合同","changeReason":"线下签署后登记"}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"contractId":"2095000000000000002","contractName":"年度框架合同","updateTime":"2026-09-04 10:02:00"},"success":true}
```

#### 空数据 / 降级响应

除 `changeReason` 外的合同业务字段可空；成功仍返回合同对象，不提供降级成功。

#### 错误响应

```json
{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
```

#### 业务边界

- 企微注册或主体状态审批为 `PENDING` 时不新增合同或审计记录。
- 合同字段、权限、锁和幂等规则不变。

### 3. 更新合同 `PUT /admin/supplier/items/{supplierId}/contracts/{contractId}/update`

**VO**: `SupplierContractUpdateReqVO → SupplierContractRespVO`

#### 使用场景

完整替换一份已有合同的业务资料。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` / `contractId` | Path | String | 是 | 正整数 | 供应商和合同 ID |
| `changeReason` | Body | String | 是 | 最长 500 | 修改原因 |
| `expectedUpdateTime` | Body | String | 否 | `yyyy-MM-dd HH:mm:ss` | 合同并发版本 |
| 合同资料字段 | Body | 原类型 | 否 | 沿用原契约 | 完整替换语义不变 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | `SupplierContractRespVO` | 成功响应结构不变 |

#### 请求示例

```json
{"contractName":"年度框架合同（修订）","changeReason":"合同修订","expectedUpdateTime":"2026-09-04 10:02:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"contractId":"2095000000000000002","contractName":"年度框架合同（修订）","updateTime":"2026-09-04 10:03:00"},"success":true}
```

#### 空数据 / 降级响应

合同业务字段保持既有可空和完整替换语义；写接口不提供降级成功。

#### 错误响应

```json
{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
```

#### 业务边界

- 企微注册或主体状态审批为 `PENDING` 时，先于合同查询拒绝，不修改合同或审计记录。
- 合同归属、可选版本及无变化校验不变。

### 4. 删除合同 `DELETE /admin/supplier/items/{supplierId}/contracts/{contractId}/del`

**VO**: `SupplierContractDeleteReqVO → Void`

#### 使用场景

软删除一份已有合同。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` / `contractId` | Path | String | 是 | 正整数 | 供应商和合同 ID |
| `changeReason` | Body | String | 是 | 最长 500 | 删除原因 |
| `expectedUpdateTime` | Body | String | 否 | `yyyy-MM-dd HH:mm:ss` | 合同并发版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | null | 成功时为空 |

#### 请求示例

```json
{"changeReason":"合同登记作废","expectedUpdateTime":"2026-09-04 10:03:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":null,"success":true}
```

#### 空数据 / 降级响应

成功时 `data=null`；请求体不能省略，也不提供降级成功。

#### 错误响应

```json
{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
```

#### 业务边界

- 企微注册或主体状态审批为 `PENDING` 时，先于合同查询拒绝，不删除合同或新增审计记录。
- 合同归属、可选版本、软删除及幂等规则不变。

### 5. 恢复合作 `POST /admin/supplier/items/{supplierId}/resume`

**VO**: `SupplierStatusChangeReqVO → SupplierStatusChangeRespVO`

#### 使用场景

将没有在途主体审批的暂停合作供应商恢复合作。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
| `reason` | Body | String | 是 | 1～500 字符 | 恢复原因 |
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 当前供应商版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.status` / `data.statusName` | String | 成功后为 `ACTIVE` / “合作中” |
| `data.updateTime` | String | 新并发版本 |

#### 请求示例

```json
{"reason":"恢复合作","expectedUpdateTime":"2026-09-04 10:00:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"2095000000000000003","status":"ACTIVE","statusName":"合作中","updateTime":"2026-09-04 10:04:00"},"success":true}
```

#### 空数据 / 降级响应

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

#### 错误响应

```json
{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
```

#### 业务边界

- 暂停合作供应商已有企微主体状态审批时不得恢复合作，来源状态保持不变。
- 原有权限、来源状态、并发、审计和幂等规则不变。

## 四、契约约束与正确调用方式

- 后端以企微注册或主体状态审批 `PENDING` 为权威门禁；页面即使状态滞后，写请求仍可能返回 `395005`。
- 前端展示和制灰统一读取列表或详情的 `statusName`；`status` 继续用于筛选和生命周期判断。
- 账户新增和设默认接口的后端契约未变：注册审批中的 `VETTING`、状态审批来源的 `SUSPENDED` / `BLACKLIST` 均不满足账户写入所需的 `ACTIVE` 状态，仍返回既有 `395010`。
- 详情、账户详情、审批记录和变更记录等读取入口保持可用；注册审批撤销 `POST /admin/supplier/items/{supplierId}/approval/revoke` 保持可用。

## 五、数据库行为

- 本次没有数据库结构、初始化数据或迁移变化。
- 审核中被拒绝的请求不修改供应商、账户、合同、状态或审计数据。

## 六、边界行为

- 五类展示场景：注册、列入黑名单、解除黑名单、“终止且账清”和“拉黑且账清”在企微审核中均返回 `statusName="审核中"`。
- 审批结束后刷新列表或详情，再按最终生命周期状态恢复原有可用操作。
- 请求参数、成功响应、认证、权限、配置、Redis 和 MQ 契约均未改变。

## 六.6、修改前后对比

| 行为 | 修改前 | 修改后 |
|---|---|---|
| 企微主体审批中修改供应商资料 | 部分入口可能继续写入 | 返回 `395005`，业务数据不变 |
| 企微主体审批中新增、更新或删除合同 | 部分入口可能继续写入 | 返回 `395005`，业务数据不变 |
| 状态审批中恢复合作 | 可能绕过审批候选来源状态 | 返回 `395005`，来源状态不变 |
| 账户写入 | 既有规则要求供应商为 `ACTIVE` | 规则不变；前端在“审核中”时提前制灰 |
| 详情与合法审批退出 | 可用 | 保持可用 |

## 六.7、影响评估

- **是否破坏向后兼容**: 是；审批中的资料和合同写请求由可能成功调整为业务拒绝。
- **前端是否必须同步上线**: 是。
- **前端 workaround 清理点**: 不再仅按 `status` 放开写按钮，增加 `statusName="审核中"` 的统一制灰条件。

## 七、不影响范围

- **仅影响**: 企微注册或主体状态审批中的供应商资料、账户、合同和冲突状态操作。
- **零影响**: 详情及审批记录读取、注册审批撤销、企微回调与轮询、审批结束后的原有业务规则。
- **无变化**: 请求/响应字段、错误码定义、数据库、配置、Redis、MQ；后端仓库未修改前端代码。

## 八、测试环境已验证

部署提交：`6462397526ad61acfbcf503486d8507c9c1c7293`。

```text
GET  /admin/supplier/items/list?limit=200                                      → 200；注册审批返回 VETTING / 审核中 ✓
GET  /admin/supplier/items/{supplierId}/basic-info/view                        → 200；详情同为 VETTING / 审核中 ✓
PUT  /admin/supplier/items/{supplierId}/update                                 → 395005 ✓
POST /admin/supplier/items/{supplierId}/contracts/add                          → 395005 ✓
PUT  /admin/supplier/items/{supplierId}/contracts/{contractId}/update           → 395005 ✓
DELETE /admin/supplier/items/{supplierId}/contracts/{contractId}/del            → 395005 ✓
POST /admin/supplier/items/{supplierId}/bank-accounts/add                       → 395010 ✓
```

上述拒绝请求前后，供应商版本、账户、合同、审批和审计的只读数据库快照哈希一致。TEST 当前没有四类状态审批的在途样本，因此没有发起企微审批造数；对应子类型、来源状态、“审核中”投影及全部写入口由合并提交中的精确自动化测试覆盖。

## 十、相关文档

- [Issue #7078](https://git.1814.love:8443/wx/HL/issues/7078)
- [PR #7086](https://git.1814.love:8443/wx/HL/pulls/7086)
- [前置展示契约 #7069](https://git.1814.love:8443/wx/HL/issues/7069)

## 前端动作与当前状态

- `statusName="审核中"` 时，统一制灰供应商资料编辑/保存、账户新增/设默认、合同新增/编辑/删除，以及暂停、恢复、拉黑、解除拉黑和归档等冲突写入口。
- 保留详情、审批记录、审批进度刷新和合法审批退出。
- **当前状态：待前端处理。**

## 关联 / 联系人

### 链接

- **Issue**: [#7078](https://git.1814.love:8443/wx/HL/issues/7078)
- **PR**: [#7086](https://git.1814.love:8443/wx/HL/pulls/7086)
- **Merge commit**: [6462397526ad61acfbcf503486d8507c9c1c7293](https://git.1814.love:8443/wx/HL/commit/6462397526ad61acfbcf503486d8507c9c1c7293)

### 联系人

- **后端负责人**: @lc