---
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: "49359412"
target_release: ""
verified_at: "2026-09-09"
status_note: "后端已合 dev-v3（#7003 account 域 + #7146 三字段字典化）并部署测试服；网关实测 E2E 通过。账户类型不可改、基本户唯一不可停用/改性质、有流水仅可停用。"
updated_at: "2026-09-09"
base: "dev-v3"
---

# 资金账户

## 1. 接口背景
财务域「资金账户」：公司收付款的资金账户（银行户/现金户/第三方支付户/内部虚拟户）全生命周期管理——建档、编辑、停用、删除、盘盈盘亏、期初结存调整、结存统计、下拉选项。属 Epic 财务域 account 资金账户域（#7003），并经 #7141 三字段字典化增强（type/nature/channel 中文标签 + 下拉）。

## 2. 变更清单
| 类型 | 接口 | 说明 |
|---|---|---|
| 新增 | GET `/admin/finance/fund-accounts/page` | 账户分页列表（类型/性质/状态/关键词筛选） |
| 新增 | GET `/admin/finance/fund-accounts/stats` | 结存统计（总计/按类型/退款预留预警） |
| 新增 | GET `/admin/finance/fund-accounts/options` | 三组下拉（类型/性质/渠道，字典化） |
| 新增 | POST `/admin/finance/fund-accounts` | 新建账户 |
| 新增 | GET `/admin/finance/fund-accounts/{id}` | 账户详情 |
| 新增 | PUT `/admin/finance/fund-accounts/{id}` | 编辑账户 |
| 新增 | POST `/admin/finance/fund-accounts/{id}/disable` | 停用账户 |
| 新增 | DELETE `/admin/finance/fund-accounts/{id}` | 删除账户（无流水才可删） |
| 新增 | POST `/admin/finance/fund-accounts/{id}/inventory-adjust` | 盘盈盘亏 |
| 新增 | POST `/admin/finance/fund-accounts/{id}/opening-adjust` | 期初结存调整 |

## 3. 接口详情

### 3.1 分页列表 GET /page
入参（Query + 分页）：`accountType`(BANK/CASH/THIRD_PARTY/INTERNAL_VIRTUAL) / `nature`(BASIC/GENERAL) / `status`(ACTIVE/DISABLED) / `keyword`(账号或账户名模糊) / pageNo / pageSize。

出参行（FundAccountRowRespVO，Long ID 均 String）：

| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 账户ID |
| accountName | String | 账户名称 |
| accountNo | String | 账号（展示层脱敏） |
| bankName | String | 开户行 |
| accountType | String | 账户类型（枚举大写） |
| accountTypeName | String | 账户类型中文名（字典 fin_fund_account_type 标签，字典不可用为 null） |
| nature | String | 账户性质（仅 BANK，其余 null） |
| natureName | String | 性质中文名（字典标签） |
| channel | String | 第三方渠道（仅 THIRD_PARTY，其余 null） |
| channelName | String | 渠道中文名（字典标签） |
| shortName | String | 账户简称 |
| displayName | String | 对外展示名（空则展示账户名称） |
| sortOrder | Integer | 排序（越小越靠前） |
| feeRate | BigDecimal | 手续费率（仅 THIRD_PARTY，如 0.006） |
| refundReserve | BigDecimal | 退款预留额度（仅 THIRD_PARTY） |
| openingBalance | BigDecimal | 期初结存 |
| balance | BigDecimal | 当前结存 |
| currency | String | 币种（默认 CNY） |
| scopeCompanies | String | 适用公司范围 |
| status | String | ACTIVE / DISABLED |

### 3.2 统计 GET /stats
出参：`totalBalance`（全部生效账户结存总计）/ `byType[]`（accountType + accountTypeName + accountCount + balance）/ `reserveWarnings[]`（余额低于 refundReserve 的三方户：accountId/accountName/当前结存）。

### 3.3 下拉 GET /options
出参三组：`accountTypes[]` / `natures[]` / `channels[]`，元素 `OptionItem{value, label, sortOrder}`（value=枚举大写名如 BANK/BASIC/WXPAY，label=中文，sortOrder 升序，仅 ACTIVE）。**账户性质仅 BANK 用、渠道仅 THIRD_PARTY 用**，前端按 accountType 联动展示。

### 3.4 新建 POST /
入参（FundAccountCreateReqVO）：

