wx/hl-api-changelog

派生 0

文件

T

yaosutu 559e3da634

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): 收付方式字典统一两维口径前端 changelog (Issue #7681 / PR #7685 )

2026-09-14 15:50:32 +08:00

10 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	7681	收付方式字典统一为「账户类型+渠道」两维口径（方案甲）	admin	yst(GIT)	修改接口	deployed	verified	required					收付方式码值收口：fin_pay_way 字典值 BANK_TRANSFER/WECHAT/ALIPAY → CASH/BANK/THIRD_PARTY；新增 pay_channel 渠道维度（WXPAY/ALIPAY，仅 THIRD_PARTY 时有值）；员工借款 repay_way TRANSFER→BANK；出纳 confirm-in/pay 入参加 payChannel，nonbiz 出入参加 payChannel/payChannelName；新增错误码 598608。前端所有收付方式/还款方式下拉与展示需按新口径适配。	2026-09-14	dev-v3

收付方式字典统一为「账户类型+渠道」两维口径（修改接口）

服务: hl-order-service-v3（hl-finance 模块）+ hl-user-service（fin_pay_way 字典） PR: #7685 Issue: #7681（Epic #7680） commit: e953e2883e 日期: 2026-09-14 影响范围: 财务域所有「收付方式」「还款方式」下拉的码值口径 + 出纳/nonbiz 出入参新增渠道字段 + 新增 1 错误码；不涉及路由变化

⚠️ 关键变化

🔴 收付方式码值变了（前端下拉/回显/传参全要改）：

维度	旧值	新值
`payMethod`（类型）	`CASH` / `BANK_TRANSFER` / `WECHAT` / `ALIPAY`	`CASH` / `BANK` / `THIRD_PARTY`
`payChannel`（渠道，新增字段）	无	`WXPAY` / `ALIPAY`（仅 payMethod=THIRD_PARTY 时传/显）
员工借款 `repayWay`	`CASH` / `TRANSFER` / `EXPENSE_OFFSET`	`CASH` / `BANK` / `EXPENSE_OFFSET`

🟢 映射关系（前端迁移参照）：

旧	新
`CASH`	`CASH`（不变）
`BANK_TRANSFER`	`BANK`
`WECHAT`	`THIRD_PARTY` + `payChannel=WXPAY`
`ALIPAY`	`THIRD_PARTY` + `payChannel=ALIPAY`
`TRANSFER`（repayWay）	`BANK`

🟢 存量数据后端已自动翻写，历史单据读出即为新值，前端无需处理存量。

一、背景

财务域收付方式此前 6 套码值并存、5 套同名不同义（如 BANK_TRANSFER 在 fin_pay_way、TRANSFER 在员工借款还款、客户侧收款又一套），口径混乱。本次把真落库的收付方式统一为「账户类型 + 渠道」两维，与资金账户 fin_fund_account.account_type/channel 对齐：

类型（pay_method）：CASH 现金 / BANK 银行转账 / THIRD_PARTY 三方支付
渠道（pay_channel）：WXPAY 微信 / ALIPAY 支付宝，仅三方支付时有值

范围仅限业务外收支（fin_nonbiz_flow）与员工借款还款（fin_staff_loan_repay）；费用报销/应付款/预付款本无收付方式列不动；订单客户侧收款是另一套业务口径，不动。

二、变更清单

项	变更
fin_pay_way 字典	值 BANK_TRANSFER/WECHAT/ALIPAY → INACTIVE 留痕；新增 BANK/THIRD_PARTY；CASH 保留
出纳确认收款 `POST /admin/finance/cashier/confirm-in`	入参新增 `payChannel`；payMethod 值域改新三值
出纳登记付款 `POST /admin/finance/cashier/pay`	入参新增 `payChannel`；payMethod 值域改新三值
nonbiz 列表 `GET /admin/finance/nonbiz-flows/page`	行出参新增 `payChannel`/`payChannelName`；payMethod 值改新三值
nonbiz 详情 `GET /admin/finance/nonbiz-flows/{id}`	出参新增 `payChannel`/`payChannelName`；payMethod 值改新三值
员工借款还款 repayWay	值 TRANSFER→BANK（入参/出参/回显同步）
错误码	新增 598608

三、接口详情与入参

3.1 出纳确认收款（IN）

方法/路径：POST /admin/finance/cashier/confirm-in
说明：业务外收入批准（APPROVED）后，出纳确认收款并记资金流水

字段	类型	必填	说明
`bizId`	long	✅	业务单据ID（direction=IN 且 status=APPROVED）
`payAccountId`	long	✅	入账公司账户ID（fin_fund_account，须 ACTIVE），JSON 传 number
`payMethod`	string	否	收付方式：`CASH`/`BANK`/`THIRD_PARTY`（fin_pay_way 码值，新口径）
`payChannel`	string	条件	收付渠道：`WXPAY`/`ALIPAY`；payMethod=THIRD_PARTY 时必填，其余方式不得传（否则 598608），≤20
`voucherNo`	string	否	收款凭证号
`voucherUrl`	string	否	收款凭证影像 URL
`payDate`	string	✅	收款日期 `yyyy-MM-dd`

3.2 出纳登记付款（OUT）

方法/路径：POST /admin/finance/cashier/pay
入参在原有基础上同样新增 payChannel（规则同 3.1）；payMethod 值域改新三值。NONBIZ 分支落 fin_nonbiz_flow.pay_method/pay_channel。

四、出参

nonbiz 列表行 / 详情（新增 2 字段）

字段	类型	说明
`payMethod`	string	收付方式码值（新三值），PAID 后由出纳回写，草稿/待审批态为 null
`payMethodName`	string	收付方式中文名（现金/银行转账/三方支付），字典回显
`payChannel`	string	新增：收付渠道码值（WXPAY/ALIPAY），仅 THIRD_PARTY 有值，否则 null
`payChannelName`	string	新增：收付渠道中文名（微信/支付宝），仅 THIRD_PARTY 有值，否则 null

建议前端展示：payChannelName 非空时显示「三方支付·微信」式组合（payMethodName + payChannelName），否则显示 payMethodName。

员工借款还款（repayWay）

出参 repayWay/repayWayName：CASH 现金 / BANK 银行转账 / EXPENSE_OFFSET 报销冲销（TRANSFER 已更名 BANK，label「转账」→「银行转账」）。

五、枚举 / 数据字典

fin_pay_way（dict_type_id=10157）新口径

dict_value	dict_label	status
`CASH`	现金	ACTIVE
`BANK`	银行转账	ACTIVE
`THIRD_PARTY`	三方支付	ACTIVE
~~`BANK_TRANSFER`~~	银行转账	INACTIVE（留痕）
~~`WECHAT`~~	微信	INACTIVE（留痕）
~~`ALIPAY`~~	支付宝	INACTIVE（留痕）

三方渠道 WXPAY/ALIPAY 不再进 fin_pay_way 字典，由业务表 pay_channel 列承载（口径同 fin_fund_account_channel）。

repay_way（员工借款还款，Java 枚举）

CASH / BANK / EXPENSE_OFFSET（TRANSFER 已更名 BANK）。

六、错误码

码	含义	触发
598608	收付方式与收付渠道不匹配	payMethod=THIRD_PARTY 未传 payChannel（或 payChannel 非 WXPAY/ALIPAY）；或 payMethod 为 CASH/BANK/空却传了 payChannel

（其余既有错误码不变）

七、示例

7.1 典型：三方支付确认收款（THIRD_PARTY + 渠道）

POST /admin/finance/cashier/confirm-in
Content-Type: application/json

{ "bizId": 2099401839253278722, "payAccountId": 2095340438738046,
  "payMethod": "THIRD_PARTY", "payChannel": "WXPAY", "payDate": "2026-09-14" }

响应：{ "code": 200, "message": "成功", "data": {...}, "success": true }，详情回读：

{ "payMethod": "THIRD_PARTY", "payMethodName": "三方支付",
  "payChannel": "WXPAY", "payChannelName": "微信" }

7.2 典型：银行转账确认收款（无渠道）

POST /admin/finance/cashier/confirm-in
{ "bizId": 2099401839253278722, "payAccountId": 2095340438738046977,
  "payMethod": "BANK", "payDate": "2026-09-14" }

响应 200，详情：{ "payMethod": "BANK", "payMethodName": "银行转账", "payChannel": null, "payChannelName": null }

7.3 异常：THIRD_PARTY 缺渠道 → 598608

POST /admin/finance/cashier/confirm-in
{ "bizId": ..., "payAccountId": ..., "payMethod": "THIRD_PARTY", "payDate": "2026-09-14" }

{ "code": 598608, "message": "收付方式与收付渠道不匹配（THIRD_PARTY 须传渠道 WXPAY/ALIPAY，其余方式不得传渠道）", "success": false }

7.4 异常：BANK 误传渠道 → 598608

POST /admin/finance/cashier/confirm-in
{ "bizId": ..., "payAccountId": ..., "payMethod": "BANK", "payChannel": "WXPAY", "payDate": "2026-09-14" }

返回同上 598608。

八、业务边界

payChannel 仅当 payMethod=THIRD_PARTY 时有意义；其余方式传了报 598608。
收付方式/渠道只由出纳确认收/付采集回写，建单/编辑不采集（草稿态出参恒 null）。
还款方式 EXPENSE_OFFSET（报销冲销）由报销域内部生成，外部登记还款仅可传 CASH/BANK。

九、修改前后对比

维度	修改前	修改后
收付方式码值	CASH/BANK_TRANSFER/WECHAT/ALIPAY（4 值）	CASH/BANK/THIRD_PARTY（3 值）
渠道细分	混在 pay_method 里（WECHAT/ALIPAY）	独立 pay_channel 列（WXPAY/ALIPAY）
还款方式	CASH/TRANSFER/EXPENSE_OFFSET	CASH/BANK/EXPENSE_OFFSET
账户口径对齐	不一致	与 fin_fund_account.account_type/channel 对齐

十、影响评估 / 回滚

影响：前端所有用到 fin_pay_way 收付方式、员工借款 repayWay 的下拉/回显/传参需按新码值适配；三方支付场景需补渠道选择与展示。
存量：后端已自动翻写（WECHAT/ALIPAY→THIRD_PARTY+pay_channel，BANK_TRANSFER/TRANSFER→BANK），历史数据读出即新值。
字典：旧值 INACTIVE 留痕未删，紧急可回置 ACTIVE（但数据已翻写，回滚需配套）。
骑缝态：前后端须同步上线，老前端传 BANK_TRANSFER/WECHAT 会被当作无效/忽略。

十一、注意事项

Long 字段（bizId/payAccountId 等）JSON 传 number，勿加引号；出参 Long 已序列化为 string。
拉取 fin_pay_way 字典下拉的接口，返回值已自动为新三值（旧值 INACTIVE 不下发）。

十二、关联 / 联系人

Epic: #7680
Issue: #7681
PR: #7685 · commit e953e2883e
负责人: 腰苏图（yst）

10 KiB 原始文件 Blame 文件历史 Unescape Escape