changelog: #5520 保险订单 totalPremium 恒 0 修复（保游金额字符串解析）

changelogs-v2/2026-08/04_5520_保险订单totalPremium恒0修复-修改接口-管理后台.md

@@ -0,0 +1,67 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5520"
+title: "保险订单 totalPremium 恒 0 修复（保游金额字符串解析）"
+consumer: "admin"
+change_type: "修改接口"
+author: "wx(GIT)"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端完成：PR #5521 已合并 dev-v3 并部署 TEST；网关实测新投保 totalPremium=\"88.00\"（修复前恒 \"0\"），DB 落库 88.00 与 raw_response 一致；存量 252 行已回填全量一致 253/253。行为修复：保单列表/详情/详情弹窗的 totalPremium 从恒 0 变为平台实际保费。"
+updated_at: "2026-08-04"
+base: "dev-v3"
+---
+
+# 保险订单 totalPremium 恒 0 修复（#5520）
+
+> **服务**: hl-order-service-v3（+hl-fleet-service 对账联动）
+> **PR**: #5521
+> **Issue**: #5520（P1）
+> **联系人**: @wx
+> **日期**: 2026-08-04
+> **影响范围**: 管理后台司机保险保单列表/详情 totalPremium 展示、退保/对账金额计算
+
+---
+
+## 变更说明
+
+**根因**：jackson-databind 2.13 的 `TextNode` 未覆盖 `decimalValue()`，保游响应中的字符串金额节点（`"TotalPremium":"88.00"`）调用时走基类默认实现恒返回 `BigDecimal.ZERO`，导致投保落库 `insurance_order.total_premium` 恒 0.00。
+
+**修复**：新增 `BaoyouMoney` 安全解析（数值节点走 decimalValue、文本节点按 BigDecimal 解析、null/空串/非法兜底），替换保险链路 5 处金额解析（投保落库 TotalPremium、保单查询 TotalPremium、回调 OrderMoney、保游余额 Balance、费率 Premium）。
+
+## 变更接口
+
+| 方法 | 路径 | 来源 |
+|---|---|---|
+| POST | /admin/fleet/drivers/{driverId}/insurance/purchase | 管理后台-司机保险 |
+| GET | /admin/fleet/drivers/{driverId}/insurance/policies | 管理后台-司机保险 |
+| POST | /admin/fleet/drivers/{driverId}/insurance/policies/{insuranceOrderId}/cancel | 管理后台-司机保险 |
+| GET | /admin/fleet/reconciliation/insurance | 管理后台-保险对账 |
+
+## 接口行为变化
+
+| 接口 | 字段 | 修复前 | 修复后 |
+|---|---|---|---|
+| `POST /admin/fleet/drivers/{driverId}/insurance/purchase` | totalPremium | `"0"`（恒） | `"88.00"`（平台实际保费） |
+| `GET /admin/fleet/drivers/{driverId}/insurance/policies` | totalPremium | `"0"` | `"88.00"` |
+| 退保链路 | 退费计算基数 | 0 | 平台实际保费 |
+| 保险对账（baoyou 口径） | 摊销金额 | 0 | 保单实际保费（新链路） |
+
+字段类型、命名、契约结构均无变化，仅值语义修正。
+
+## 存量数据
+
+- TEST 环境 252 行存量保单（245 INSURED + 7 CANCELLED）已按 `raw_response.TotalPremium` 精确回填 `total_premium=88.00`，全量 253/253 与平台响应一致。
+- 存量 `fleet_insurance_task` 任务快照 premium_amount=0 为历史创建时未关联保单 id 的派生快照，不做模糊回填（避免错配）；新链路任务金额从保单 total_premium 复制自动正确。
+
+
+## 验证证据
+
+- 网关实测（api.test.1814.love:9443，admin，2026-08-04）：新投保 totalPremium="88.00"（修复前恒 "0"），DB total_premium=88.00 与 raw_response 一致
+- 存量 252 行回填后全量 253/253 raw==列 一致；退保金额保持 88.00、update_time 刷新
+- 定向测试：BaoyouMoneyTest 4/4 + savePurchaseResult 字符串金额回归，保险域 354/354 全绿（PR #5521）