文件

T

changelog-filename-gate / validate (push) Failing after 2s

详情

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

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

2026-09-15 11:53:35 +08:00

4.8 KiB

原始文件 Blame 文件历史

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	frontend-finance-fund-account-overdraft	资金账户 overdraftAllowed 禁传布尔，须传整数 1/0（前端对接纠错）	admin	yst(GIT)	修改接口	deployed	verified	pending				2026-09-15	后端契约零变更，仅前端对接纠错：新建/编辑资金账户接口的 overdraftAllowed 字段是 Integer（1 允许 / 0 不允许），不是布尔。前端开关组件若直接提交 true/false，会被 Jackson 在反序列化阶段拦截，报「请求数据格式错误：字段 [overdraftAllowed] 格式错误」（HTTP 200 + code 400）。提交前须把开关值规整为 1/0 整数。	2026-09-15	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。 真实链路是：

「所属公司」（scopeCompanies）是 List<String>，多选序列化没问题；
但提交动作触发的请求体里，overdraftAllowed 被前端传成了布尔 false（开关组件原值）；
后端该字段定义是 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

PUT /admin/finance/fund-accounts/2095431817594028033
Content-Type: application/json

{
  "accountName": "基本户-工行",
  "accountNo": "6222020200112233",
  "overdraftAllowed": false,
  "scopeCompanies": ["ALL"]
}

响应（HTTP 200，业务码 400）：

{ "code": 400, "message": "请求数据格式错误：字段 [overdraftAllowed] 格式错误", "success": false }

3.2 反例：传空串也会 400

"overdraftAllowed": "" 同样非法（Jackson 无法把空串转 Integer）。不想传就整个 key 不传，或给 0。

3.3 正例：传整数 → 成功

PUT /admin/finance/fund-accounts/2095431817594028033
Content-Type: application/json

{
  "accountName": "基本户-工行",
  "accountNo": "6222020200112233",
  "overdraftAllowed": 0,
  "scopeCompanies": ["ALL"]
}

{ "code": 200, "message": "成功", "success": true }

四、前端对接建议

「可否透支」开关绑定值在提交前统一规整：overdraftAllowed: form.overdraftAllowed ? 1 : 0。
回显时反向判真：开关 checked = detail.overdraftAllowed === 1。
该字段选填；不传时后端按默认（不允许透支）处理，建议显式传 0/1 避免歧义。

五、影响评估 / 回滚

后端零变更，本次仅为对接说明，无需发版、无需回滚。
前端修好后（提交值规整为 1/0）即可正常调用，无需等待后端任何动作。

六、关联 / 联系人

负责人: 腰苏图（yst）
反馈入口: 财务域后端对接群 / 直接 @yst

4.8 KiB 原始文件 Blame 文件历史 Unescape Escape