diff --git a/changelogs-v2/2026-09/15_fund-account_可否透支overdraftAllowed禁传布尔须传1或0-修改接口-管理后台.md b/changelogs-v2/2026-09/15_fund-account_可否透支overdraftAllowed禁传布尔须传1或0-修改接口-管理后台.md new file mode 100644 index 00000000..5edb8506 --- /dev/null +++ b/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`,多选序列化没问题; +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