---
schema: "hl-changelog/v2"
ticket: "7291"
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-07"
status_note: "后端已部署 TEST 并经 Gateway 验证；前端需移除相关表单、请求和展示字段。当前状态：待前端处理。"
updated_at: "2026-09-07"
base: "dev-v3"
---

# 供应商与结算信息：移除历史字段

## 一、关键变化

- 供应商新建、提交、修改不再要求或写入 `balance`、`paymentType`；供应商列表和详情不再返回这两个字段。
- 结算信息新建、修改不再要求或写入 `settleMode`、`invoiceType`、`taxRate`；结算列表和详情不再返回这三个字段。
- `accountPeriod` 保留。数据库历史列与存量值不删除，但不再通过当前公开接口读写。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---:|---|---|---|---|---|
| 1 | 新建供应商草稿 | POST | `/admin/supplier/items/add` | 请求字段删除 | 删除供应商两字段及初始账户三字段 |
| 2 | 提交供应商审批 | POST | `/admin/supplier/items/{supplierId}/submit` | 请求字段删除 | 删除供应商两字段及初始账户三字段 |
| 3 | 修改供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 请求字段删除 | 删除供应商两字段及初始账户三字段 |
| 4 | 供应商分页查询 | GET | `/admin/supplier/items/page` | 响应字段删除 | 不返回 `balance`、`paymentType` |
| 5 | 供应商有界查询 | GET | `/admin/supplier/items/list` | 响应字段删除 | 不返回 `balance`、`paymentType` |
| 6 | 供应商详情 | GET | `/admin/supplier/items/{supplierId}/basic-info/view` | 响应字段删除 | 不返回 `balance`、`paymentType` |
| 7 | 新增收款账户 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | 请求字段删除 | 账户项删除三个结算字段 |
| 8 | 修改收款账户 | PUT | `/admin/supplier/bank-accounts/{accountId}/update` | 请求字段删除 | 删除三个结算字段 |
| 9 | 结算信息列表 | GET | `/admin/supplier/items/{supplierId}/account-info/list` | 响应字段删除 | 不返回三个结算字段 |
| 10 | 结算信息详情 | GET | `/admin/supplier/bank-accounts/{accountId}/view` | 响应字段删除 | 不返回三个结算字段 |

## 三、接口详情

### 1. 新建供应商草稿 `POST /admin/supplier/items/add`

**VO**: `SupplierDraftSaveReqVO / SupplierWriteRespVO`

#### 使用场景

新增供应商并保存一项初始收款账户。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `balance` / `paymentType` | Body | - | 否 | 不发送 | 已从供应商请求模型删除 |
| `initialAccounts[].settleMode` / `invoiceType` / `taxRate` | Body | - | 否 | 不发送 | 已从账户请求模型删除 |
| `initialAccounts[].accountPeriod` | Body | String | 否 | 最长 50 | 账期继续保留 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.supplierId` / `status` / `updateTime` | String | 创建结果保持不变 |

#### 请求示例

```json
{
  "fullName": "示例供应商有限公司",
  "taxNo": "HL7291EXAMPLE001",
  "types": [{"typeCode": "SCENIC"}],
  "legalRepresentative": "张三",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/id-front.png",
  "legalRepresentativeIdCardBackUrl": "https://files.example.com/id-back.png",
  "contactPhone": "13900000000",
  "establishDate": "2026-09-01",
  "mainCooperation": "旅游资源合作",
  "licenseImageUrl": "https://files.example.com/license.png",
  "address": "示例地址",
  "contacts": [{"contactName": "李四", "contactPhone": "13900000001", "contactRole": "contentBus", "isPrimary": true}],
  "initialAccounts": [{"accountType": "CORPORATE", "bankName": "示例银行", "accountNo": "6222000000000000", "accountPeriod": "月结30天"}]
}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"2097000000000000001","status":"DRAFT","updateTime":"2026-09-07 22:36:56"},"success":true}
```

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

省略五个已删除字段不会失败；其余现有必填字段仍按原契约校验。

#### 错误响应

```json
{"code":400,"message":"供应商全称不能为空","data":null,"success":false}
```

#### 业务边界

- 旧客户端多传已删除字段时兼容忽略，不写入数据库。

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

**VO**: `SupplierSubmitReqVO / SupplierApprovalCommandRespVO`

#### 使用场景

提交完整供应商表单进入既有审批流程。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID | 草稿供应商 |
| `balance` / `paymentType` | Body | - | 否 | 不发送 | 已删除 |
| `initialAccounts[].settleMode` / `invoiceType` / `taxRate` | Body | - | 否 | 不发送 | 已删除；`accountPeriod` 保留 |
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 并发版本保持不变 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.approvalLogId` / `approvalStatus` | String | 审批结果保持不变 |

