---
schema: "hl-changelog/v2"
ticket: "7182"
title: "供应商账户删除、启用与新记录式修改审批"
consumer: "admin"
author: "lc(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "326a1523"
target_release: ""
verified_at: "2026-09-07"
status_note: "前端已交付 ref 326a1523(+sync-log 20eb2a19):accounts.js 新增 enable/delete/update 三 API(disable 已有);SupplierAccountsManageModal 操作列扩启用/修改/删除(显隐 status×isDefault、在途审批本地禁用+后端 395011/395028 兜底);新建 SupplierAccountEditModal 新记录式修改(条件必填月结账期/开票税率、proofFileUrls 按权限省略);移除「无删除/停用入口」过时提示。supplier 域 175+全量 vitest 2171 绿,生产构建过。"
updated_at: "2026-09-06"
base: "dev-v3"
---

# 供应商：账户删除、启用与新记录式修改审批

## 关键变化

`#7029` 中“无删除/停用入口”已过时。后端现提供删除、停用、启用和修改四类审批操作；提交成功只表示待审，企微通过后才应用账户变更。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 申请停用账户 | POST | `/admin/supplier/bank-accounts/{accountId}/disable` | 权限与链路延用 | 保留现有入口，待审期间仍启用 |
| 2 | 申请启用账户 | POST | `/admin/supplier/bank-accounts/{accountId}/enable` | 新增接口 | 待审期间仍停用 |
| 3 | 申请删除账户 | POST | `/admin/supplier/bank-accounts/{accountId}/delete` | 新增接口 | 通过后软删除 |
| 4 | 申请修改账户 | PUT | `/admin/supplier/bank-accounts/{accountId}/update` | 新增接口 | 新建 PENDING 记录，原账户待审期间继续生效 |

## 三、接口详情

### 1. 申请停用 `POST /admin/supplier/bank-accounts/{accountId}/disable`

**VO**: `SupplierAccountDisableReqVO / BankAccountSubmitResultRespVO`

#### 使用场景

对非默认 `ACTIVE` 账户申请停用。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| accountId | Path | String | 是 | 正整数 | 目标账户 ID |
| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 最新账户详情版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| accountId / approvalLogId | String | 账户 / 审批记录 ID |
| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
| syncStatus / accountStatus / isDefault | String | 同步状态 / 账户现态 / 默认标记 |
| submittedAt / finishedAt | String/null | 提交 / 终态时间 |

#### 请求示例

```json
{"expectedUpdateTime":"2026-09-06 12:00:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182002","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060001","syncStatus":"REQUESTING","accountStatus":"ACTIVE","isDefault":"NO"}}
```

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

无空成功数据；账户不存在返回 `395001`。企微提交或对账异常按 `syncStatus` 返回原审批事实，不直接停用账户。

#### 错误响应

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

#### 业务边界

- 仅非默认 `ACTIVE` 账户可提交；待审期间仍 `ACTIVE`，通过后才 `DISABLED`。
- 供应商必须 `ACTIVE`，主体与账户均不能有在途审批；失败零写入。

### 2. 申请启用 `POST /admin/supplier/bank-accounts/{accountId}/enable`

**VO**: `SupplierAccountActionReqVO / BankAccountSubmitResultRespVO`

#### 使用场景

对 `DISABLED` 账户申请恢复启用。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| accountId | Path | String | 是 | 正整数 | 目标账户 ID |
| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 最新账户详情版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| accountId / approvalLogId | String | 账户 / 审批记录 ID |
| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
| syncStatus / accountStatus / isDefault | String | 同步状态 / 账户现态 / 默认标记 |
| submittedAt / finishedAt | String/null | 提交 / 终态时间 |

#### 请求示例

```json
{"expectedUpdateTime":"2026-09-06 12:00:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182003","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060002","syncStatus":"REQUESTING","accountStatus":"DISABLED","isDefault":"NO"}}
```

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

无空成功数据；账户不存在返回 `395001`。企微异常不会提前启用账户，调用方须按 `syncStatus` 展示待同步/待对账。

#### 错误响应

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

#### 业务边界

- 仅 `DISABLED` 账户可提交；待审期间仍 `DISABLED`，通过后才 `ACTIVE`。
- 供应商必须 `ACTIVE`，主体与账户均不能有在途审批；失败零写入。

### 3. 申请删除 `POST /admin/supplier/bank-accounts/{accountId}/delete`

**VO**: `SupplierAccountActionReqVO / BankAccountSubmitResultRespVO`

#### 使用场景

对非默认 `ACTIVE` 或 `DISABLED` 账户申请删除。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| accountId | Path | String | 是 | 正整数 | 目标账户 ID |
| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 最新账户详情版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| accountId / approvalLogId | String | 账户 / 审批记录 ID |
| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
| syncStatus / accountStatus / isDefault | String | 同步状态 / 账户现态 / 默认标记 |
| submittedAt / finishedAt | String/null | 提交 / 终态时间 |

#### 请求示例

```json
{"expectedUpdateTime":"2026-09-06 12:00:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182004","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060003","syncStatus":"REQUESTING","accountStatus":"ACTIVE","isDefault":"NO"}}
```

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

无空成功数据；已软删除或不存在返回 `395001`。企微异常时保留原账户，不把提交成功当作删除成功。

#### 错误响应

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

#### 业务边界

