---
schema: "hl-changelog/v2"
ticket: "7318"
title: "供应商删除账期并必填证照图片"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "edefb5c4"
target_release: ""
verified_at: "2026-09-08"
status_note: "前端已删除账户账期全链路(表单/预填/清洗/payload/列表/详情),新增资质行证照图片必填行内拦截,已有资质留空保留原图;合同域 settleCycle 未动。提交 edefb5c4"
updated_at: "2026-09-08"
base: "dev-v3"
---

# ⚠️ 供应商：删除账期并必填证照图片

前端删除账户账期输入、提交和展示；新增资质及完整提交时要求上传证照图片。当前状态：后端已部署并验证，前端待适配。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 新增供应商 | POST | `/admin/supplier/items/add` | 修改 | 移除账期请求；证照图片必填 |
| 2 | 修改供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 修改 | 移除账期请求；证照图片必填 |
| 3 | 提交供应商 | POST | `/admin/supplier/items/{supplierId}/submit` | 修改 | 移除账期请求；证照图片必填 |
| 4 | 新增收款账户 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | 修改 | 移除账期请求 |
| 5 | 修改收款账户 | PUT | `/admin/supplier/bank-accounts/{accountId}/update` | 修改 | 移除账期请求 |
| 6 | 账户列表 | GET | `/admin/supplier/items/{supplierId}/account-info/list` | 修改 | 账户响应不再含账期 |
| 7 | 账户详情 | GET | `/admin/supplier/bank-accounts/{accountId}/view` | 修改 | 账户响应不再含账期 |
| 8 | 设置默认账户 | PUT | `/admin/supplier/bank-accounts/{accountId}/default/update` | 修改 | 账户响应不再含账期 |

## 三、接口详情

以下仅列本次变更及调用关键字段；审批响应示意省略未变更的提供方明细。示例 ID 与版本仅用于说明，实际使用页面最新值。

### 1. 新增供应商 `POST /admin/supplier/items/add`

**VO**: `SupplierDraftSaveReqVO → SupplierWriteRespVO`

#### 使用场景

供应商管理页面新增供应商。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| qualifications[].imageUrl | Body | String | 每项必填 | 非空，最长 1000 字符 | 证照图片地址 |
| initialAccounts[].accountPeriod | Body | 已删除 | 否 | 不再提交 | 账期输入已移除 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data | Object | 原有写入/审批结果；初始账户摘要原本就没有账期 |

#### 请求示例

```http
POST https://api.test.1814.love:9443/admin/supplier/items/add
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "fullName": "测试供应商7318",
  "taxNo": "91350211M000100Y46",
  "types": [
    {
      "typeCode": "SCENIC"
    }
  ],
  "legalRepresentative": "测试法人",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.test/front.png",
  "legalRepresentativeIdCardBackUrl": "https://files.example.test/back.png",
  "contactPhone": "01012345678",
  "establishDate": "2020-01-01",
  "address": "测试地址",
  "mainCooperation": "景区服务",
  "licenseImageUrl": "https://files.example.test/license.png",
  "contacts": [
    {
      "contactName": "测试联系人",
      "contactPhone": "13800138000",
      "contactRole": "contentMoney"
    }
  ],
  "qualifications": [
    {
      "qualType": "GZZRX_LICENSE",
      "certNo": "TEST-7318",
      "permanentValid": true,
      "imageUrl": "https://files.example.test/7318/permit.png"
    }
  ],
  "initialAccounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ]
}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"731801","supplierNo":"SUP731801","status":"DRAFT","statusName":"草稿","onboardingStage":"PROFILE_DRAFT","initialAccounts":[{"accountId":"731802","accountNo":"7318123456789012","accountNoMask":"7318123456789012","status":"DRAFT"}],"approval":null,"updateTime":"2026-09-08 17:00:00"}}
```

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

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

#### 错误响应

```json
{"code":400,"message":"证照图片不能为空","data":null}
```

#### 业务边界

- 上传成功取得非空图片地址后再提交；缺图拒绝当前请求。

### 2. 修改供应商 `PUT /admin/supplier/items/{supplierId}/update`

