---
schema: "hl-changelog/v2"
ticket: "7029"
title: "供应商新增账户接入企微审批"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: "2026-09-03"
status_note: "后端已改为企微异步审批；前端需切换账户新增路径、展示待审批状态并移除本地人工审批入口。"
updated_at: "2026-09-03"
base: "dev-v3"
---

# 供应商模块：新增账户接入企微审批

> **服务**: `hl-resource-service`（8082）、`hl-user-service`（8081）
> **Issue**: #7029
> **PR**: #7031
> **影响范围**: 管理后台供应商列表的账户管理

## ⚠️ 关键变化

已审核通过的供应商新增账户后不再立即生效，也不再由管理端调用人工审批接口；后端会在企微“账户”模板发起审批，账户先返回 `PENDING`，企微通过并同步后才变为 `ACTIVE`。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 批量新增并提交收款账户 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | 行为修改 | 每个账户独立发起企微审批并返回审批状态 |

## 三、接口详情

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

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

#### 使用场景

供应商状态为 `ACTIVE` 后，在账户管理中新增一至五十个收款账户。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| supplierId | Path | String | 是 | 正整数雪花 ID | 已生效供应商 |
| accounts | Body | Array | 是 | 1～50 项 | 收款账户列表 |
| accounts[].accountType | Body | String | 是 | `CORPORATE` / `PERSONAL` | 账户类型 |
| accounts[].bankName | Body | String | 是 | 最长 500 | 开户行 |
| accounts[].bankBranch | Body | String | 否 | 最长 500 | 开户支行 |
| accounts[].accountNo | Body | String | 是 | 8～128 位，仅数字、空格、`-` | 账号 |
| accounts[].proofFileUrls | Body | Array | 否 | 最多 20 项 | 证明附件 |
| accounts[].settleMode | Body | String | 否 | `PREPAY` / `MONTHLY` / `SINGLE` | 结算方式 |
| accounts[].accountPeriod | Body | String | 条件必填 | `MONTHLY` 时必填，其他方式必须为空 | 账期 |
| accounts[].invoiceType | Body | String | 否 | `SPECIAL` / `NORMAL` / `NONE` | 发票类型 |
| accounts[].taxRate | Body | String | 条件必填 | 可开票时必填，`NONE` 时必须为空 | `0%`～`100%`，最多两位小数 |

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

| 字段 | 类型 | 说明 |
|---|---|---|
| accountId | String | 新账户 ID |
| approvalLogId | String | 账户审批记录 ID |
| requestNo | String | 同一请求重放使用的稳定请求号 |
| provider | String | 新申请固定为 `WECOM` |
| approvalStatus | String | 新申请为 `PENDING`，通过后为 `APPROVED` |
| spNo | String | 企微审批单号 |
| spStatus | String / null | 企微原始状态，完成同步前可为空 |
| syncStatus | String | 正常建单为 `REQUESTING`，完成应用为 `APPLIED`；异常可能为 `APPLY_FAILED` / `RESULT_UNCERTAIN` |
| accountStatus | String | 通过前 `PENDING`，通过后 `ACTIVE` |
| isDefault | String | 新增账户固定为 `NO` |
| submittedAt | String / null | 提交时间 |
| finishedAt | String / null | 完成时间，审批中为空 |

#### 请求示例

```json
{
  "accounts": [
    {
      "accountType": "PERSONAL",
      "bankName": "示例银行",
      "bankBranch": "示例支行",
      "accountNo": "6222 0000 1234 5678",
      "proofFileUrls": [],
      "settleMode": "SINGLE",
      "accountPeriod": null,
      "invoiceType": "NONE",
      "taxRate": null
    }
  ]
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "accountId": "353807302408683520",
      "approvalLogId": "353807302408683521",
      "requestNo": "SUP-ACC-REQ-example",
      "provider": "WECOM",
      "approvalStatus": "PENDING",
      "spNo": "202609030009",
      "spStatus": null,
      "syncStatus": "REQUESTING",
      "accountStatus": "PENDING",
      "isDefault": "NO",
      "submittedAt": "2026-09-03 15:45:00",
      "finishedAt": null
    }
  ],
  "success": true
}
```

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

写接口不返回空成功列表。企微结果不确定时仍保留账户和审批事实为 `PENDING`，对应项返回 `syncStatus=RESULT_UNCERTAIN`，前端不得自动重提。

#### 错误响应

```json
{
  "code": 395010,
  "message": "请先完成供应商注册",
  "data": null,
  "success": false
}
```

#### 业务边界