- 仅非默认 `ACTIVE` 或 `DISABLED` 账户可提交；待审期间保留原状态，通过后才软删除。
- 供应商必须 `ACTIVE`，主体与账户均不能有在途审批；失败零写入。

### 4. 申请修改 `PUT /admin/supplier/bank-accounts/{accountId}/update`

**VO**: `SupplierAccountUpdateReqVO / BankAccountSubmitResultRespVO`

#### 使用场景

对 `ACTIVE` 账户提交完整新资料。后端新建待审账户，不覆盖原记录。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| accountId | Path | String | 是 | 正整数 | 原账户 ID |
| accountType / bankName / accountNo | Body | String | 是 | 沿用账户校验 | 新账户核心资料 |
| bankBranch / proofFileUrls | Body | String/List | 否 | 附件最多 20 个 | 开户支行 / 证明材料 |
| settleMode / accountPeriod | Body | String | 否 | 月结时账期必填 | 结算方式 / 账期 |
| invoiceType / taxRate | Body | String | 否 | 开票时税率必填 | 发票类型 / 税率 |
| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 原账户最新版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| accountId / approvalLogId | String | 新建待审账户 / 审批记录 ID |
| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
| syncStatus / accountStatus / isDefault | String | 同步状态 / 新账户现态 / 默认标记 |
| submittedAt / finishedAt | String/null | 提交 / 终态时间 |

#### 请求示例

```json
{"accountType":"CORPORATE","bankName":"示例银行","bankBranch":"示例支行","accountNo":"718200000002","proofFileUrls":[],"settleMode":"PREPAY","invoiceType":"NONE","expectedUpdateTime":"2026-09-06 12:00:00"}
```

#### 响应示例

```json
{"code":200,"message":"成功","success":true,"data":{"accountId":"7182010","approvalLogId":"7182011","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060004","syncStatus":"REQUESTING","accountStatus":"PENDING","isDefault":"NO"}}
```

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

无空成功数据；原账户不存在返回 `395001`。企微异常时原账户保持 `ACTIVE`，已创建的新记录按同步状态对账，不覆盖原账户。

#### 错误响应

```json
{"code":395027,"message":"该收款账号已被占用，请联系财务核实","success":false,"data":null}
```

#### 业务边界

- 仅 `ACTIVE` 原账户可提交，新 `accountNo` 必须全局未占用；返回的 `accountId` 是新记录。
- 待审期间原账户 `ACTIVE`、新记录 `PENDING`；通过后原账户 `DISABLED`、新记录 `ACTIVE` 并承接默认标记。
- 驳回或撤销后原账户不变、新记录 `DISABLED`；所有门禁失败零写入。

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

1. 先读取账户详情，将最新 `updateTime` 原样传为 `expectedUpdateTime`。
2. 提交后根据 `approvalStatus`、`syncStatus`、`accountStatus` 展示待审态，不要把 `code=200` 解释为已应用。
3. 同账户有在途审批时禁用其他变更按钮；回调或轮询进入终态后刷新账户列表和详情。
4. 修改成功返回的 `accountId` 指向新记录；驳回/撤销后不要用新记录覆盖原账户。
5. 前端需移除“无删除/停用入口”的过时提示，接入四类操作的按钮、版本参数、待审展示和终态刷新。

## 五、数据库行为

无 DDL。四类操作复用现有账户审批表和企微回调/轮询链路；修改新建账户行，删除仅在审批通过后软删除目标行。

## 六、边界行为

- `401`：未登录；`400`：缺参或字段校验失败。
- `395001`：账户/供应商不存在；`395002`：角色或权限不允许。
- `395005`：供应商主审批中、账户状态或默认标记不允许；`395010`：供应商非 `ACTIVE`（如暂停合作）。
- `395011` / `395028`：账户已有在途审批/变更；`395014`：版本过期；`395027`：新账号已占用。
- `395019`–`395022`：企微配置、绑定、提交失败或结果待对账；按 `syncStatus` 处理，不要无限新建申请。

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

- `approvalStatus`：`PENDING` 审核中，`APPROVED` 已通过，`REJECTED` 已驳回，`CANCELED` 已撤销。
- `accountStatus`：`PENDING`、`ACTIVE`、`DISABLED`、`DELETED`；历史 `REJECTED` 仅兼容读取。
- `syncStatus`：`REQUESTING`、`APPLIED`、`APPLY_FAILED`、`RESULT_UNCERTAIN`。

## 七、不影响范围

仅影响管理后台供应商账户维护。已有账户新增、查询、设为默认的路径与响应结构不变；无数据迁移、Redis、MQ 或前端源码变更。

## 八、测试环境已验证

TEST Gateway 已验证真实企微通过后的修改、停用、启用与删除：修改待审期间原账户继续生效，通过后新旧记录正确迁移；停用/启用待审期间保持原状态；`ACTIVE` 与 `DISABLED` 删除通过后均软删除。同版本重试复用原审批，在途变更、主体审批中、暂停合作和未登录请求均被拒绝且零写入。合成账户已清理，有效账户数回到基线 0；前端待接入。

## 十、相关文档

- **Issue**：[#7182](https://git.1814.love:8443/wx/HL/issues/7182)
- **PR**：[#7192](https://git.1814.love:8443/wx/HL/pulls/7192)
- **Merge commit**：[`06e682ae417defddcfb391d2afc4e928fc702627`](https://git.1814.love:8443/wx/HL/commit/06e682ae417defddcfb391d2afc4e928fc702627)

## 关联 / 联系人

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