---
schema: "hl-changelog/v2"
ticket: "5520"
title: "保险订单 totalPremium 恒 0 修复（保游金额字符串解析）"
consumer: "admin"
change_type: "修改接口"
author: "wx(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "pi-main-session"
frontend_ref: "hl-admin@ef497e8e30d2df2d55d97f5554c8c5e921dc49ef"
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）

## 关联/联系人

### 链接

- [后端工单 #5520](https://git.1814.love:8443/wx/HL/issues/5520)
- [后端 PR #5521](https://git.1814.love:8443/wx/HL/pulls/5521)
- Merge commit: `3bc4ff3ba8`

### 联系人

- **后端负责人**: @wx