---
schema: "hl-changelog/v2"
ticket: "7101"
title: "供应商合作中资料变更接入企微审批"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "fbed9101"
target_release: ""
verified_at: "2026-09-05"
status_note: "后端已部署并通过 TEST；前端需将合作中资料保存结果按企微异步审批处理，并展示审核中。"
updated_at: "2026-09-05"
base: "dev-v3"
---

# 供应商模块：合作中资料变更接入企微审批

> **服务**: `hl-resource-service`、`hl-user-service`
> **Issue**: #7101
> **PR**: #7125、#7128
> **日期**: 2026-09-05
> **影响范围**: 管理后台供应商资料保存与新增收款账户结果展示

## ⚠️ 关键变化

合作中（`ACTIVE`）供应商保存资料不再直接更新正式资料：接口先返回企微审批受理结果，待审批时统一显示“审核中”；驳回不更新，通过后才应用本次申请。新增账户仍独立审批，本次补充中文审批状态字段。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 更新供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 行为与响应修改 | `ACTIVE` 改为企微审批后生效，响应新增 `approval` |
| 2 | 批量新增收款账户 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | 响应字段扩展 | 每项新增 `approvalStatusName` |

## 三、接口详情

### 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 | `ACTIVE` 必填 | 最长 500 | 变更原因 |
| 资料字段 | Body | 原类型 | 否 | 沿用原契约 | 至少产生一项实际变化 |
| `contacts` | Body | Array | 否 | 完整快照 | 已有联系人带 `contactId`、`expectedUpdateTime`；新增联系人省略 `contactId` |

#### 出参 `Result<SupplierWriteRespVO>`

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.status` | String | 审批期间仍为 `ACTIVE` |
| `data.statusName` | String | 待审批时为“审核中” |
| `data.approval.approvalLogId` | String | 资料变更审批记录 ID |
| `data.approval.approvalStatus` | String | 初次受理为 `PENDING` |
| `data.approval.approvalStatusName` | String | 初次受理为“审核中” |
| `data.approval.spNo` | String | 企业微信审批单号 |
| `data.approval.syncStatus` | String | 审批同步状态 |
| `data.updateTime` | String | 审核中仍返回正式资料当前版本 |

#### 请求示例

```json
{
  "remark": "更新合作备注",
  "changeReason": "业务资料更新",
  "expectedUpdateTime": "2026-09-05 09:00:00"
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "2095000000000000001",
    "status": "ACTIVE",
    "statusName": "审核中",
    "approval": {
      "approvalLogId": "2095000000000000002",
      "provider": "WECOM",
      "approvalStatus": "PENDING",
      "approvalStatusName": "审核中",
      "spNo": "202609050001",
      "syncStatus": "REQUESTING"
    },
    "updateTime": "2026-09-05 09:00:00"
  }
}
```

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

成功受理时 `data.approval` 不为空；企微结果不确定时保留审批事实，前端不得自动重复提交。草稿直接保存时 `data.approval=null`。

#### 错误响应

```json
{
  "code": 395014,
  "message": "数据已被他人修改，请刷新后重试",
  "success": false,
  "data": null
}
```

`400` 表示字段、联系人快照或变更原因不合法；`395005` 表示当前状态不允许；`395019`～`395022` 表示企微未配置、账号未绑定、提交失败或状态待对账。未新增错误码。

#### 业务边界

- 审核中正式资料保持原值；驳回不更新，通过后一次性应用申请中的冻结值。
- 新增联系人必须省略 `contactId`，不得发送 `contactId:null`；只修正内部审批快照兼容，不放宽外部显式空 ID 校验。
- 企微表单的变更明细只列实际差异，身份证号和个人电话完整展示；相关附件和当前正式资料为选填。

### 2. 批量新增收款账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`

**VO**: `SupplierBankAccountBatchCreateReqVO → List<BankAccountSubmitResultRespVO>`

#### 使用场景

为合作中供应商新增一至五十个收款账户，每个账户独立提交企微审批。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 | 合作中供应商 ID |
| `accounts` | Body | Array | 是 | 1～50 项 | 账户列表，原请求结构不变 |

#### 出参 `Result<List<BankAccountSubmitResultRespVO>>`

| 字段 | 类型 | 说明 |
|---|---|---|
| `data[].approvalStatus` | String | `PENDING` / `APPROVED` / `REJECTED` |
| `data[].approvalStatusName` | String | “审核中” / “已通过” / “已驳回” |
| `data[].accountStatus` | String | 审核中为 `PENDING`，通过为 `ACTIVE`，驳回为 `REJECTED` |
| `data[].spNo` | String | 企业微信审批单号 |

#### 请求示例

```json
{
  "accounts": [{
    "accountType": "PERSONAL",
    "bankName": "示例银行",
    "bankBranch": "示例支行",
    "accountNo": "6222000012345678",
    "proofFileUrls": [],
    "settleMode": "SINGLE",
    "invoiceType": "NONE"
  }]
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [{
    "accountId": "2095000000000000003",
    "approvalLogId": "2095000000000000004",
    "provider": "WECOM",
    "approvalStatus": "PENDING",
    "approvalStatusName": "审核中",
    "spNo": "202609050002",
    "syncStatus": "REQUESTING",
    "accountStatus": "PENDING",
    "isDefault": "NO"
  }]
}
```

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

写接口不返回空成功列表；结果不确定时账户保持不可用，前端不得自动重提。