**VO**: `SupplierUpdateReqVO → SupplierWriteRespVO`

#### 使用场景

供应商管理页面修改供应商。以下请求示例用于 DRAFT 草稿；非草稿不允许通过 initialAccounts 维护账户，资料修改沿用必填 changeReason。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| supplierId | Path | String | 是 | 正整数 ID | 当前记录 |
| qualifications[].imageUrl | Body | String | 新增项必填；已有 qualificationId 的项省略/null 保留原图 | 非空，最长 1000 字符 | 证照图片地址 |
| initialAccounts[].accountPeriod | Body | 已删除 | 否 | 不再提交 | 账期输入已移除 |
| expectedUpdateTime | Body | String | 是 | yyyy-MM-dd HH:mm:ss | 使用最新详情的 updateTime |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data | Object | 原有写入/审批结果；初始账户摘要原本就没有账期 |

#### 请求示例

```http
PUT https://api.test.1814.love:9443/admin/supplier/items/731801/update
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "expectedUpdateTime": "2026-09-08 17:00:00",
  "qualifications": [
    {
      "qualificationId": "731804",
      "imageUrl": "https://files.example.test/7318/permit.png"
    }
  ],
  "initialAccounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ]
}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"731801","supplierNo":"SUP731801","status":"DRAFT","statusName":"草稿","onboardingStage":"PROFILE_DRAFT","initialAccounts":[{"accountId":"731802","accountNo":"7318123456789012","accountNoMask":"7318123456789012","status":"DRAFT"}],"approval":null,"updateTime":"2026-09-08 17:00:00"}}
```

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

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

#### 错误响应

```json
{"code":400,"message":"证照图片不能为空","data":null}
```

#### 业务边界

- qualifications 提交完整保留集合，未包含的既有项会被删除；项内 imageUrl 省略/null 才保留原图。空白及归一化后为空的图片均拒绝。整个数组未提交时不强制补齐历史图片。

### 3. 提交供应商 `POST /admin/supplier/items/{supplierId}/submit`

**VO**: `SupplierSubmitReqVO → SupplierApprovalCommandRespVO`

#### 使用场景

供应商管理页面提交供应商。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| supplierId | Path | String | 是 | 正整数 ID | 当前记录 |
| qualifications[].imageUrl | Body | String | 每项必填 | 非空，最长 1000 字符 | 证照图片地址 |
| initialAccounts[].accountPeriod | Body | 已删除 | 否 | 不再提交 | 账期输入已移除 |
| expectedUpdateTime | Body | String | 是 | yyyy-MM-dd HH:mm:ss | 使用最新详情的 updateTime |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data | Object | 原有写入/审批结果；初始账户摘要原本就没有账期 |

#### 请求示例

```http
POST https://api.test.1814.love:9443/admin/supplier/items/731801/submit
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "fullName": "测试供应商7318",
  "taxNo": "91350211M000100Y46",
  "types": [
    {
      "typeCode": "SCENIC"
    }
  ],
  "legalRepresentative": "测试法人",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.test/front.png",
  "legalRepresentativeIdCardBackUrl": "https://files.example.test/back.png",
  "contactPhone": "01012345678",
  "establishDate": "2020-01-01",
  "address": "测试地址",
  "mainCooperation": "景区服务",
  "licenseImageUrl": "https://files.example.test/license.png",
  "contacts": [
    {
      "contactName": "测试联系人",
      "contactPhone": "13800138000",
      "contactRole": "contentMoney"
    }
  ],
  "qualifications": [
    {
      "qualType": "GZZRX_LICENSE",
      "certNo": "TEST-7318",
      "permanentValid": true,
      "imageUrl": "https://files.example.test/7318/permit.png"
    }
  ],
  "initialAccounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ],
  "expectedUpdateTime": "2026-09-08 17:00:00"
}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中"}}
```

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

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

#### 错误响应

```json
{"code":400,"message":"证照图片不能为空","data":null}
```

#### 业务边界

- 上传成功取得非空图片地址后再提交；缺图拒绝当前请求。

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

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

#### 使用场景

