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

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7291	供应商与结算信息移除历史字段	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	41f0bacc		2026-09-08	前端已交付并验证(commit 41f0bacc):供应商 balance/paymentType 与结算账户 settleMode/invoiceType/taxRate 五字段表单/请求组装/展示/字典/校验全量清零;accountPeriod 保留并解除 settleMode==='MONTHLY' 耦合(三弹窗无条件渲染、去空白非空即携带);isValidTaxRate 删,core/accounts JSDoc 改新口径;supplier 域 168/168 绿,checkpoint 全绿(含生产构建)。	2026-09-08	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	创建结果保持不变

请求示例

{
  "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天"}]
}

响应示例

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

空数据 / 降级响应

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

错误响应

{"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	审批结果保持不变

请求示例

{
  "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"
}

响应示例

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

空数据 / 降级响应

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

错误响应

{"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	修改结果保持不变

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

{"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

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

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

业务边界

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

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

VO: SupplierListReqVO / List<SupplierListItemRespVO>

使用场景

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

入参

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

出参

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

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

{"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；其他字段不变

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

{"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	账户提交与审批结果保持不变

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

{"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	修改审批结果保持不变

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

{"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

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

{"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

请求示例

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

响应示例

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

空数据 / 降级响应

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

错误响应

{"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，PR #7299
• 补充 Issue #7301，PR #7302
• 最终部署提交 35830856adb99f14186b50a646a6caaae142efec

关联 / 联系人

链接

• Issue: #7291
• PR: #7299
• 补充 PR: #7302

联系人

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