| code | 场景 | 前端处理 |
|---|---|---|
| `400` | 账户字段、枚举或组合规则不合法 | 保留表单并展示后端提示 |
| `395001` | 供应商不存在 | 关闭弹窗并刷新列表 |
| `395002` | 无账户管理或提交权限 | 禁止操作 |
| `395010` | 供应商不是 `ACTIVE` | 先完成供应商注册审批 |
| `395011` | 同一账号已有在途审批 | 不重复提交，刷新账户列表 |
| `395027` | 账号已被占用 | 联系财务核实 |

- 每个账户生成独立审批；顶层 `success=true` 后仍须检查每项 `syncStatus` 和 `accountStatus`。
- 企微模板固定展示供应商、账户类型、开户行和账号，审批人由企微模板配置决定，前端不传审批人。

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

1. 新增账户只调用 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`，请求体必须使用 `accounts` 数组。
2. 成功建单后展示“待审批”，不得把 `PENDING` 当作可用账户，也不得调用旧的 `/supplier/{supplierId}/accounts/{accountId}/approve`。
3. 通过 `GET /admin/supplier/items/{supplierId}/account-info/list` 刷新状态；只有 `status=ACTIVE` 才展示为生效中。
4. 必须同时判断顶层 `success/code` 与每项 `syncStatus/accountStatus`；`RESULT_UNCERTAIN` 只提示对账，不自动重试。

## 五、数据库行为

提交成功后先持久化 `PENDING`、非默认账户及对应审批记录；企微审批通过后异步更新为 `ACTIVE`，并追加审批关联的账户启用审计。外部提交失败或结果不确定时不会把账户标记为生效。

## 六、边界行为

- 供应商创建时携带的初始账户仍随供应商注册审批，通过前为 `PENDING`，通过后为 `ACTIVE`。
- 后续新增账户与供应商创建时是否携带初始账户无关，只要求供应商当前为 `ACTIVE`。
- 企微驳回或撤销不会激活账户；终态由后端回调或轮询同步。
- 接口使用统一 `Result`；业务错误可能仍为 HTTP 200，必须读取响应体 `code/success`。

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

### accountStatus / 账户列表 status

| 值 | 中文 | 说明 |
|---|---|---|
| `PENDING` | 待审批 | 不可作为生效账户使用 |
| `ACTIVE` | 生效中 | 企微审批通过且后端已完成应用 |
| `DISABLED` | 已停用 | 本工单未修改停用流程 |

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

| 行为 | 修改前 | 修改后 |
|---|---|---|
| 新增账户 | 本地自动通过并立即 `ACTIVE` | 企微建单后先 `PENDING`，通过后才 `ACTIVE` |
| 审批动作 | 管理端存在本地人工审批调用 | 仅在企微处理，管理端只刷新状态 |
| 新增路径 | 旧页面调用 `/supplier/{supplierId}/accounts` | 调用 `/admin/supplier/items/{supplierId}/bank-accounts/add` |

## 六.7、影响评估

- **是否破坏向后兼容**: 是；新增账户由同步生效改为异步审批。
- **前端是否必须同步上线**: 是。
- **前端 workaround 清理点**: 删除账户本地审批按钮及 `/supplier/{supplierId}/accounts/{accountId}/approve` 调用。

## 七、不影响范围

- **仅影响**: 管理后台供应商账户新增及状态展示。
- **零影响**: 账户详情读取、默认账户切换、停用流程、合同、资源绑定和小程序接口。

## 八、测试环境已验证

TEST Gateway 已验证：初始账户随注册审批由 `PENDING` 转为 `ACTIVE`；后续账户使用指定企微模板建单并在通过后由 `PENDING` 转为 `ACTIVE`，审批记录和启用审计均可查询；非法账户类型返回业务失败且零写入。

## 十、相关文档

- [Issue #7029](https://git.1814.love:8443/wx/HL/issues/7029)
- [PR #7031](https://git.1814.love:8443/wx/HL/pulls/7031)

## 前端动作与当前状态

- 将账户新增改为批量接口及 `accounts` 请求结构。
- 新增后展示 `PENDING`，轮询或刷新账户列表，直到后端返回 `ACTIVE`。
- 移除管理端账户审批按钮和旧人工审批请求。
- **当前状态：待前端处理。**

## 关联 / 联系人

- **Issue**: [#7029](https://git.1814.love:8443/wx/HL/issues/7029)
- **PR**: [#7031](https://git.1814.love:8443/wx/HL/pulls/7031)
- **Merge commit**: [f5dfa7771a61948bb4d59e35fbedb67d61fcb3f3](https://git.1814.love:8443/wx/HL/commit/f5dfa7771a61948bb4d59e35fbedb67d61fcb3f3)
- **后端负责人**: @lc