From f6ca749fe3283614d69787b87b0c884e673db1bf Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Sat, 8 Aug 2026 20:12:16 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=BD=A6=E8=BE=86=E6=A0=B8?= =?UTF-8?q?=E5=8D=95=E9=87=91=E9=A2=9D=E6=94=BE=E5=BC=80=E5=8F=AF=E7=BC=96?= =?UTF-8?q?=E8=BE=91(#5712)+=E8=BD=A6=E8=BE=86=E4=B8=8B=E6=8B=89=E6=96=B0?= =?UTF-8?q?=E5=A2=9EdayPrice(#5708)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 5712: PUT /v3/admin/order/{orderId}/settlement/step3/vehicles FLEET行amount放开可编辑 - 5708: GET /v3/admin/order/{orderId}/settlement/vehicle-options 出参新增dayPrice参考价 --- ...拉新增车型牌价dayPrice-修改接口-管理后台.md | 249 ++++++++++++++++ ...辆核单金额放开可编辑-修改接口-管理后台.md | 266 ++++++++++++++++++ 2 files changed, 515 insertions(+) create mode 100644 changelogs-v2/2026-08/08_5708_车辆下拉新增车型牌价dayPrice-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-08/08_5712_车辆核单金额放开可编辑-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/08_5708_车辆下拉新增车型牌价dayPrice-修改接口-管理后台.md b/changelogs-v2/2026-08/08_5708_车辆下拉新增车型牌价dayPrice-修改接口-管理后台.md new file mode 100644 index 0000000..e34b36a --- /dev/null +++ b/changelogs-v2/2026-08/08_5708_车辆下拉新增车型牌价dayPrice-修改接口-管理后台.md @@ -0,0 +1,249 @@ +--- +schema: "hl-changelog/v2" +ticket: "5708" +title: "核单车辆下拉新增车型当日牌价 dayPrice（参考价，非最终核算价）" +consumer: "admin" +change_type: "修改接口" +author: "yaosutu(GIT)" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #5713 已合并 dev-v3；GET /v3/admin/order/{orderId}/settlement/vehicle-options 出参 data[] 新增 dayPrice 字段（车型当日牌价，元/车天）。dayPrice 是参考价非最终核算价，最终核算价以派单后车辆快照 dailyPrice / 核单行 amount 为准。" +updated_at: "2026-08-08" +base: "dev-v3" +--- + +# 【修改接口·管理后台】核单车辆下拉新增车型当日牌价 dayPrice（#5708） + +> **PR**: [#5713](https://git.1814.love:8443/wx/HL/pulls/5713) | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-08 + +## 1. 接口背景 + +核单 Step3 车辆 Tab 的车辆下拉选项接口，此前只返回车牌 / 车型 / 司机等基础信息，核单人员看不到该车型当日的参考牌价，选车时无法预估金额。本次在出参 `data[]` 新增 `dayPrice` 字段，按订单出发日期取该车型当日定价，**仅供前端展示参考，不是最终核算价**。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 前端动作 | +|---|---|---|---|---|---| +| 1 | 查询核单车辆异步下拉 | GET | `/v3/admin/order/{orderId}/settlement/vehicle-options` | 出参新增字段 | 读取 `data[].dayPrice`，建议标注"参考价" | + +## 3. 接口详情 + +- **使用场景**：核单人员在订单核单 Step3 车辆 Tab 选择车辆时，通过关键字异步搜索候选车辆。 +- **认证**：需要管理后台登录态（Bearer Token）。 +- **幂等性**：是，只读查询。 +- **限流**：未声明接口专属限流。 + +## 4. 接口入参 + +### 4.1 路径参数 / Query 参数 + +| 字段 | 位置 | 类型 | 必填 | 说明 | +|---|---|---|---|---| +| `orderId` | Path | Long | 是 | 订单 ID | +| `keyword` | Query | String | 否 | 可匹配车牌、品牌型号、车型大类和常驻司机姓名 | +| `limit` | Query | Integer | 否 | 由 Fleet 按默认 10、最大 20 处理 | + +### 4.2 请求体字段 + +GET 请求无请求体。 + +## 5. 出参字段 + +响应类型：`Result>`。 + +### 5.1 统一响应外层 + +| 字段 | 类型 | 可空 | 说明 | +|---|---|---|---| +| `code` | Integer | 否 | 成功为 `200`；失败见 §7 | +| `message` | String | 否 | 结果说明 | +| `data` | Array | 失败时为空 | 成功时为车辆下拉选项数组 | +| `success` | Boolean | 否 | `code=200` 时为 `true` | + +### 5.2 `data[]` 字段（共 8 个） + +| 字段 | 类型 | 可空 | 说明 | +|---|---|---|---| +| `vehicleId` | String(Long) | 否 | 车辆 ID | +| `plate` | String | 否 | 车牌号 | +| `modelName` | String | 否 | 车型名称 | +| `typeName` | String | 否 | 车型大类 | +| `primaryDriverId` | String(Long) | 是 | 常驻司机 ID | +| `primaryDriverName` | String | 是 | 常驻司机姓名 | +| `label` | String | 否 | 下拉展示文案（车牌/车型/大类/司机拼接） | +| **`dayPrice`** | **Decimal** | **是** | **车型当日牌价（元/车天），本次新增**；语义见下 | + +### 5.3 `dayPrice` 语义（**重点，前端必读**） + +- **是参考价，不是最终核算价**：`dayPrice` 来自 fleet 车型定价日历（按订单出发日 `departDate` 取当日牌价，未定价日回退车型 `basePrice`）。 +- **最终核算价以派单后车辆快照 `dailyPrice` / 核单行 `amount` 为准**。前端展示 `dayPrice` 时应标注"参考价"，避免误导核单人员把它当成结算价。 +- **fleet 未上线该字段前 `dayPrice` 为 `null`**（向前兼容）；fleet 侧现已上线（配套 Issue #5706），正常出值。 + +## 6. 枚举 / 数据字典 + +本次不涉及枚举新增或改值。 + +## 7. 错误码 + +| code | 含义 | 触发场景 | +|---:|---|---| +| `400` | 请求参数错误 | `orderId` 非法（如 0、负数、非数字） | +| `581007` | 订单不存在 | `orderId` 对应订单不存在 | +| `584071` | 无权访问该订单 | 当前账号不在订单可访问范围内 | + +## 8. 示例 + +### 8.1 典型成功 —— 返回含 dayPrice + +**请求**： + +```http +GET /v3/admin/order/2084000000000002978/settlement/vehicle-options?keyword=汉兰达&limit=10 +Authorization: Bearer +``` + +无请求体。 + +**响应**： + +```json +{ + "code": 200, + "message": "success", + "data": [ + { + "vehicleId": "301", + "plate": "蒙A88888", + "modelName": "丰田汉兰达", + "typeName": "SUV", + "primaryDriverId": "45", + "primaryDriverName": "张师傅", + "label": "蒙A88888 丰田汉兰达 SUV 张师傅", + "dayPrice": "1000.00" + }, + { + "vehicleId": "302", + "plate": "蒙A66666", + "modelName": "丰田汉兰达", + "typeName": "SUV", + "primaryDriverId": "46", + "primaryDriverName": "李师傅", + "label": "蒙A66666 丰田汉兰达 SUV 李师傅", + "dayPrice": "1000.00" + } + ], + "success": true +} +``` + +### 8.2 边界情况 —— 车型当日未定价时 dayPrice 回退 basePrice 或为 null + +**场景说明**：某车型在订单出发日未配置定价日历时，后端回退取车型 `basePrice`；若 fleet 侧未上线该字段则返回 `null`。 + +**请求**： + +```http +GET /v3/admin/order/2084000000000002978/settlement/vehicle-options?keyword=别克&limit=10 +Authorization: Bearer +``` + +无请求体。 + +**响应**： + +```json +{ + "code": 200, + "message": "success", + "data": [ + { + "vehicleId": "305", + "plate": "蒙A11111", + "modelName": "别克GL8", + "typeName": "MPV", + "primaryDriverId": "47", + "primaryDriverName": "王师傅", + "label": "蒙A11111 别克GL8 MPV 王师傅", + "dayPrice": null + } + ], + "success": true +} +``` + +前端拿到 `dayPrice: null` 时应展示为 "—" 或不显示该行参考价，**不要展示为 `0`**。 + +### 8.3 业务失败 —— orderId 非法返 400 + +**请求**： + +```http +GET /v3/admin/order/0/settlement/vehicle-options?keyword=汉兰达 +Authorization: Bearer +``` + +无请求体。 + +**响应**： + +```json +{"code": 400, "message": "请求参数错误", "data": null, "success": false} +``` + +## 9. 业务边界 + +- **适用场景**：核单车辆下拉展示参考牌价，辅助核单人员选车预估金额。 +- **不适用场景**：**不要把 `dayPrice` 当作最终核算价**展示在结算明细里；最终价以派单后快照 `dailyPrice` / 核单行 `amount` 为准。 +- **特殊边界**：`dayPrice` 为 `null` 时表示 fleet 侧暂无该车型当日定价数据，不等于"免费"；展示时应与 `0.00` 区分。 + +## 10. 修改前后对比 + +### 10.1 字段级对比 + +| 字段 | 原来 | 现在 | +|---|---|---| +| `data[].dayPrice` | 不存在 | **新增**；Decimal，可空 | + +其余 7 个字段（`vehicleId`/`plate`/`modelName`/`typeName`/`primaryDriverId`/`primaryDriverName`/`label`）无变化。 + +### 10.2 行为级对比 + +| 行为 | 原来 | 现在 | +|---|---|---| +| 车辆下拉展示 | 只有车牌/车型/司机 | 新增当日参考牌价 | + +## 11. 影响评估 / 回滚 + +### 11.1 影响评估 + +- **是否破坏向后兼容**：否。仅出参新增字段，旧前端不读 `dayPrice` 即可继续工作。 +- **前端是否必须同步上线**：否。字段为增强信息，前端可择机上线展示。 + +### 11.2 回滚方案 + +- 回滚即出参不再返回 `dayPrice`；已上线的新前端应把 `dayPrice` 作为可选字段处理（读到就展示、读不到就不展示），天然兼容回滚。 + +## 12. 注意事项 + +- **`dayPrice` 是参考价**，前端展示建议加"参考价"标注，避免与最终核算价混淆。 +- fleet 侧配套改动见 Issue #5706；fleet 未上线前 `dayPrice` 恒为 `null`，前端需做 null 兜底展示。 +- `dayPrice` 单位为元/车天（整段行程 1 天的价格），不是整段总价。 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#5708](https://git.1814.love:8443/wx/HL/issues/5708) +- **PR**: [#5713](https://git.1814.love:8443/wx/HL/pulls/5713) +- **Merge commit**: [10ba85d65](https://git.1814.love:8443/wx/HL/commit/10ba85d65eca08fa5b1f9da60a4e8c9cfd318938) +- **配套 fleet 侧 Issue**: [#5706](https://git.1814.love:8443/wx/HL/issues/5706) + +### 13.2 联系人 + +- **后端负责人**: @yaosutu (yst) +- **fleet 侧对接**: @wx diff --git a/changelogs-v2/2026-08/08_5712_车辆核单金额放开可编辑-修改接口-管理后台.md b/changelogs-v2/2026-08/08_5712_车辆核单金额放开可编辑-修改接口-管理后台.md new file mode 100644 index 0000000..5a959d9 --- /dev/null +++ b/changelogs-v2/2026-08/08_5712_车辆核单金额放开可编辑-修改接口-管理后台.md @@ -0,0 +1,266 @@ +--- +schema: "hl-changelog/v2" +ticket: "5712" +title: "车辆核单 FLEET 行核算金额放开可编辑（amount 不再撞 584109）" +consumer: "admin" +change_type: "修改接口" +author: "yaosutu(GIT)" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #5715 已合并 dev-v3；PUT /v3/admin/order/{orderId}/settlement/step3/vehicles 对 FLEET 来源行的 amount 字段从只读放开为可编辑，结构字段仍受 584109 保护。前端若把 amount 渲染为只读输入框，应放开为可编辑。" +updated_at: "2026-08-08" +base: "dev-v3" +--- + +# 【修改接口·管理后台】车辆核单 FLEET 行核算金额放开可编辑（#5712） + +> **PR**: [#5715](https://git.1814.love:8443/wx/HL/pulls/5715) | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-08 + +## 1. 接口背景 + +核单 Step3 车辆 Tab 的全量保存接口此前对 **FLEET（车务）来源行** 的 `amount`（核算金额）做只读保护：前端把 GET 回显的金额改大/改小后回传，会被错误码 `584109`「车务来源字段不可直接修改或删除」拦截，接口虽然返回 200 但 message 提示、金额实际不变。 + +业务诉求：核单人员需要能对车务来源的核算金额做手工修正（实际结算价与车务快照价不一致的场景，与住宿/门票核单的人工调价口径一致）。本次放开 FLEET 行 `amount` 可编辑，**改完即生效、不留审计痕**。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 前端动作 | +|---|---|---|---|---|---| +| 1 | 全量保存车辆核单草稿 | PUT | `/v3/admin/order/{orderId}/settlement/step3/vehicles` | 行为放开（字段零变化） | FLEET 行 `amount` 输入框由只读改可编辑 | +| 2 | 查询车辆核单草稿 | GET | `/v3/admin/order/{orderId}/settlement/step3/vehicles` | 出参语义变化 | `items[].amount` 现返回覆盖层修正后金额 | + +## 3. 接口详情 + +- **使用场景**：核单人员在订单核单 Step3 车辆 Tab 维护车辆核单明细（全量覆盖式保存）。 +- **认证**：需要管理后台登录态（Bearer Token）。 +- **幂等性**：是，按订单维度全量覆盖式保存，重复提交相同载荷结果一致。 +- **限流**：未声明接口专属限流。 + +## 4. 接口入参 + +### 4.1 路径参数 + +| 字段 | 位置 | 类型 | 必填 | 说明 | +|---|---|---|---|---| +| `orderId` | Path | Long | 是 | 订单 ID | + +### 4.2 请求体字段 + +| 字段 | 类型 | 必填 | 校验规则 | 本次是否放开 | +|---|---|---|---|---| +| `items` | Array | 是 | 全量明细 | — | +| `items[].id` | Long | 条件必填 | 既有行必传；新增手工行为 null | 否（仍受 584109 保护） | +| `items[].sourceType` | String | 是 | `FLEET` / `MANUAL` | 否 | +| `items[].serviceDate` | String(date) | 是 | `yyyy-MM-dd` | 否（仍受 584109 保护） | +| `items[].vehicleId` | Long | 条件必填 | FLEET 行必传 | 否（仍受 584109 保护） | +| `items[].vehiclePlate` | String | 否 | 最长 64 | 否（仍受 584109 保护） | +| `items[].vehicleModelId` | Long | 否 | — | 否（仍受 584109 保护） | +| `items[].vehicleModelName` | String | 否 | 最长 128 | 否（仍受 584109 保护） | +| `items[].driverId` | Long | 否 | — | 否（仍受 584109 保护） | +| `items[].driverName` | String | 否 | 最长 64 | 否（仍受 584109 保护） | +| `items[].amount` | Decimal | 是 | 非负、最多 2 位小数 | **本次放开为可编辑** | +| `items[].paymentMethod` | String | 是 | `CASH_PAID` / `SIGNED` / `COMPANY_PAID` | 否（仍受 584109 保护） | +| `items[].settlementConfirmStatus` | String | 是 | `UNCONFIRMED` / `CONFIRMED` | 否（本就可改） | +| `items[].remark` | String | 否 | 最长 500 | 否（本就可改） | +| `items[].voucherUrls` | String[] | 否 | 最多 9 个 URL | 否（本就可改） | + +> **FLEET 行编辑约定**：`vehicleFeeLineId`（即 GET 回显的 `items[].id`）、`serviceDate`、`vehicleId`、`vehiclePlate`、`vehicleModelId`、`vehicleModelName`、`driverId`、`driverName`、`paymentMethod` 这 9 个**车务来源结构字段不允许改**，前端应把这些字段**原样回传**（来自 GET step3/vehicles 的回显值），只允许改 `amount`（以及 `remark` / `voucherUrls` / `settlementConfirmStatus`）。改了结构字段仍撞 `584109`。 + +## 5. 出参字段 + +成功响应为统一 `Result` 结构，`code=200`。`data` 出参字段（`orderId` / `totalAmount` / `allConfirmed` / `settlementReady` / `blockReasonCode` / `items` / `frozen`）结构无变化。 + +**唯一语义变化**：GET `items[].amount` 现在返回**覆盖层修正后的金额**（改完再查就是新值），不再被 fleet 快照价覆盖。 + +## 6. 枚举 / 数据字典 + +本次不涉及枚举新增或改值。`paymentMethod`（CASH_PAID/SIGNED/COMPANY_PAID）、`settlementConfirmStatus`（UNCONFIRMED/CONFIRMED）、`sourceType`（FLEET/MANUAL）取值不变。 + +## 7. 错误码 + +| code | 含义 | 触发场景 | +|---:|---|---| +| `584109` | 车务来源字段不可直接修改或删除 | 改了 FLEET 行的结构字段（serviceDate/vehicleId/vehiclePlate/vehicleModelId/vehicleModelName/driverId/driverName/paymentMethod/vehicleFeeLineId）或试图删除 FLEET 行 | +| `400` | 请求数据格式错误 | `amount` 为负数 / 小数位超过 2 位 / 数值超出范围 / 其他 Bean 校验失败 | + +## 8. 示例 + +### 8.1 典型成功 —— FLEET 行 amount 由 800 改为 950 + +**请求**： + +```http +PUT /v3/admin/order/2084000000000002978/settlement/step3/vehicles +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "items": [ + { + "id": "9001", + "sourceType": "FLEET", + "serviceDate": "2026-08-08", + "vehicleId": "301", + "vehiclePlate": "蒙A88888", + "vehicleModelId": "21", + "vehicleModelName": "丰田汉兰达", + "driverId": "45", + "driverName": "张师傅", + "amount": "950.00", + "paymentMethod": "COMPANY_PAID", + "settlementConfirmStatus": "UNCONFIRMED", + "remark": "实际结算价高于快照", + "voucherUrls": [] + } + ] +} +``` + +**响应**： + +```json +{"code": 200, "message": "success", "data": {"saved": true}, "success": true} +``` + +随后 GET 同一订单 step3/vehicles，`items[].amount` 返回 `"950.00"`。 + +### 8.2 边界情况 —— amount 改为 0.00 仍合法 + +**场景说明**：金额下限为 `0.00`，0 元合法（不是"未填"）。 + +**请求**： + +```http +PUT /v3/admin/order/2084000000000002978/settlement/step3/vehicles +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "items": [ + { + "id": "9001", + "sourceType": "FLEET", + "serviceDate": "2026-08-08", + "vehicleId": "301", + "vehiclePlate": "蒙A88888", + "vehicleModelId": "21", + "vehicleModelName": "丰田汉兰达", + "driverId": "45", + "driverName": "张师傅", + "amount": "0.00", + "paymentMethod": "COMPANY_PAID", + "settlementConfirmStatus": "UNCONFIRMED", + "remark": null, + "voucherUrls": [] + } + ] +} +``` + +**响应**： + +```json +{"code": 200, "message": "success", "data": {"saved": true}, "success": true} +``` + +### 8.3 业务失败 —— 改了 FLEET 行结构字段 vehiclePlate 撞 584109 + +**场景说明**：仅放开 `amount`；结构字段（如车牌）仍受保护。 + +**请求**： + +```http +PUT /v3/admin/order/2084000000000002978/settlement/step3/vehicles +Authorization: Bearer +Content-Type: application/json +``` + +```json +{ + "items": [ + { + "id": "9001", + "sourceType": "FLEET", + "serviceDate": "2026-08-08", + "vehicleId": "301", + "vehiclePlate": "蒙A99999", + "vehicleModelId": "21", + "vehicleModelName": "丰田汉兰达", + "driverId": "45", + "driverName": "张师傅", + "amount": "950.00", + "paymentMethod": "COMPANY_PAID", + "settlementConfirmStatus": "UNCONFIRMED", + "remark": null, + "voucherUrls": [] + } + ] +} +``` + +**响应**： + +```json +{"code": 584109, "message": "车务来源字段不可直接修改或删除", "data": null, "success": false} +``` + +## 9. 业务边界 + +- **适用场景**：FLEET 行 `amount` 可任意改（非负、最多 2 位小数）；改完即生效，**不留审计痕**，与住宿/门票核单人工调价口径一致。 +- **不适用场景**：FLEET 行的结构字段（车牌 / 司机 / 服务日期 / 车型 / 付款方式 / 行 id）仍不允许改；如需换车换司机请走车务派单链路，不要在核单页改。 +- **特殊边界**：`amount` 改为 `0.00` 是合法值，不是"清空"；MANUAL 行的所有字段本就可改，本次无变化。 + +## 10. 修改前后对比 + +### 10.1 字段级对比 + +| 字段 | 原来 | 现在 | +|---|---|---| +| FLEET 行 `amount` | 只读；改值撞 `584109`（PUT 返回 200 但 message 提示、金额不变） | **可编辑**；值合法即落库 | +| FLEET 行结构字段（车牌/司机/日期/车型/付款方式） | 只读，撞 `584109` | 仍只读，撞 `584109`（不变） | +| GET `items[].amount` | 返回 fleet 快照价 | 返回**覆盖层修正后**金额 | + +### 10.2 行为级对比 + +| 行为 | 原来 | 现在 | +|---|---|---| +| 前端把 FLEET 行 amount 改大/改小回传 | 被 `584109` 拦截，金额不变 | 正常保存，GET 回读新值 | +| 前端改 FLEET 行 vehiclePlate | `584109` | `584109`（不变） | + +## 11. 影响评估 / 回滚 + +### 11.1 影响评估 + +- **是否破坏向后兼容**：否。接口签名、字段、错误码零变化；仅放开一个字段的编辑限制。 +- **前端是否必须同步上线**：否。旧前端继续把 amount 渲染为只读输入框不影响功能；但建议尽快放开为可编辑以匹配新口径。 + +### 11.2 回滚方案 + +- 回滚即恢复 amount 只读保护，旧前端（amount 只读）天然兼容；已改为可编辑的新前端在旧后端上保存会重新撞 `584109`，需前后端同批回滚。 + +## 12. 注意事项 + +- 本次仅放开 `amount`；**不要把 FLEET 行其他结构字段也放开为可编辑**。 +- 前端在 FLEET 行编辑表单里，`amount` 用 number input 即可，提交前按"非负、最多 2 位小数"做一次本地校验可减少 400。 +- 若前端历史上有"FLEET 行 amount 改了被静默回滚"的 workaround（如改完强刷 GET 重新渲染），本次后可保留也可简化，无破坏性。 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#5712](https://git.1814.love:8443/wx/HL/issues/5712) +- **PR**: [#5715](https://git.1814.love:8443/wx/HL/pulls/5715) +- **Merge commit**: [d4fce1230](https://git.1814.love:8443/wx/HL/commit/d4fce12309dd3c2ad040ee5d71e9734cb1b8ad5b) + +### 13.2 联系人 + +- **后端负责人**: @yaosutu (yst)