---
schema: "hl-changelog/v2"
ticket: "7003"
title: "收款账户（增改 + 设默认 + 停用）"
consumer: "admin"
author: "yst"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "21540997"
target_release: ""
verified_at: "2026-09-09"
status_note: "后端已合 dev-v3（account 资金账户域）并部署测试服。设默认/停用独立端点；设默认排他（同收款方其余自动降 0）。"
updated_at: "2026-09-09"
base: "dev-v3"
---

# 收款账户

## 1. 接口背景
财务域「收款账户」：各类收款方（司导/员工、车队、导游公司、供应商）的收款方式档案（微信/支付宝收款码、银行卡、对公账户）。供付款、报销等场景选择收款对象账户。

## 2. 变更清单
| 类型 | 接口 | 说明 |
|---|---|---|
| 新增 | GET `/admin/finance/payee-accounts/page` | 收款账户分页 |
| 新增 | POST `/admin/finance/payee-accounts` | 新增收款账户 |
| 新增 | PUT `/admin/finance/payee-accounts/{id}` | 编辑 |
| 新增 | POST `/admin/finance/payee-accounts/{id}/set-default` | 设为默认（排他） |
| 新增 | POST `/admin/finance/payee-accounts/{id}/disable` | 停用（软删） |

## 3. 接口详情

### 3.1 分页 GET /page
入参（Query + 分页，均可选）：`payeeType` / `payeeName`（模糊）/ `accountType` / pageNo / pageSize。

出参行（PayeeAccountRowRespVO，Long ID 序列化为 String）：

| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 账户ID |
| payeeType | String | 收款方类型 |
| payeeRefId | String | 收款方关联ID（弱关联快照，可空） |
| payeeName | String | 收款方名称 |
| accountType | String | 账户类型 |
| qrUrl | String | 收款码影像 URL |
| bankAccount | String | 银行账号（展示层脱敏） |
| bankName | String | 开户行 |
| isDefault | Integer | 0 否 / 1 是（同收款方默认唯一） |

### 3.2 新增 POST /
入参（PayeeAccountCreateReqVO）：

| 字段 | 必填 | 说明 |
|---|---|---|
| payeeType | 是 | STAFF / FLEET / GUIDE_CO / SUPPLIER |
| payeeRefId | 否 | 收款方关联ID（弱关联快照） |
| payeeName | 是 | 收款方名称（≤100） |
| accountType | 是 | WECHAT_QR / ALIPAY_QR / BANK_CARD / CORP_ACCOUNT |
| qrUrl | 否 | 收款码影像（≤500，收款码类用） |
| bankAccount | 银行卡/对公必填 | 银行账号（≤64；BANK_CARD/CORP_ACCOUNT 必填否则 595202） |
| bankName | 否 | 开户行（≤100） |
| isDefault | 否 | 默认 0；置 1 时同收款方原默认自动降 0 |

出参 `{id}`。

### 3.3 编辑 PUT /{id}
入参均可选：`payeeName` / `accountType` / `qrUrl` / `bankAccount` / `bankName`。

### 3.4 设默认 POST /{id}/set-default
本账户置默认（isDefault=1），**同收款方其余账户自动降为 0**（默认排他，先降后升）。

### 3.5 停用 POST /{id}/disable
软删该收款账户。

## 4. 枚举 / 数据字典
| 字段 | 取值 |
|---|---|
| payeeType | STAFF 司导/员工个人 / FLEET 车队 / GUIDE_CO 导游公司 / SUPPLIER 供应商（预留） |
| accountType | WECHAT_QR 微信收款码 / ALIPAY_QR 支付宝收款码 / BANK_CARD 银行卡 / CORP_ACCOUNT 对公账户 |
| isDefault | 0 否 / 1 是 |

## 5. 错误码（段位 595200-595299）
| 码 | 含义 |
|---|---|
| 595201 | 收款方账户不存在 |
| 595202 | 收款方账户字段组合不合法（银行卡/对公账户必填账号） |

## 6. 示例
**新增银行卡收款账户**
```
POST /admin/finance/payee-accounts
{"payeeType":"STAFF","payeeName":"张三","accountType":"BANK_CARD","bankAccount":"622XXX","bankName":"工商银行","isDefault":1}
→ 200 {"id":"2097..."}
```
**银行卡缺账号（异常）**
```
POST /admin/finance/payee-accounts  {"payeeType":"STAFF","payeeName":"张三","accountType":"BANK_CARD"}
→ 595202 收款方账户字段组合不合法
```
**设默认**
```
POST /admin/finance/payee-accounts/{id}/set-default  → 200（同收款方其余自动降 0）
```

## 7. 注意事项
- 同一收款方默认账户唯一；设默认会自动取消原默认。
- 银行卡/对公账户必须填 bankAccount；收款码类填 qrUrl。
- 银行账号原值入库、展示层脱敏。
- 长整型 ID 序列化为字符串。

## 8. 关联 / 联系人
- Issue：https://git.1814.love:8443/wx/HL/issues/7003
- Commit：https://git.1814.love:8443/wx/HL/commit/b46269a4d4
- 负责人：腰苏图（yst）