docs(changelog): 资金账户新建/编辑表单字段对接说明（管理后台 v2）

非接口改动：资金账户接口字段早已齐全，前端补 5 字段（bankName/shortName/nature/feeRate/refundReserve）+ scopeCompanies 改多选。
2026-09-13 10:05:19 +08:00
@@ -0,0 +1,174 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7520"
+title: "资金账户新建/编辑表单字段对接说明——后端字段早已齐全，前端补 5 字段 + 所属公司改多选（非接口改动）"
+consumer: "admin"
+author: "yst"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "📘 字段对接说明（非接口改动）：资金账户新建/编辑接口出入参字段早已齐全，后端零改动。前端表单缺 5 字段（bankName/shortName/nature/feeRate/refundReserve）+ scopeCompanies 误作单选（后端实为多选）。前端按本文补做即可，无需后端配合。"
+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（腰苏图）