供应商管理页面新增收款账户。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| supplierId | Path | String | 是 | 正整数 ID | 当前记录 |
| accounts | Body | Array | 是 | 1–50 项 | 按输入顺序返回审批结果 |
| accounts[].accountType | Body | String | 是 | CORPORATE / PERSONAL | 对公 / 对私 |
| accounts[].bankName | Body | String | 是 | 最长 500 字符 | 开户银行 |
| accounts[].accountNo | Body | String | 是 | 去空白/连字符后 8–32 位数字 | 收款账号 |
| accounts[].accountPeriod | Body | 已删除 | 否 | 不再提交 | 删除账期输入 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data | Array | 原有写入/审批结果；初始账户摘要原本就没有账期 |

#### 请求示例

```http
POST https://api.test.1814.love:9443/admin/supplier/items/731801/bank-accounts/add
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "accounts": [
    {
      "accountType": "CORPORATE",
      "bankName": "测试银行",
      "accountNo": "7318123456789012"
    }
  ]
}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":[{"accountId":"731802","approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中","accountStatus":"PENDING","isDefault":"NO"}]}
```

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

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

#### 错误响应

```json
{"code":400,"message":"开户银行不能为空","data":null}
```

#### 业务边界

- 沿用既有账户状态和权限限制；删除账期不跳过审批。

### 5. 修改收款账户 `PUT /admin/supplier/bank-accounts/{accountId}/update`

**VO**: `SupplierAccountUpdateReqVO → BankAccountSubmitResultRespVO`

#### 使用场景

供应商管理页面修改收款账户。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| accountId | Path | String | 是 | 正整数 ID | 当前记录 |
| expectedUpdateTime | Body | String | 是 | yyyy-MM-dd HH:mm:ss | 使用最新详情的 updateTime |
| accountType | Body | String | 是 | CORPORATE / PERSONAL | 对公 / 对私 |
| bankName | Body | String | 是 | 最长 500 字符 | 开户银行 |
| accountNo | Body | String | 是 | 去空白/连字符后 8–32 位数字 | 收款账号 |
| accountPeriod | Body | 已删除 | 否 | 不再提交 | 删除账期输入 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data | Object | 原有写入/审批结果；初始账户摘要原本就没有账期 |

#### 请求示例

```http
PUT https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/update
Authorization: Bearer <当前有效登录会话>
Content-Type: application/json

{
  "accountType": "CORPORATE",
  "bankName": "测试银行",
  "accountNo": "7318123456789012",
  "expectedUpdateTime": "2026-09-08 17:00:00"
}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"accountId":"731802","approvalLogId":"731803","requestNo":"supplier-example-7318","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中","accountStatus":"ACTIVE","isDefault":"NO"}}
```

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

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

#### 错误响应

```json
{"code":400,"message":"开户银行不能为空","data":null}
```

#### 业务边界

- 沿用既有账户状态和权限限制；删除账期不跳过审批。

### 6. 账户列表 `GET /admin/supplier/items/{supplierId}/account-info/list`

**VO**: `SupplierAccountInfoRespVO`

#### 使用场景

供应商管理页面账户列表。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| supplierId | Path | String | 是 | 正整数 ID | 当前记录 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data.bankAccounts[].accountPeriod | 已删除 | 字段不再返回，删除页面账期展示 |

#### 请求示例

```http
GET https://api.test.1814.love:9443/admin/supplier/items/731801/account-info/list
Authorization: Bearer <当前有效登录会话>

无请求体
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"731801","bankAccounts":[{"accountId":"731802","accountName":"测试供应商7318","accountType":"CORPORATE","bankName":"测试银行","accountNo":"7318123456789012","bankBranch":null,"accountNoMask":"7318123456789012","status":"ACTIVE","isDefault":"YES","updateTime":"2026-09-08 17:00:00"}],"updateTime":"2026-09-08 17:00:00"}}
```

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

无账户时 bankAccounts=[]；不会补回 accountPeriod。

#### 错误响应

```json
{"code":395001,"message":"供应商不存在","data":null}
```

#### 业务边界

- 只移除当前账户展示的账期，历史审批记录继续按原语义展示。

