---
schema: "hl-changelog/v2"
ticket: "7520"
title: "资金账户新建/编辑表单字段对接说明——后端字段早已齐全，前端补 5 字段 + 所属公司改多选（非接口改动）"
consumer: "admin"
author: "yst"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "37454cb4"
target_release: ""
verified_at: "2026-09-13"
status_note: "📘 字段对接说明（非接口改动）：资金账户新建/编辑接口出入参字段早已齐全，后端零改动。前端表单缺 5 字段（bankName/shortName/nature/feeRate/refundReserve）+ scopeCompanies 误作单选（后端实为多选）。前端按本文补做即可，无需后端配合。 前端已交付：scopeCompanies 单选改多选+ALL 互斥（列表/详情按数组映射名称，agencyId 不数值化）；自述的 5 字段 grep 实证本已存在，实际缺口仅此一项。"
updated_at: "2026-09-13"
base: "dev-v3"
---

# 资金账户 新建/编辑表单 —— 字段对接说明

> **服务**: hl-order-service-v3（hl-finance 财务模块）
> **端**: 管理后台
> **类型**: 📘 字段对接说明（**非接口改动**，字段早已在出入参里，本文只讲"前端该补哪些"）
> **日期**: 2026-09-13
> **关联**: Epic #7520（员工借款域全链路）配套梳理

---

## 一句话结论

资金账户新建/编辑弹窗，后端接口字段**早已齐全、零改动**。前端当前少做了 **5 个字段**，并把 **所属公司误作单选**（后端是多选）。按下表补做即可，**无需后端配合**。

**涉及接口**：
- 新建 `POST /admin/finance/fund-accounts`
- 编辑 `PUT /admin/finance/fund-accounts/{id}`
- 详情 `GET /admin/finance/fund-accounts/{id}`

---

## ⚠️ 前端需补的 5 个字段（后端入参现有）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `bankName` | String(≤100) | 选填 | 开户行（如 工商银行海拉尔支行） |
| `shortName` | String(≤50) | 选填 | 账户简称（列表展示用，如 工行对公户） |
| `nature` | String | **仅 BANK 必填** | 账户性质：`BASIC` 基本户 / `GENERAL` 一般户 |
| `feeRate` | BigDecimal | 选填 | 默认手续费率（‰），≥0 |
| `refundReserve` | BigDecimal | 选填 | 退款预留额度（**仅 THIRD_PARTY 第三方支付**，默认 0） |

## ⚠️ 所属公司：单选 → 多选

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `scopeCompanies` | **List\<String\>** | ✅ | 所属公司**多选**（公司主体名列表）；`["ALL"]`=全公司通用，与指定公司**互斥** |

> 前端当前做成了单选下拉，应改为**多选**。传 `["ALL"]` 表示全公司通用（此时不能再传具体公司）。

---

## 完整入参（FundAccountCreateReqVO）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `accountName` | String(≤100) | ✅ | 账户名称（全称化口径，如 呼伦贝尔XX公司基本户） |
| `accountNo` | String(≤64) | ✅ | 账号（原值入库，展示层脱敏） |
| `accountType` | String | ✅ | `BANK` 银行 / `CASH` 现金 / `THIRD_PARTY` 第三方支付 / `INTERNAL_VIRTUAL` |
| `openingBalance` | BigDecimal | ✅ | 期初结存（起步余额，可 0） |
| `scopeCompanies` | List\<String\> | ✅ | 所属公司多选；`["ALL"]`=全公司通用 |
| `bankName` | String(≤100) | ❌ | 开户行 |
| `nature` | String | 仅 BANK 必填 | `BASIC` 基本户 / `GENERAL` 一般户 |
| `channel` | String | 仅 THIRD_PARTY 必填 | `WXPAY` 微信 / `ALIPAY` 支付宝 |
| `settleAccountNo` | String(≤64) | 仅 THIRD_PARTY | 绑定结算卡（展示层脱敏） |
| `refundReserve` | BigDecimal | ❌ | 退款预留额度（仅 THIRD_PARTY，默认 0） |
| `shortName` | String(≤50) | ❌ | 账户简称 |
| `displayName` | String(≤64) | ❌ | 对外展示名（对客/对单展示，空则展示账户名称） |
| `sortOrder` | Integer | ❌ | 排序（越小越靠前，缺省 0） |
| `feeRate` | BigDecimal | ❌ | 默认手续费率（‰） |
| `overdraftAllowed` | Integer | ❌ | 可否透支：1 允许 / 0 不允许（默认） |
| `payQrUrl` | String(≤500) | ❌ | 收款码图片 URL |
| `remark` | String(≤200) | ❌ | 备注 |

