From d37df2feab3026d9798d67d6f668679c1fb902bc Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 8 Jun 2026 14:56:39 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=BD=A6=E5=8A=A1=E9=87=91?= =?UTF-8?q?=E9=A2=9D=E5=AD=97=E6=AE=B5number=E2=86=92String(PR#3592,?= =?UTF-8?q?=E7=A0=B4=E5=9D=8F=E6=80=A7)=20+=20=E8=BD=A6=E9=98=9F=E5=BD=92?= =?UTF-8?q?=E5=B1=9E/=E4=BD=BF=E7=94=A8=E6=80=A7=E8=B4=A8=E6=94=B9?= =?UTF-8?q?=E5=AD=97=E5=85=B8=E4=B8=8B=E6=8B=89(PR#3596)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...字段返回值number改String-修改接口-管理后台.md | 95 +++++++++++++ ...与使用性质改数据字典下拉-修改接口-管理后台.md | 130 ++++++++++++++++++ 2 files changed, 225 insertions(+) create mode 100644 changelogs-v2/2026-06/08_3592_车务金额字段返回值number改String-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-06/08_3596_车队归属与使用性质改数据字典下拉-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/08_3592_车务金额字段返回值number改String-修改接口-管理后台.md b/changelogs-v2/2026-06/08_3592_车务金额字段返回值number改String-修改接口-管理后台.md new file mode 100644 index 0000000..f859bea --- /dev/null +++ b/changelogs-v2/2026-06/08_3592_车务金额字段返回值number改String-修改接口-管理后台.md @@ -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 +``` + +**响应（注意 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 | diff --git a/changelogs-v2/2026-06/08_3596_车队归属与使用性质改数据字典下拉-修改接口-管理后台.md b/changelogs-v2/2026-06/08_3596_车队归属与使用性质改数据字典下拉-修改接口-管理后台.md new file mode 100644 index 0000000..d8432d8 --- /dev/null +++ b/changelogs-v2/2026-06/08_3596_车队归属与使用性质改数据字典下拉-修改接口-管理后台.md @@ -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 +``` +**响应** +```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 +``` +**响应** +```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 |