diff --git a/changelogs-v2/2026-09/14_7681_收付方式字典统一两维口径-修改接口-管理后台.md b/changelogs-v2/2026-09/14_7681_收付方式字典统一两维口径-修改接口-管理后台.md new file mode 100644 index 00000000..3ef3beee --- /dev/null +++ b/changelogs-v2/2026-09/14_7681_收付方式字典统一两维口径-修改接口-管理后台.md @@ -0,0 +1,223 @@ +--- +schema: "hl-changelog/v2" +ticket: "7681" +title: "收付方式字典统一为「账户类型+渠道」两维口径(方案甲)" +consumer: "admin" +author: "yst(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "收付方式码值收口: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。前端所有收付方式/还款方式下拉与展示需按新口径适配。" +updated_at: "2026-09-14" +base: "dev-v3" +--- + +# 收付方式字典统一为「账户类型+渠道」两维口径(修改接口) + +> **服务**: hl-order-service-v3(hl-finance 模块)+ hl-user-service(fin_pay_way 字典) +> **PR**: [#7685](https://git.1814.love:8443/wx/HL/pulls/7685) +> **Issue**: [#7681](https://git.1814.love:8443/wx/HL/issues/7681)(Epic [#7680](https://git.1814.love:8443/wx/HL/issues/7680)) +> **commit**: [e953e2883e](https://git.1814.love:8443/wx/HL/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 + 渠道) + +```http +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 }`,详情回读: + +```json +{ "payMethod": "THIRD_PARTY", "payMethodName": "三方支付", + "payChannel": "WXPAY", "payChannelName": "微信" } +``` + +### 7.2 典型:银行转账确认收款(无渠道) + +```http +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 + +```http +POST /admin/finance/cashier/confirm-in +{ "bizId": ..., "payAccountId": ..., "payMethod": "THIRD_PARTY", "payDate": "2026-09-14" } +``` + +```json +{ "code": 598608, "message": "收付方式与收付渠道不匹配(THIRD_PARTY 须传渠道 WXPAY/ALIPAY,其余方式不得传渠道)", "success": false } +``` + +### 7.4 异常:BANK 误传渠道 → 598608 + +```http +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](https://git.1814.love:8443/wx/HL/issues/7680) +- Issue: [#7681](https://git.1814.love:8443/wx/HL/issues/7681) +- PR: [#7685](https://git.1814.love:8443/wx/HL/pulls/7685) · commit [e953e2883e](https://git.1814.love:8443/wx/HL/commit/e953e2883e) +- 负责人: 腰苏图(yst)