#### 请求示例

```json
{
  "fullName": "示例供应商有限公司",
  "taxNo": "HL7291EXAMPLE001",
  "types": [{"typeCode": "SCENIC"}],
  "legalRepresentative": "张三",
  "legalRepresentativeIdNo": "11010519491231002X",
  "legalRepresentativeIdCardFrontUrl": "https://files.example.com/id-front.png",
  "legalRepresentativeIdCardBackUrl": "https://files.example.com/id-back.png",
  "contactPhone": "13900000000",
  "establishDate": "2026-09-01",
  "mainCooperation": "旅游资源合作",
  "licenseImageUrl": "https://files.example.com/license.png",
  "address": "示例地址",
  "contacts": [{"contactName": "李四", "contactPhone": "13900000001", "contactRole": "contentBus", "isPrimary": true}],
  "initialAccounts": [{"accountType": "CORPORATE", "bankName": "示例银行", "accountNo": "6222000000000000", "accountPeriod": "月结30天"}],
  "expectedUpdateTime": "2026-09-07 22:36:56"
}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"approvalLogId":"2097000000000000002","approvalStatus":"PENDING"},"success":true}
```

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

省略已删除字段不影响提交；完整表单、状态和版本要求不变。

#### 错误响应

```json
{"code":400,"message":"expectedUpdateTime不能为空","data":null,"success":false}
```

#### 业务边界

- 审批、幂等、状态与并发门禁没有变化。

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

**VO**: `SupplierUpdateReqVO / SupplierWriteRespVO`

#### 使用场景

增量修改供应商或草稿初始账户的保留字段。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID | 目标供应商 |
| `balance` / `paymentType` | Body | - | 否 | 不发送 | 外部请求不再绑定 |
| `initialAccounts[].settleMode` / `invoiceType` / `taxRate` | Body | - | 否 | 不发送 | 已删除；`accountPeriod` 保留 |
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 并发版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.supplierId` / `status` / `updateTime` | String | 修改结果保持不变 |

#### 请求示例

```json
{"shortName":"示例简称","initialAccounts":[{"accountType":"CORPORATE","bankName":"示例银行","accountNo":"6222000000000000","accountPeriod":"周结"}],"expectedUpdateTime":"2026-09-07 22:36:56"}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"2097000000000000001","status":"DRAFT","updateTime":"2026-09-07 22:37:52"},"success":true}
```

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

只传版本仍不是有效修改；至少提交一个当前可变更字段。

#### 错误响应

```json
{"code":400,"message":"除changeReason和expectedUpdateTime外，至少提交一个可变更字段","data":null,"success":false}
```

#### 业务边界

- 多传旧字段不会修改历史值；其他字段仍受既有状态、权限和版本约束。

### 4. 供应商分页查询 `GET /admin/supplier/items/page`

**VO**: `SupplierPageReqVO / PageResult<SupplierListItemRespVO>`

#### 使用场景

分页展示供应商列表。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `pageNo` / `pageSize` | Query | Integer | 是 | 沿用现有分页规则 | 查询条件不变 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.records[]` | Array | 不再含 `balance`、`paymentType` |

#### 请求示例

```http
GET /admin/supplier/items/page?pageNo=1&pageSize=10
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"records":[{"supplierId":"2097000000000000001","fullName":"示例供应商有限公司"}],"total":1,"page":1,"pageSize":10},"success":true}
```

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

没有匹配项时 `records=[]`，且不会补回已删除字段。

#### 错误响应

```json
{"code":401,"message":"未登录或登录已过期","data":null,"success":false}
```

#### 业务边界

- 前端删除列表类型和列配置中的两个旧字段。

### 5. 供应商有界查询 `GET /admin/supplier/items/list`

**VO**: `SupplierListReqVO / List<SupplierListItemRespVO>`

#### 使用场景

