docs(changelog): 车务金额字段number→String(PR#3592,破坏性) + 车队归属/使用性质改字典下拉(PR#3596)
这个提交包含在：
API Changelog Bot
父节点
7c33a382bc
当前提交
d37df2feab
@ -0,0 +1,95 @@
|
|||||||
|
# 车务金额字段返回值 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 |
|
||||||
@ -0,0 +1,130 @@
|
|||||||
|
# 车辆档案「车队归属 / 使用性质」改数据字典下拉 — 修改接口 — 管理后台
|
||||||
|
|
||||||
|
> 变更类型：🟡 增强（字段取值改字典驱动，字段名/类型不变）
|
||||||
|
> 端类型：管理后台
|
||||||
|
> 日期：2026-06-08
|
||||||
|
> 服务：hl-fleet-service + hl-user-service（字典种子）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 背景
|
||||||
|
|
||||||
|
车辆档案（新增 / 编辑）表单里两个字段过去是写死的：
|
||||||
|
- `fleet`（车队归属）原是后端 `@Pattern` 写死枚举 own/coopA/coopB；
|
||||||
|
- `regCertUsage`（使用性质）原是纯自由文本输入框。
|
||||||
|
|
||||||
|
本次把这两个字段改为**数据字典驱动**，前端应改为**下拉选择框**，选项从通用字典接口实时拉取。这样合作车队、使用性质都能在字典后台增减，无需改代码发版。
|
||||||
|
|
||||||
|
> 字段名、类型、提交入参格式**全不变**，前端只是把输入控件换成下拉、并从字典接口取选项。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 变更清单
|
||||||
|
|
||||||
|
| 字段 | 位置 | 旧控件 | 新控件 | 字典 type | 存的值 |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
| `fleet` 车队归属 | 车辆档案新增/编辑表单 | 写死下拉 own/coopA/coopB | 字典下拉 | `fleet_attribution` | dictValue（own/coopA/coopB code） |
|
||||||
|
| `regCertUsage` 使用性质 | 车辆档案新增/编辑表单 | 自由文本框 | 字典下拉 | `vehicle_reg_cert_usage` | dictValue（中文：营运租赁等） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 字典选项怎么取（通用接口，已有）
|
||||||
|
|
||||||
|
| 项目 | 值 |
|
||||||
|
|---|---|
|
||||||
|
| 方法 | GET |
|
||||||
|
| 路径 | `/admin/dict/data/{dictType}` |
|
||||||
|
| 认证 | Bearer Token（管理后台 JWT） |
|
||||||
|
|
||||||
|
前端渲染下拉：用 `dictValue` 作为选项的 value（提交给后端的值）、`dictLabel` 作为显示文案。已按 `sortOrder` 升序返回。
|
||||||
|
|
||||||
|
### 3.1 车队归属 `fleet_attribution`
|
||||||
|
|
||||||
|
**请求**
|
||||||
|
```
|
||||||
|
GET /admin/dict/data/fleet_attribution
|
||||||
|
Authorization: Bearer <token>
|
||||||
|
```
|
||||||
|
**响应**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200, "message": "成功", "success": true,
|
||||||
|
"data": [
|
||||||
|
{"dictValue": "own", "dictLabel": "自有", "sortOrder": 10, "status": "ACTIVE"},
|
||||||
|
{"dictValue": "coopA", "dictLabel": "合作车队A", "sortOrder": 20, "status": "ACTIVE"},
|
||||||
|
{"dictValue": "coopB", "dictLabel": "合作车队B", "sortOrder": 30, "status": "ACTIVE"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 使用性质 `vehicle_reg_cert_usage`
|
||||||
|
|
||||||
|
**请求**
|
||||||
|
```
|
||||||
|
GET /admin/dict/data/vehicle_reg_cert_usage
|
||||||
|
Authorization: Bearer <token>
|
||||||
|
```
|
||||||
|
**响应**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200, "message": "成功", "success": true,
|
||||||
|
"data": [
|
||||||
|
{"dictValue": "营运租赁", "dictLabel": "营运租赁", "sortOrder": 10, "status": "ACTIVE"},
|
||||||
|
{"dictValue": "非营运", "dictLabel": "非营运", "sortOrder": 20, "status": "ACTIVE"},
|
||||||
|
{"dictValue": "旅游客运", "dictLabel": "旅游客运", "sortOrder": 30, "status": "ACTIVE"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> 使用性质的 value=label（都是中文），照抄行驶证「使用性质」栏；车队归属 value 是英文 code、label 是中文，**提交给保存接口的是 dictValue（own/coopA/coopB），展示用 dictLabel**。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 保存接口入参（不变，仅举例）
|
||||||
|
|
||||||
|
车辆新增 `POST /admin/fleet/vehicles` / 编辑 `PUT /admin/fleet/vehicles/{vehicleId}`，body 里 `fleet` 传选中的 dictValue、`regCertUsage` 传选中的 dictValue：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"plate": "蒙A-66666",
|
||||||
|
"vehicleModelId": "...",
|
||||||
|
"fleet": "own",
|
||||||
|
"regCertUsage": "营运租赁",
|
||||||
|
"...": "..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 前端迁移清单
|
||||||
|
|
||||||
|
1. **车队归属**：输入控件改为下拉，选项 `GET /admin/dict/data/fleet_attribution`；提交 `fleet` = 选中项 `dictValue`；列表/详情回显时用 `dictValue` 在字典里查 `dictLabel` 显示（也可直接缓存该字典做映射）。
|
||||||
|
2. **使用性质**：自由文本框改为下拉，选项 `GET /admin/dict/data/vehicle_reg_cert_usage`；提交 `regCertUsage` = 选中项 `dictValue`（中文）。
|
||||||
|
3. **存量数据兼容**：历史车辆的 `fleet`/`regCertUsage` 值与字典 value 一致（own/coopA/coopB、营运租赁等），回显正常；若遇到字典里没有的历史脏值，下拉做「未匹配则原样显示」兜底。
|
||||||
|
4. 后端已去掉写死枚举校验，**字典后台新增的合作车队（如 coopC）/ 新使用性质会自动出现在下拉**，前端无需改代码。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 附带：错误码提示已全中文化（无需前端改动，仅告知）
|
||||||
|
|
||||||
|
后端把车务错误提示里的英文术语换成了中文，前端若直接透传后端 `message` 展示会更友好：
|
||||||
|
|
||||||
|
| 旧提示 | 新提示 |
|
||||||
|
|---|---|
|
||||||
|
| VIN 已存在 | 车架号已存在 |
|
||||||
|
| token 无效 / 已过期 / 已使用 | 邀请链接无效 / 已过期 / 已使用 |
|
||||||
|
| OCR 识别失败 | 证件识别失败 |
|
||||||
|
| 车型大类 key 已存在 | 车型大类标识已存在 |
|
||||||
|
|
||||||
|
> 另：车辆档案错误码编号文档此前与代码不一致，已按代码对齐——「车架号已存在」实际码 **600107**（非文档旧标的 600101）、「车型不存在」**600108**。前端按 `message` 文案处理即可，一般无需硬编码错误码。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 关联
|
||||||
|
|
||||||
|
| 项目 | 信息 |
|
||||||
|
|---|---|
|
||||||
|
| PR | https://git.1814.love:8443/wx/HL/pulls/3596 |
|
||||||
|
| 部署 | 已部署测试服并实测：两字典经网关 9443 各返 3 项（fleet_attribution / vehicle_reg_cert_usage） |
|
||||||
|
| 字典维护 | 系统管理 → 字典管理，type=`fleet_attribution` / `vehicle_reg_cert_usage` |
|
||||||
|
| 后端负责人 | wx |
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户