docs(finance): 资金账户 overdraftAllowed 前端纠错——禁传布尔须传整数 1/0

后端契约零变更，仅前端对接说明：新建/编辑资金账户的 overdraftAllowed 为 Integer，
前端开关直传 true/false 会被 Jackson 反序列化拦截报「字段 [overdraftAllowed] 格式错误」，
提交前须规整为 1/0。附正反例 JSON + 回显判真建议。

changelogs-v2/2026-09/15_fund-account_可否透支overdraftAllowed禁传布尔须传1或0-修改接口-管理后台.md

@@ -0,0 +1,127 @@
+---
+schema: "hl-changelog/v2"
+ticket: "frontend-finance-fund-account-overdraft"
+title: "资金账户 overdraftAllowed 禁传布尔，须传整数 1/0（前端对接纠错）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-15"
+status_note: "后端契约零变更，仅前端对接纠错：新建/编辑资金账户接口的 overdraftAllowed 字段是 Integer（1 允许 / 0 不允许），不是布尔。前端开关组件若直接提交 true/false，会被 Jackson 在反序列化阶段拦截，报「请求数据格式错误：字段 [overdraftAllowed] 格式错误」（HTTP 200 + code 400）。提交前须把开关值规整为 1/0 整数。"
+updated_at: "2026-09-15"
+base: "dev-v3"
+---
+
+# 资金账户 overdraftAllowed 禁传布尔，须传整数 1/0（前端对接纠错）
+
+> **服务**: hl-order-service-v3（hl-finance 模块）
+> **类型**: ⚠️ 前端对接纠错说明（后端契约**无任何变更**，无需发版）
+> **日期**: 2026-09-15
+> **影响范围**: 新建资金账户 + 编辑资金账户两个接口的 `overdraftAllowed` 字段提交格式
+
+---
+
+## 🔴 一句话给前端
+
+**`overdraftAllowed` 是整数 `Integer`，只收 `1` 或 `0`，不是布尔。**
+
+| 开关状态 | ❌ 错误传法（会 400） | ✅ 正确传法 |
+|---|---|---|
+| 允许透支（开） | `"overdraftAllowed": true` | `"overdraftAllowed": 1` |
+| 不允许透支（关） | `"overdraftAllowed": false` | `"overdraftAllowed": 0` |
+
+**提交前把开关组件的布尔值转一次：`true→1` / `false→0`。** 不要直接把 `el-switch` / checkbox 的 `true/false` 原样塞进请求体。
+
+---
+
+## 一、背景（为什么报「格式错误」）
+
+有同事反馈：编辑资金账户、勾完「所属公司」多选后提交，接口报：
+
+```
+请求数据格式错误：字段 [overdraftAllowed] 格式错误
+```
+
+**这不是「所属公司」字段的问题，也不是后端 bug。** 真实链路是：
+
+1. 「所属公司」（`scopeCompanies`）是 `List<String>`，多选序列化没问题；
+2. 但**提交动作**触发的请求体里，`overdraftAllowed` 被前端传成了布尔 `false`（开关组件原值）；
+3. 后端该字段定义是 `Integer`，Jackson 在 **JSON 反序列化阶段**就把请求拒了——**根本没进到业务校验层**，所以表象像是"选了公司就报错"，其实是同一请求体里附带的 `overdraftAllowed` 格式非法。
+
+报错文案来自全局异常处理器对 `HttpMessageNotReadableException`（JSON 解析失败）的兜底，提示里的字段名就是反序列化失败的那个字段。
+
+## 二、涉及接口与字段定义
+
+| 接口 | 方法 | 路径 | 该字段类型 |
+|---|---|---|---|
+| 新建资金账户 | POST | `/admin/finance/fund-accounts` | `Integer overdraftAllowed` |
+| 编辑资金账户 | PUT | `/admin/finance/fund-accounts/{id}` | `Integer overdraftAllowed` |
+
+字段语义：**可否透支**——`1` 允许（账户结存可扣成负数）/ `0` 不允许（默认，余额不足拦截）。
+
+> 两个接口同规则。响应侧（账户详情/列表）返回的也是 `Integer`（`1`/`0`），前端回显开关时需 `=== 1` 判真。
+
+## 三、示例
+
+### 3.1 反例：传布尔 → 400
+
+```http
+PUT /admin/finance/fund-accounts/2095431817594028033
+Content-Type: application/json
+
+{
+  "accountName": "基本户-工行",
+  "accountNo": "6222020200112233",
+  "overdraftAllowed": false,
+  "scopeCompanies": ["ALL"]
+}
+```
+
+响应（HTTP 200，业务码 400）：
+
+```json
+{ "code": 400, "message": "请求数据格式错误：字段 [overdraftAllowed] 格式错误", "success": false }
+```
+
+### 3.2 反例：传空串也会 400
+
+`"overdraftAllowed": ""` 同样非法（Jackson 无法把空串转 Integer）。**不想传就整个 key 不传，或给 `0`。**
+
+### 3.3 正例：传整数 → 成功
+
+```http
+PUT /admin/finance/fund-accounts/2095431817594028033
+Content-Type: application/json
+
+{
+  "accountName": "基本户-工行",
+  "accountNo": "6222020200112233",
+  "overdraftAllowed": 0,
+  "scopeCompanies": ["ALL"]
+}
+```
+
+```json
+{ "code": 200, "message": "成功", "success": true }
+```
+
+## 四、前端对接建议
+
+- 「可否透支」开关绑定值在提交前统一规整：`overdraftAllowed: form.overdraftAllowed ? 1 : 0`。
+- 回显时反向判真：开关 `checked = detail.overdraftAllowed === 1`。
+- 该字段选填；不传时后端按默认（不允许透支）处理，建议显式传 `0`/`1` 避免歧义。
+
+## 五、影响评估 / 回滚
+
+- **后端零变更**，本次仅为对接说明，无需发版、无需回滚。
+- 前端修好后（提交值规整为 `1`/`0`）即可正常调用，无需等待后端任何动作。
+
+## 六、关联 / 联系人
+
+- 负责人: 腰苏图（yst）
+- 反馈入口: 财务域后端对接群 / 直接 @yst