docs(changelog): publish supplier field removal (#7291)

changelogs-v2/2026-09/07_7291_供应商与结算信息移除历史字段-修改接口-管理后台.md

@@ -0,0 +1,616 @@
+---
+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
+- **当前状态**: 待前端处理