在选择器等有界场景读取供应商列表。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `limit` | Query | Integer | 否 | 沿用现有上限 | 查询条件不变 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data[]` | Array | 不再含 `balance`、`paymentType` |

#### 请求示例

```http
GET /admin/supplier/items/list?limit=50
```

#### 响应示例

```json
{"code":200,"message":"成功","data":[{"supplierId":"2097000000000000001","fullName":"示例供应商有限公司"}],"success":true}
```

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

没有匹配项时返回空数组。

#### 错误响应

```json
{"code":401,"message":"未登录或登录已过期","data":null,"success":false}
```

#### 业务边界

- 返回项与分页列表使用同一精简响应模型。

### 6. 供应商详情 `GET /admin/supplier/items/{supplierId}/basic-info/view`

**VO**: `SupplierBasicInfoRespVO`

#### 使用场景

打开供应商详情或编辑页时读取基本资料。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID | 目标供应商 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | Object | 不再含 `balance`、`paymentType`；其他字段不变 |

#### 请求示例

```http
GET /admin/supplier/items/2097000000000000001/basic-info/view
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"2097000000000000001","fullName":"示例供应商有限公司","status":"DRAFT","updateTime":"2026-09-07 22:37:52"},"success":true}
```

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

旧字段不会以 `null` 占位返回。

#### 错误响应

```json
{"code":401,"message":"未登录或登录已过期","data":null,"success":false}
```

#### 业务边界

- 前端不得继续依赖两个旧字段初始化表单或详情展示。

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

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

#### 使用场景

为符合既有状态条件的供应商批量提交新收款账户。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID | 所属供应商 |
| `accounts[].settleMode` / `invoiceType` / `taxRate` | Body | - | 否 | 不发送 | 已删除 |
| `accounts[].accountPeriod` | Body | String | 否 | 最长 50 | 账期保留 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data[]` | Array | 账户提交与审批结果保持不变 |

#### 请求示例

```json
{"accounts":[{"accountType":"CORPORATE","bankName":"示例银行","accountNo":"6222000000000000","accountPeriod":"月结30天"}]}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":[{"accountId":"2097000000000000003","approvalStatus":"PENDING"}],"success":true}
```

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

省略三个已删除字段不会失败；账户列表本身仍必须满足既有数量规则。

#### 错误响应

```json
{"code":400,"message":"收款账户列表不能为空","data":null,"success":false}
```

#### 业务边界

- 账户审批、状态、账号唯一性和幂等规则不变。

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

**VO**: `SupplierAccountUpdateReqVO / BankAccountSubmitResultRespVO`

#### 使用场景

按现有流程提交一份账户资料修改。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `accountId` | Path | String | 是 | 正整数 ID | 目标账户 |
| `settleMode` / `invoiceType` / `taxRate` | Body | - | 否 | 不发送 | 已删除 |
| `accountPeriod` | Body | String | 否 | 最长 50 | 账期保留 |
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 并发版本 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.accountId` / `approvalStatus` | String | 修改审批结果保持不变 |

#### 请求示例

```json
{"accountType":"CORPORATE","bankName":"示例银行","accountNo":"6222000000000000","accountPeriod":"周结","expectedUpdateTime":"2026-09-07 22:37:52"}
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"accountId":"2097000000000000003","approvalStatus":"PENDING"},"success":true}
```

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

省略三个已删除字段不会失败；完整账户资料和版本要求保持不变。

#### 错误响应

```json
{"code":400,"message":"expectedUpdateTime不能为空","data":null,"success":false}
```

#### 业务边界

- 多传三个旧字段时兼容忽略，不进入审批候选值。

### 9. 结算信息列表 `GET /admin/supplier/items/{supplierId}/account-info/list`

**VO**: `SupplierAccountInfoRespVO / SupplierBankAccountRespVO`

#### 使用场景

在供应商结算信息页读取账户列表。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID | 所属供应商 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.bankAccounts[]` | Array | 不再含 `settleMode`、`invoiceType`、`taxRate`；保留 `accountPeriod` |

#### 请求示例

```http
GET /admin/supplier/items/2097000000000000001/account-info/list
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"supplierId":"2097000000000000001","bankAccounts":[{"accountId":"2097000000000000003","accountType":"CORPORATE","bankName":"示例银行","accountPeriod":"周结"}]},"success":true}
```

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

无账户时 `bankAccounts=[]`，不会补回已删除字段。

#### 错误响应

```json
{"code":401,"message":"未登录或登录已过期","data":null,"success":false}
```

#### 业务边界

- 前端删除三字段的列表列、详情入口参数和类型声明。

### 10. 结算信息详情 `GET /admin/supplier/bank-accounts/{accountId}/view`

