# 车务金额字段返回值 number → String — 修改接口 — 管理后台

> 变更类型：⚠️ 破坏性变更（JSON 类型 number → string）
> 端类型：管理后台
> 日期：2026-06-08
> 服务：hl-fleet-service

---

## 1. 背景

车务（fleet）部分接口的金额字段过去序列化为 JSON **数字**（如 `1000.00`）。平台约定金额一律以 **String** 下发前端（Java 内部仍是 BigDecimal），避免 JS 浮点精度问题、与其它模块口径统一。

本次给车务 3 个已上线接口的金额字段补上 `@JsonSerialize(ToStringSerializer)`，返回值由 **number 改为 string**（如 `1000.00` → `"1000.00"`）。**前端读取这些字段时必须按字符串处理**（如需计算先 `parseFloat`/`Number()`，展示直接用字符串）。

> 注：全局 Jackson 只把超出 JS 安全范围的 Long 雪花转 String，**不会自动转 BigDecimal**，所以金额需逐字段显式标注，此前这 3 处漏标导致泄成数字。

---

## 2. 变更清单

| # | 接口 | 字段 | 旧类型(JSON) | 新类型(JSON) | 示例 |
|---|---|---|---|---|---|
| 1 | 车型型号分页 / 详情 | `basePrice` 起步价 | number | **string** | `1000.00` → `"1000.00"` |
| 2 | 车型价格日历查询 | `dayPrice` 当日租赁价 | number | **string** | `800.00` → `"800.00"` |
| 3 | 司机详情·保险块 | `annualPremium` 年保费 | number | **string** | `3600.00` → `"3600.00"` |
| 4 | 司机详情·保险块 | `perDayRate` 行程日费率 | number | **string** | `50.00` → `"50.00"` |

> 仅这 4 个金额字段受影响；其它非金额数字字段（座位数 seats、排序 sortOrder、各类 count）不变。

---

## 3. 受影响接口

| 接口 | 方法 | 路径 | 受影响字段 |
|---|---|---|---|
| 车型型号分页 | GET | `/admin/fleet/vehicle-types/models/page` | basePrice |
| 车型价格日历查询 | GET | `/admin/fleet/vehicle-types/{vehicleModelId}/pricing-calendar` | dayPrice |
| 司机详情 | GET | `/admin/fleet/drivers/{driverId}` | insurance.annualPremium / insurance.perDayRate |

---

## 4. 示例（车型型号分页）

**请求**

```
GET /admin/fleet/vehicle-types/models/page?pageNo=1&pageSize=5
Authorization: Bearer <token>
```

**响应（注意 basePrice 现为带引号的字符串）**

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "id": "2057378612593823745",
        "vehicleTypeId": "2057378611889180674",
        "modelName": "丰田普拉多",
        "seats": 7,
        "basePrice": "1000.00",
        "alias": "",
        "sortOrder": 1
      }
    ],
    "total": 1
  },
  "success": true
}
```

---

## 5. 前端迁移

| 字段 | 前端处理 |
|---|---|
| basePrice / dayPrice / annualPremium / perDayRate | 读到的是字符串 `"1000.00"`。**展示**：直接用。**参与计算**：先 `Number(x)` / `parseFloat(x)` 再算，结果再格式化回字符串。**编辑回填**：表单控件按字符串赋值即可。 |

- 若前端原先把这些字段当 number 直接做算术（`a.basePrice + b.basePrice`），现在会变成字符串拼接，**必须改为先转数字**。
- 提交（保存）入参不受影响——入参金额前端按原样传，后端独立计算/解析。

---

## 6. 关联

| 项目 | 信息 |
|---|---|
| PR | https://git.1814.love:8443/wx/HL/pulls/3592 |
| 部署 | 已部署测试服并实测：`"basePrice":"1000.00"`（网关 9443 + admin token 实测带引号） |
| 后端负责人 | wx |