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

2026-09-14 15:50:32 +08:00
@@ -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）