diff --git a/changelogs-v2/2026-09/07_7291_供应商与结算信息移除历史字段-修改接口-管理后台.md b/changelogs-v2/2026-09/07_7291_供应商与结算信息移除历史字段-修改接口-管理后台.md new file mode 100644 index 00000000..8fe4b467 --- /dev/null +++ b/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` + +#### 使用场景 + +分页展示供应商列表。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `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` + +#### 使用场景 + +在选择器等有界场景读取供应商列表。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `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` + +#### 使用场景 + +为符合既有状态条件的供应商批量提交新收款账户。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `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 +- **当前状态**: 待前端处理