---
schema: "hl-changelog/v2"
ticket: "7681"
title: "收付方式字典统一为「账户类型+渠道」两维口径（方案甲）"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "7ed122cb"
target_release: ""
verified_at: "2026-09-14"
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。前端所有收付方式/还款方式下拉与展示需按新口径适配。 前端已交付(mmg)：收付方式兜底新三码值+支付渠道仅三方条件必填+nonbiz 组合展示+repayWay BANK；commit 7ed122cb。"
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）