wx/hl-api-changelog

派生 0

文件

T

lc a7a3a0bb3e

changelog-filename-gate / validate (push) Successful in 2s

详情

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

2026-09-07 22:52:09 +08:00

20 KiB

原始文件 Blame 文件历史

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	pending				2026-09-07	后端已部署 TEST 并经 Gateway 验证；前端需移除相关表单、请求和展示字段。当前状态：待前端处理。	2026-09-07	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
当前状态: 待前端处理

20 KiB 原始文件 Blame 文件历史

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

一、关键变化

二、变更接口清单

三、接口详情

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

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

20 KiB

原始文件 Blame 文件历史

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`

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

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

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`