hl-api-changelog/changelogs-v2/2026-09/09_7003_收款账户-新增接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

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