From 48d36a1c84d2670b8fce949cead0234e158e1238 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Sun, 13 Sep 2026 10:04:58 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=B5=84=E9=87=91=E8=B4=A6?=
 =?UTF-8?q?=E6=88=B7=E6=96=B0=E5=BB=BA/=E7=BC=96=E8=BE=91=E8=A1=A8?=
 =?UTF-8?q?=E5=8D=95=E5=AD=97=E6=AE=B5=E5=AF=B9=E6=8E=A5=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=EF=BC=88=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0=20v2=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

非接口改动：资金账户接口字段早已齐全，前端补 5 字段（bankName/shortName/nature/feeRate/refundReserve）+ scopeCompanies 改多选。
---
 ...�新建编辑表单字段对接说明-修改接口-管理后台.md | 174 ++++++++++++++++++
 1 file changed, 174 insertions(+)
 create mode 100644 changelogs-v2/2026-09/13_7520_资金账户新建编辑表单字段对接说明-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-09/13_7520_资金账户新建编辑表单字段对接说明-修改接口-管理后台.md b/changelogs-v2/2026-09/13_7520_资金账户新建编辑表单字段对接说明-修改接口-管理后台.md
new file mode 100644
index 00000000..ef7bbe1c
--- /dev/null
+++ b/changelogs-v2/2026-09/13_7520_资金账户新建编辑表单字段对接说明-修改接口-管理后台.md
@@ -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（腰苏图）