### 7. 账户详情 `GET /admin/supplier/bank-accounts/{accountId}/view`

**VO**: `SupplierBankAccountDetailRespVO`

#### 使用场景

供应商管理页面账户详情。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| accountId | Path | String | 是 | 正整数 ID | 当前记录 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data.accountPeriod | 已删除 | 字段不再返回，删除页面账期展示 |

#### 请求示例

```http
GET https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/view
Authorization: Bearer <当前有效登录会话>

无请求体
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"accountId":"731802","accountName":"测试供应商7318","accountType":"CORPORATE","bankName":"测试银行","accountNo":"7318123456789012","bankBranch":null,"accountNoMask":"7318123456789012","status":"ACTIVE","isDefault":"YES","updateTime":"2026-09-08 17:00:00"}}
```

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

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

#### 错误响应

```json
{"code":395001,"message":"供应商不存在","data":null}
```

#### 业务边界

- 只移除当前账户展示的账期，历史审批记录继续按原语义展示。

### 8. 设置默认账户 `PUT /admin/supplier/bank-accounts/{accountId}/default/update`

**VO**: `SupplierBankAccountRespVO`

#### 使用场景

供应商管理页面设置默认账户。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| accountId | Path | String | 是 | 正整数 ID | 当前记录 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| code / message | Number / String | 检查业务结果；成功 code=200 |
| data.accountPeriod | 已删除 | 字段不再返回，删除页面账期展示 |

#### 请求示例

```http
PUT https://api.test.1814.love:9443/admin/supplier/bank-accounts/731802/default/update
Authorization: Bearer <当前有效登录会话>

无请求体
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"accountId":"731802","accountName":"测试供应商7318","accountType":"CORPORATE","bankName":"测试银行","accountNo":"7318123456789012","bankBranch":null,"accountNoMask":"7318123456789012","status":"ACTIVE","isDefault":"YES","updateTime":"2026-09-08 17:00:00"}}
```

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

不存在的记录按原有业务错误返回；不会使用空成功结果兜底。

#### 错误响应

```json
{"code":395001,"message":"供应商不存在","data":null}
```

#### 业务边界

- 仅支持有效供应商的 ACTIVE 账户；无请求体，响应使用 status。

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

移除 accountPeriod 的表单、请求拼装及列表/详情绑定。旧请求多传该字段会被忽略，不再写入。证照图片上传成功后使用 imageUrl；新增项和完整请求必填，qualifications 数组须传完整保留集合，未包含的既有项会被删除；只有项内 imageUrl 省略/null 才保留原图，显式空白拒绝。

## 五、数据库行为

历史账期与审批记录保留；本次失败的图片校验不保存业务变更。

## 六、边界行为

不新增错误码。缺图沿用 HTTP 200、code=400、message=证照图片不能为空；不能仅凭 HTTP 状态判断成功。

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

| 字段 | 修改前 | 修改后 |
|---|---|---|
| accountPeriod | 可输入、返回 | 当前账户契约移除 |
| imageUrl | 可空 | 新增/完整请求必填；增量已有项可保留原图 |

## 六.7、影响评估

管理端需要删除账期控件和展示，并增加图片必填校验。

## 七、不影响范围

账户审批、默认账户条件、权限和历史记录沿用既有契约。

## 八、测试环境已验证

真实 TEST API 已验证：新增供应商及更新账户不保存账期，账户列表/详情不返回账期；新增、修改、提交的缺图及控制字符输入均被拒绝；有效图片可更新，既有图片省略/null 可保留。失败请求无业务写入，测试草稿已清理。独立账户审批和默认设置沿用既有流程，本次未发起新企微审批。

## 十、相关文档

[工单 #7318](https://git.1814.love:8443/wx/HL/issues/7318)、[补充工单 #7350](https://git.1814.love:8443/wx/HL/issues/7350)、[PR #7349](https://git.1814.love:8443/wx/HL/pulls/7349)、[PR #7351](https://git.1814.love:8443/wx/HL/pulls/7351)。

## 关联 / 联系人

### 联系人

- **后端负责人**: @lc
- **当前状态**：前端待适配。