| 字段 | 必填 | 说明 |
|---|---|---|
| accountName | 是 | 账户名称（全称化口径） |
| accountNo | 是 | 账号（原值入库，展示脱敏） |
| bankName | 否 | 开户行 |
| accountType | 是 | BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL |
| nature | BANK 必填 | BASIC / GENERAL |
| channel | THIRD_PARTY 必填 | WXPAY / ALIPAY |
| settleAccountNo | 否 | 绑定结算卡（仅 THIRD_PARTY，原值入库展示脱敏） |
| refundReserve | 否 | 退款预留额度（仅 THIRD_PARTY，默认 0） |
| shortName | 否 | 账户简称 |
| displayName | 否 | 对外展示名（空则展示账户名称） |
| sortOrder | 否 | 排序（越小越靠前） |
| openingBalance | 否 | 期初结存（默认 0） |
| feeRate | 否 | 手续费率（仅 THIRD_PARTY，如 0.006） |
| overdraftAllowed | 否 | 是否允许透支（布尔） |
| payQrUrl | 否 | 收款码影像 URL（仅 CASH/THIRD_PARTY 收款场景） |
| remark | 否 | 备注 |

出参：`{id}`（新账户ID，String）。

### 3.5 详情 GET /{id}
出参 = Row 全字段 + `settleAccountNo`（结算卡脱敏）/ `overdraftAllowed` / `payQrUrl` / `remark` / `flows[]`（最近资金流水行）。

### 3.6 编辑 PUT /{id}
入参同新建（FundAccountUpdateReqVO，accountType 不可改；BASIC 基本户 nature 不可改成其他）。

### 3.7 停用 POST /{id}/disable
无入参。唯一基本户不允许停用（595005）；已停用重复停用幂等。

### 3.8 删除 DELETE /{id}
有流水账户不可删（595003），仅可停用。

### 3.9 盘盈盘亏 POST /{id}/inventory-adjust
入参：`direction`（SURPLUS 盘盈补收 / DEFICIT 盘亏补付，必填）/ `amount`（差额>0，必填）/ `reason`（原因，必填，进留痕）/ `voucherUrl`（佐证影像，选填）。

### 3.10 期初调整 POST /{id}/opening-adjust
入参：`newOpeningBalance`（新期初结存≥0，必填；调整后结存=新期初+历史流水净影响）/ `reason`（可空，缺省生成「期初调整 旧→新」）/ `voucherUrl`（选填）。

## 4. 枚举 / 数据字典
| 字段 | 取值 | 字典表 |
|---|---|---|
| accountType | BANK 银行 / CASH 现金 / THIRD_PARTY 第三方支付 / INTERNAL_VIRTUAL 内部虚拟户（预留） | fin_fund_account_type |
| nature | BASIC 基本户 / GENERAL 一般户（仅 BANK） | fin_fund_account_nature |
| channel | WXPAY 微信支付 / ALIPAY 支付宝（仅 THIRD_PARTY） | fin_fund_account_channel |
| status | ACTIVE 生效 / DISABLED 停用 | - |
| direction | SURPLUS 盘盈 / DEFICIT 盘亏 | - |

字典建在 user-service（部署顺序：先 user-service 后 order-v3）。**建议前端用 `/options` 拉下拉，channel 已彻底字典化（后续加渠道零发版）**。

## 5. 错误码（段位 595000-595099）
| 码 | 含义 |
|---|---|
| 595001 | 账户不存在 |
| 595002 | 基本户每公司唯一，已存在其他基本户 |
| 595003 | 有流水账户不可删除，仅可停用 |
| 595004 | 互转两方账户不能相同 |
| 595005 | 唯一基本户不允许停用 |
| 595006 | 账户已停用 |
| 595007 | 账户字段组合不合法（银行户必填账户性质，三方户必填渠道） |
| 595008 | 取现出账账户须为基本户 |
| 595009 | 存取方式无效 |
| 595010 | 存取方式与转出/转入账户类型不匹配 |

## 6. 示例
**新建银行基本户**
```
POST /admin/finance/fund-accounts
{"accountName":"呼伦贝尔XX公司基本户","accountNo":"150XXX","bankName":"中国银行","accountType":"BANK","nature":"BASIC"}
→ 200 {"id":"2097..."}
```
**三方户缺渠道（异常）**
```
POST /admin/finance/fund-accounts  {"accountName":"微信商户","accountNo":"...","accountType":"THIRD_PARTY"}
→ 595007 账户字段组合不合法
```
**删除有流水账户（异常）**
```
DELETE /admin/finance/fund-accounts/{id}  → 595003 有流水账户不可删除，仅可停用
```
**盘盈**
```
POST /admin/finance/fund-accounts/{id}/inventory-adjust
{"direction":"SURPLUS","amount":100.00,"reason":"盘点溢余"}
→ 200
```

## 7. 注意事项
- 账号/结算卡**原值入库、展示层脱敏**，出参 accountNo 为脱敏值。
- 全部长整型 ID 序列化为字符串。
- 账户类型不可改；基本户唯一且不可停用/不可改性质。
- 删除仅限无流水账户，有流水走停用。

## 8. 关联 / 联系人
- Issue：https://git.1814.love:8443/wx/HL/issues/7003 ｜ 字典化增强 #7141（PR https://git.1814.love:8443/wx/HL/pulls/7146）
- Commit：https://git.1814.love:8443/wx/HL/commit/b46269a4d4
- 负责人：腰苏图（yst）