118 行
4.4 KiB
Markdown
118 行
4.4 KiB
Markdown
---
|
||
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）
|