> **编辑** `PUT` 入参与新建基本一致，差异：`openingBalance` / `accountType` **不可改**；`nature` 对已是 BASIC 的账户**锁死**不可改。

---

## 出参（FundAccountDetailRespVO，详情）

入参字段全回显 + 额外：

| 字段 | 说明 |
|---|---|
| `id` | 账户 ID（Long 已转 String 防 JS 精度丢失） |
| `accountTypeName` / `natureName` / `channelName` | 类型/性质/渠道**中文名**（字典标签，展示直接用） |
| `balance` | 当前结存（只读，流水重算） |
| `currency` | 币种（CNY） |
| `status` | `ACTIVE` / `DISABLED` |
| `openingBalance` | 期初结存（读时派生：balance − ΣIN + ΣOUT + Σfee） |
| `flows` | 本账户资金流水分页（逐笔含 balanceAfter） |

> 出参 `accountNo` / `settleAccountNo` 为**脱敏后**值。

---

## 字典枚举（前端展示用中文名走后端字典标签字段）

| 字段 | 枚举值 | 中文字段 |
|---|---|---|
| `accountType` | `BANK` / `CASH` / `THIRD_PARTY` / `INTERNAL_VIRTUAL` | `accountTypeName` |
| `nature` | `BASIC` / `GENERAL` | `natureName` |
| `channel` | `WXPAY` / `ALIPAY` | `channelName` |
| `status` | `ACTIVE` / `DISABLED` | — |
| `overdraftAllowed` | `1` 允许 / `0` 不允许 | — |

---

## 示例

### 新建请求（银行-基本户-多公司）

```json
{
  "accountName": "呼伦贝尔呼籁国际旅行社有限公司基本户",
  "accountNo": "6222020200112233445",
  "accountType": "BANK",
  "bankName": "工商银行海拉尔支行",
  "nature": "BASIC",
  "shortName": "工行对公户",
  "displayName": "呼籁国际-基本户",
  "openingBalance": 100000.00,
  "feeRate": 0,
  "overdraftAllowed": 0,
  "scopeCompanies": ["内蒙古呼籁国际旅行社有限公司", "呼伦贝尔呼籁旅行社有限公司"],
  "remark": "主收单账户"
}
```

### 新建请求（第三方支付-全公司通用）

```json
{
  "accountName": "呼籁微信商户号",
  "accountNo": "1630001234",
  "accountType": "THIRD_PARTY",
  "channel": "WXPAY",
  "settleAccountNo": "6222020200998877665",
  "refundReserve": 5000.00,
  "openingBalance": 0,
  "scopeCompanies": ["ALL"]
}
```

### 成功响应

```json
{ "code": 200, "message": "success", "data": { "id": "2095340438490583041" }, "success": true }
```

---

## 注意事项

1. **后端零改动**：本文是字段对接说明，接口出入参早已就绪，前端按上表补做即可。
2. **基本户唯一口径**：后端当前是**全系统仅一个基本户**（`BASIC` 唯一约束），非"每公司一个"。若产品要求按公司各一个基本户，需另提需求改后端（本期按全系统一个）。
3. **退款预留**仅对 `THIRD_PARTY` 有业务含义，银行/现金户填了不生效，前端可按类型联动显隐。
4. **收款码** `payQrUrl` 存图片 URL，尺寸 200*200 / ≤2M 由前端 + 文件上传服务控制，后端不校验尺寸/大小。
5. HTTP 恒 200，判 `code`；业务失败按 `message` 原样提示即可（不二次包装）。

---

## 关联

- 服务：hl-order-service-v3（hl-finance 财务模块）
- 联系人：yst（腰苏图）