hl-api-changelog/changelogs-v2/2026-09/13_7520_资金账户新建编辑表单字段对接说明-修改接口-管理后台.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	7520	资金账户新建/编辑表单字段对接说明——后端字段早已齐全，前端补 5 字段 + 所属公司改多选（非接口改动）	admin	yst	修改接口	deployed	not_required	not_required					📘 字段对接说明（非接口改动）：资金账户新建/编辑接口出入参字段早已齐全，后端零改动。前端表单缺 5 字段（bankName/shortName/nature/feeRate/refundReserve）+ scopeCompanies 误作单选（后端实为多选）。前端按本文补做即可，无需后端配合。	2026-09-13	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 不允许	—

---

示例

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

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

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

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

成功响应

{ "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（腰苏图）