**VO**: `SupplierBankAccountDetailRespVO`

#### 使用场景

打开或编辑单个收款账户时读取完整账户资料。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| `accountId` | Path | String | 是 | 正整数 ID | 目标账户 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data` | Object | 不再含 `settleMode`、`invoiceType`、`taxRate`；保留 `accountPeriod` |

#### 请求示例

```http
GET /admin/supplier/bank-accounts/2097000000000000003/view
```

#### 响应示例

```json
{"code":200,"message":"成功","data":{"accountId":"2097000000000000003","accountType":"CORPORATE","bankName":"示例银行","accountPeriod":"周结","updateTime":"2026-09-07 22:37:52"},"success":true}
```

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

三个已删除字段不会以 `null` 占位返回。

#### 错误响应

```json
{"code":401,"message":"未登录或登录已过期","data":null,"success":false}
```

#### 业务边界

- 编辑表单只按当前响应字段初始化，保留 `accountPeriod`。

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

- 新建、提交和修改供应商时停止发送 `balance`、`paymentType`。
- 初始账户、批量新增账户和修改账户时停止发送 `settleMode`、`invoiceType`、`taxRate`。
- 查询消费方停止读取上述字段；`accountPeriod` 继续按原名读写。
- 旧请求多传已删除字段时后端兼容忽略；这不是继续使用旧字段的承诺。

## 五、数据库行为

| 外部行为 | 可观察结果 |
|---|---|
| 新建供应商或账户 | 已删除字段不再写入；其余合法字段正常保存 |
| 修改请求多传旧字段 | 旧字段不绑定、不覆盖历史值；其余合法修改正常保存 |
| 查询历史记录 | 响应也不暴露已删除字段 |

没有数据库迁移，历史列与存量值保留。

## 六、边界行为

- 没有新增错误码；省略已删除字段不再触发其旧必填、字典或组合校验。
- 业务失败仍可能使用 HTTP 200，必须判断响应体 `code`、`success` 和 `message`。
- 未认证请求仍返回业务码 `401`；权限、状态、审批、幂等和并发门禁不变。

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

| 字段 | 修改前 | 修改后 |
|---|---|---|
| `balance`、`paymentType` | 供应商表单可写，查询可回显 | 请求模型与查询响应移除 |
| `settleMode`、`invoiceType`、`taxRate` | 结算账户可写，查询可回显 | 请求模型与查询响应移除 |
| `accountPeriod` | 可写、可回显 | 保持不变 |

## 六.7、影响评估

- **是否破坏向后兼容**: 响应字段删除会影响仍读取旧字段的前端；旧请求多传字段暂时兼容忽略。
- **前端是否必须同步上线**: 是。
- **前端 workaround 清理点**: 删除五个字段的输入、校验、请求组装、展示映射、字典加载和类型声明。

## 七、不影响范围

- 仅影响管理端供应商资料与收款账户的上述请求和响应字段。
- 不改变账号、开户行、附件、默认账户、账期、权限、状态、审批、审计、软删除、Redis 或 MQ 规则。
- 不删除数据库历史列、存量值或字典数据。

## 八、测试环境已验证

- 省略已删除字段可成功新建和修改供应商及初始账户。
- 修改请求多传旧字段时不绑定、不落库，其他合法字段正常更新。
- 供应商列表/详情和结算列表/详情均不返回对应旧字段。
- 未认证请求被拒绝，业务失败零写入；合成验收数据已通过业务接口清理。

## 十、相关文档

- 主 Issue [#7291](https://git.1814.love:8443/wx/HL/issues/7291)，PR [#7299](https://git.1814.love:8443/wx/HL/pulls/7299)
- 补充 Issue [#7301](https://git.1814.love:8443/wx/HL/issues/7301)，PR [#7302](https://git.1814.love:8443/wx/HL/pulls/7302)
- 最终部署提交 [`35830856adb99f14186b50a646a6caaae142efec`](https://git.1814.love:8443/wx/HL/commit/35830856adb99f14186b50a646a6caaae142efec)

## 关联 / 联系人

### 链接

- **Issue**: [#7291](https://git.1814.love:8443/wx/HL/issues/7291)
- **PR**: [#7299](https://git.1814.love:8443/wx/HL/pulls/7299)
- **补充 PR**: [#7302](https://git.1814.love:8443/wx/HL/pulls/7302)

### 联系人

- **后端负责人**: @lc
- **当前状态**: 待前端处理