#### 错误响应

```json
{
  "code": 395011,
  "message": "该账户正在审批中，请勿重复提交",
  "success": false,
  "data": null
}
```

`400` 表示账户字段或组合规则不合法；`395010` 表示供应商尚未生效；其他企微错误沿用现有 `395019`～`395022`。

#### 业务边界

- 每个账户独立审批；审核中保持 `PENDING` 且不可收款、不可设为默认。
- 企微驳回后为 `REJECTED`，通过后为 `ACTIVE`；前端只把 `ACTIVE` 当作生效账户。

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

1. 更新接口返回成功后，若 `data.approval.approvalStatus=PENDING`，展示“审核中”并保留正式资料页面值，不做本地乐观覆盖。
2. 通过详情、审批记录或账户列表刷新终态；审批只能在企业微信处理，管理端不发送通过或驳回命令。
3. 联系人数组是完整快照；新增项省略 `contactId`，已有项同时传 `contactId` 与 `expectedUpdateTime`。
4. 所有接口同时检查 HTTP 状态和响应体 `code/success`。

## 五、数据库行为

- 本次无数据库结构或迁移变化。
- 资料审批中不写正式资料；通过后应用冻结申请，驳回后正式版本和值均不变。
- 新账户审批中为 `PENDING`，通过后为 `ACTIVE`，驳回后为 `REJECTED`。

## 六、边界行为

- 模板审批节点由企业微信配置决定，后端不校验“恰好一级”。
- 表单固定使用已配置的八个 `Text` 控件；相关附件与当前正式资料允许为空。
- 企微回调或轮询完成前，前端只展示受理状态，不推断最终结果。

## 六.5、枚举 / 数据字典

| 字段 | 值 | 中文 | 说明 |
|---|---|---|---|
| `approvalStatus` | `PENDING` | 审核中 | 尚未终结 |
| `approvalStatus` | `APPROVED` | 已通过 | 业务变更已应用 |
| `approvalStatus` | `REJECTED` | 已驳回 | 业务变更未应用 |
| `accountStatus` | `PENDING` | 待审批 | 账户不可用 |
| `accountStatus` | `ACTIVE` | 生效中 | 账户可用 |
| `accountStatus` | `REJECTED` | 已驳回 | 账户不可用 |

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

| 行为 | 修改前 | 修改后 |
|---|---|---|
| `ACTIVE` 供应商保存资料 | 直接更新正式资料 | 返回企微审批；通过后更新，驳回不更新 |
| 资料保存响应 | 无独立资料审批结果 | 返回 `data.approval` 与“审核中”状态 |
| 新增账户响应 | 仅英文审批状态 | 增加 `approvalStatusName` 中文状态 |

## 六.7、影响评估

- **是否破坏向后兼容**: 是；合作中资料保存由同步生效改为异步审批。
- **前端是否必须同步上线**: 是。
- **前端 workaround 清理点**: 删除保存成功后立即以请求值覆盖正式资料的逻辑，改为展示“审核中”并刷新终态。

## 七、不影响范围

- 草稿供应商直接保存、注册审批、主体状态审批、合同、默认账户和停用流程不变。
- 新增账户的请求路径、请求字段和独立审批语义不变。
- 未新增数据库、配置、Redis、MQ 或错误码。

## 八、测试环境已验证

```text
PUT  /admin/supplier/items/{supplierId}/update                    → PENDING / 审核中，正式资料保持原值 ✓
企微通过资料变更                                                  → 正式资料更新，身份证号与电话完整值可见 ✓
企微驳回资料变更                                                  → 正式资料和值版本均不变 ✓
POST /admin/supplier/items/{supplierId}/bank-accounts/add         → PENDING / 审核中 ✓
企微通过新增账户                                                  → ACTIVE ✓
企微驳回新增账户                                                  → REJECTED，未激活 ✓
```

资料审批使用模板 `3WNhaxns4i6kfVs74gz4qZQhFxy4iJY4anxMuvYw`；八个 `Text` 控件、实际差异格式、完整身份证号/电话和两个选填项已逐项验证。部署提交为 `6bc1c1262e5e4902a893f30fac875d35a65f8a76`。

## 十、相关文档

- [Issue #7101](https://git.1814.love:8443/wx/HL/issues/7101)
- [主 PR #7125](https://git.1814.love:8443/wx/HL/pulls/7125)
- [补充 Issue #7127](https://git.1814.love:8443/wx/HL/issues/7127)
- [补充 PR #7128](https://git.1814.love:8443/wx/HL/pulls/7128)

## 前端动作与当前状态

- 合作中资料保存成功后读取 `data.approval`，展示“审核中”，刷新终态后再更新正式资料。
- 新增账户直接展示 `approvalStatusName`，并按 `accountStatus` 判断是否可用。
- 新增联系人省略 `contactId`，已有联系人继续携带 ID 与版本。
- **当前状态：待前端处理。**

## 关联 / 联系人

### 链接

- **Issue**: [#7101](https://git.1814.love:8443/wx/HL/issues/7101)
- **PR**: [#7125](https://git.1814.love:8443/wx/HL/pulls/7125)
- **Merge commit**: [91a965f0b0f403a0f8c9d3990587f09ea780c9dd](https://git.1814.love:8443/wx/HL/commit/91a965f0b0f403a0f8c9d3990587f09ea780c9dd)

### 联系人

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