---
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: "verified"
frontend_owner: "mmg"
frontend_ref: "7a2cbaa3c716ec6f6195344963693cf52bb9f456"
target_release: ""
verified_at: "2026-09-15"
status_note: "后端契约零变更，仅前端对接纠错：新建/编辑资金账户接口的 overdraftAllowed 字段是 Integer（1 允许 / 0 不允许），不是布尔。前端开关组件若直接提交 true/false，会被 Jackson 在反序列化阶段拦截，报「请求数据格式错误：字段 [overdraftAllowed] 格式错误」（HTTP 200 + code 400）。提交前须把开关值规整为 1/0 整数。 前端已修复(7a2cbaa3):AccountFormDrawer 提交体 overdraftAllowed 规整 true→1/false→0,编辑回显改 === 1 判真(规避 \"0\" 字符串 Boolean 误判),fund-account.js 入参文档同步 Integer 口径;新增 AccountFormDrawer.spec 3 例,checkpoint 13 项全绿。"
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