From 017cc5cadc2eea52c528678aecad6f0814257abe Mon Sep 17 00:00:00 2001 From: wx <2636507191@qq.com> Date: Sun, 26 Jul 2026 18:19:03 +0800 Subject: [PATCH] fix(changelog): repair #5262 filename gate --- changelog-path-aliases.json | 6 + ...与核单实时接口-修改接口-前端待处理-管理后台.md | 96 ++------------- ...逐日车费与核单实时接口-修改接口-管理后台.md | 112 ++++++++++++++++++ 3 files changed, 127 insertions(+), 87 deletions(-) create mode 100644 changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md diff --git a/changelog-path-aliases.json b/changelog-path-aliases.json index 75ea363..690f295 100644 --- a/changelog-path-aliases.json +++ b/changelog-path-aliases.json @@ -6,6 +6,12 @@ "alias": "changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md", "canonical": "changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-管理后台.md", "reason": "兼容前端消费线程在文件重命名前持久化的稳定路径" + }, + { + "ticket": "5262", + "alias": "changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md", + "canonical": "changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md", + "reason": "修复首次交接文件名包含前端状态导致的 CI 失败，并保留已发布路径兼容入口" } ] } diff --git a/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md b/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md index b7d93d3..c266270 100644 --- a/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md +++ b/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md @@ -11,101 +11,23 @@ frontend_owner: "" frontend_ref: "" target_release: "" verified_at: "2026-07-26T16:37:00+08:00" -status_note: "后端 PR wx/HL#5266 已合并到 dev-v3（9bfd21de6），Fleet/Order 测试双实例已部署并完成管理端网关与 internal Feign 实测；前端仍为 pending，owner/ref 保持为空。本契约替代 #5253 的“手工填写每车总价”口径。" +canonical_path: "changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md" +status_note: "兼容 #5262 首次交接时已发布的稳定路径；状态更新必须通过 alias-aware transition 同步 canonical。" updated_at: "2026-07-26" base: "dev-v3" -generated: "2026-07-26T16:20:00+08:00" --- -# 派车逐日车费、只读总价与核单实时接口 +# 【路径兼容·管理后台】派车逐日车费、只读总价与核单实时接口 -## 关联 - -- Issue: [wx/HL#5262](https://git.1814.love:8443/wx/HL/issues/5262) -- 服务：`hl-fleet-service`、`hl-order-service-v3` -- 前端仓库：`mmg/hl-ui`（本文仅交接，不代表已修改前端） -- 替代口径：[#5253 按车辆记录订单总车费并接入核单](./26_5253_按车辆记录订单总车费并接入核单-修改接口-管理后台.md) - -## 关键变化 - -1. 多日派车按服务日保存 assignment，每个槽位 4 天即 4 条每日记录。 -2. 价格日历改为提供逐日参考价；车务可覆盖本次派车的某日车费，覆盖值不回写价格日历。 -3. `vehicleFeeTotal` 改为只读合计，恒等于收费日 `assignmentPrice` 之和。 -4. 创建、批量派车、确认和改派请求继续兼容解析旧总价字段，但只要传值即返回稳定业务错误，不再接受手工总价。 -5. 配置车辆不写 Order 核单表；核单后端通过新的 Fleet internal API 实时读取逐日车辆费用。 +本文件是 #5262 首次交接路径的兼容入口。完整接口说明以 +`changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md` +为 canonical；不得删除或再次重命名本文件。 ## 变更接口 -| 方法 | 路径 | 变化 | -| --- | --- | --- | -| `POST` | `/admin/fleet/assignments/candidates` | 车辆候选新增逐日车费参考 | -| `POST` | `/admin/fleet/assignments` | 新增 `dailyVehicleFees`；旧 `vehicleFeeTotal` 禁止传值 | -| `POST` | `/admin/fleet/assignments/batch` | 每个最终车辆槽位分别提交 `dailyVehicleFees` | -| `POST` | `/admin/fleet/assignments/:assignmentId/change` | 新派车段提交逐日车费；保留段沿用原逐日快照 | -| `POST` | `/admin/fleet/assignments/:assignmentId/confirm` | 旧总价字段禁止传值；总价由已保存逐日车费只读计算 | -| `GET` | `/admin/fleet/board/orders/:orderId` | 槽位返回 `dailyVehicleFees` 和只读合计 | - -## 请求字段 - -`dailyVehicleFees[]`： - -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| `serviceDate` | `LocalDate` | 是 | 本次覆盖的服务日期 | -| `price` | `Decimal` | 是 | 本次派车单日车费，最小 `0.00`，最多 2 位小数 | - -规则： - -- 未提交覆盖值的收费日使用车型价格日历当天价格。 -- 收费日缺少日历价格且未提交覆盖值时，后端拒绝最终派车。 -- 覆盖值与日历参考价不一致时提交 `vehicleFeeAdjustmentReason`。 -- 免费日期 `assignmentPrice` 固定为 `"0.00"`，不计入总价。 -- `vehicleFeeTotal`、`retainedVehicleFeeTotal` 以及对应旧调整原因字段不得再由前端提交。 - -## 响应字段 - -候选、派车写响应和看板槽位新增或统一返回 `dailyVehicleFees[]`： - -| 字段 | 类型 | 说明 | -| --- | --- | --- | -| `serviceDate` | `LocalDate` | 服务日期 | -| `chargeable` | `Boolean` | 是否收取车费 | -| `calendarPrice` | `Decimal/null` | 车型价格日历参考价；缺价时为空 | -| `assignmentPrice` | `Decimal/null` | 本次派车单日车费；收费日必须有值，免费日为 `"0.00"` | -| `source` | `String` | `CALENDAR` / `OVERRIDE` / `FREE` / `MISSING` | -| `calendarPriceMissing` | `Boolean` | 价格日历是否缺价 | - -`vehicleFeeTotal` 继续返回，但语义变为只读： - -```text -vehicleFeeTotal = sum(dailyVehicleFees[chargeable=true].assignmentPrice) -``` - -金额字段按字符串消费，雪花 ID 继续按字符串消费。 - -## 页面展示矩阵 - -| 区域 | 展示 | 空态 | 状态/颜色 | 守恒规则 | -| --- | --- | --- | --- | --- | -| 收费日期 | 每日显示日历参考价与本次派车价 | 选车前“待计算”；缺价“价格日历缺价” | 参考价中性、覆盖蓝、缺价橙 | 一服务日一条派车记录 | -| 最终总车费 | 只读合计，不渲染金额输入框 | 缺价时“价格不完整” | 正常中性、缺价橙 | 等于全部收费日本次派车价之和 | -| 已结束行程 | 只允许查看逐日价格和总价 | 不适用 | 只读灰 | 前端禁用与后端拒绝一致 | - -## 前端处理清单 - -- [ ] 移除“最终总车费”输入框，改为只读合计。 -- [ ] 收费日期逐日展示 `calendarPrice`，并允许编辑当前槽位的 `assignmentPrice`。 -- [ ] 仅把修改后的日期组装为 `dailyVehicleFees`，不调用车型价格日历写接口。 -- [ ] 使用 `source` 和 `calendarPriceMissing` 展示覆盖与缺价状态。 -- [ ] 创建、批量派车、确认和改派请求不再传旧总价字段。 -- [ ] 行程结束后禁用逐日车费、槽位和改派入口。 +- 不新增或修改业务接口；本文件仅保留已下发路径，并把消费方引导到 canonical 文档。 ## 验证证据 -- OpenAPI/oasdiff：`not_configured`；已完成 Controller/VO 源码比对和 Fleet 接口测试回退证据。 -- Spring Cloud Contract：`not_configured`；已完成 Fleet producer、Order Feign consumer 和 shared DTO 测试回退证据。 -- Fleet：`mvn -pl hl-fleet-service -am verify` 与 `spotless:check` 通过。 -- Order：`mvn -pl hl-order-service-v3 -am verify` 完成，Surefire 零失败并生成可执行 JAR。 -- 部署：Fleet `630858f8`、Order `63f9ba60` 成功，8087/8187 与 8086/8186 双实例健康。 -- 网关：管理端订单详情返回 4 条逐日车费及约定的 6 个逐日字段；internal Feign 正向响应严格为顶层 5 个字段、item 12 个字段。 -- `frontend_status`：`pending`；真实领取后再迁移为 `claimed`。 +- `changelog-path-aliases.json` 记录旧路径与 canonical 的机器可识别关系。 +- alias 校验确保前端状态字段与 canonical 同步。 diff --git a/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md b/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md new file mode 100644 index 0000000..6ee9c84 --- /dev/null +++ b/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md @@ -0,0 +1,112 @@ +--- +schema: "hl-changelog/v2" +ticket: "5262" +title: "派车逐日车费、只读总价与核单实时接口" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-07-26T16:37:00+08:00" +path_aliases: "changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md" +status_note: "后端 PR wx/HL#5266 已合并到 dev-v3（9bfd21de6），Fleet/Order 测试双实例已部署并完成管理端网关与 internal Feign 实测；前端仍为 pending，owner/ref 保持为空。本契约替代 #5253 的“手工填写每车总价”口径。" +updated_at: "2026-07-26" +base: "dev-v3" +generated: "2026-07-26T16:20:00+08:00" +--- + +# 派车逐日车费、只读总价与核单实时接口 + +## 关联 + +- Issue: [wx/HL#5262](https://git.1814.love:8443/wx/HL/issues/5262) +- 服务：`hl-fleet-service`、`hl-order-service-v3` +- 前端仓库：`mmg/hl-ui`（本文仅交接，不代表已修改前端） +- 替代口径：[#5253 按车辆记录订单总车费并接入核单](./26_5253_按车辆记录订单总车费并接入核单-修改接口-管理后台.md) + +## 关键变化 + +1. 多日派车按服务日保存 assignment，每个槽位 4 天即 4 条每日记录。 +2. 价格日历改为提供逐日参考价；车务可覆盖本次派车的某日车费，覆盖值不回写价格日历。 +3. `vehicleFeeTotal` 改为只读合计，恒等于收费日 `assignmentPrice` 之和。 +4. 创建、批量派车、确认和改派请求继续兼容解析旧总价字段，但只要传值即返回稳定业务错误，不再接受手工总价。 +5. 配置车辆不写 Order 核单表；核单后端通过新的 Fleet internal API 实时读取逐日车辆费用。 + +## 变更接口 + +| 方法 | 路径 | 变化 | +| --- | --- | --- | +| `POST` | `/admin/fleet/assignments/candidates` | 车辆候选新增逐日车费参考 | +| `POST` | `/admin/fleet/assignments` | 新增 `dailyVehicleFees`；旧 `vehicleFeeTotal` 禁止传值 | +| `POST` | `/admin/fleet/assignments/batch` | 每个最终车辆槽位分别提交 `dailyVehicleFees` | +| `POST` | `/admin/fleet/assignments/:assignmentId/change` | 新派车段提交逐日车费；保留段沿用原逐日快照 | +| `POST` | `/admin/fleet/assignments/:assignmentId/confirm` | 旧总价字段禁止传值；总价由已保存逐日车费只读计算 | +| `GET` | `/admin/fleet/board/orders/:orderId` | 槽位返回 `dailyVehicleFees` 和只读合计 | + +## 请求字段 + +`dailyVehicleFees[]`： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `serviceDate` | `LocalDate` | 是 | 本次覆盖的服务日期 | +| `price` | `Decimal` | 是 | 本次派车单日车费，最小 `0.00`，最多 2 位小数 | + +规则： + +- 未提交覆盖值的收费日使用车型价格日历当天价格。 +- 收费日缺少日历价格且未提交覆盖值时，后端拒绝最终派车。 +- 覆盖值与日历参考价不一致时提交 `vehicleFeeAdjustmentReason`。 +- 免费日期 `assignmentPrice` 固定为 `"0.00"`，不计入总价。 +- `vehicleFeeTotal`、`retainedVehicleFeeTotal` 以及对应旧调整原因字段不得再由前端提交。 + +## 响应字段 + +候选、派车写响应和看板槽位新增或统一返回 `dailyVehicleFees[]`： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `serviceDate` | `LocalDate` | 服务日期 | +| `chargeable` | `Boolean` | 是否收取车费 | +| `calendarPrice` | `Decimal/null` | 车型价格日历参考价；缺价时为空 | +| `assignmentPrice` | `Decimal/null` | 本次派车单日车费；收费日必须有值，免费日为 `"0.00"` | +| `source` | `String` | `CALENDAR` / `OVERRIDE` / `FREE` / `MISSING` | +| `calendarPriceMissing` | `Boolean` | 价格日历是否缺价 | + +`vehicleFeeTotal` 继续返回，但语义变为只读： + +```text +vehicleFeeTotal = sum(dailyVehicleFees[chargeable=true].assignmentPrice) +``` + +金额字段按字符串消费，雪花 ID 继续按字符串消费。 + +## 页面展示矩阵 + +| 区域 | 展示 | 空态 | 状态/颜色 | 守恒规则 | +| --- | --- | --- | --- | --- | +| 收费日期 | 每日显示日历参考价与本次派车价 | 选车前“待计算”；缺价“价格日历缺价” | 参考价中性、覆盖蓝、缺价橙 | 一服务日一条派车记录 | +| 最终总车费 | 只读合计，不渲染金额输入框 | 缺价时“价格不完整” | 正常中性、缺价橙 | 等于全部收费日本次派车价之和 | +| 已结束行程 | 只允许查看逐日价格和总价 | 不适用 | 只读灰 | 前端禁用与后端拒绝一致 | + +## 前端处理清单 + +- [ ] 移除“最终总车费”输入框，改为只读合计。 +- [ ] 收费日期逐日展示 `calendarPrice`，并允许编辑当前槽位的 `assignmentPrice`。 +- [ ] 仅把修改后的日期组装为 `dailyVehicleFees`，不调用车型价格日历写接口。 +- [ ] 使用 `source` 和 `calendarPriceMissing` 展示覆盖与缺价状态。 +- [ ] 创建、批量派车、确认和改派请求不再传旧总价字段。 +- [ ] 行程结束后禁用逐日车费、槽位和改派入口。 + +## 验证证据 + +- OpenAPI/oasdiff：`not_configured`；已完成 Controller/VO 源码比对和 Fleet 接口测试回退证据。 +- Spring Cloud Contract：`not_configured`；已完成 Fleet producer、Order Feign consumer 和 shared DTO 测试回退证据。 +- Fleet：`mvn -pl hl-fleet-service -am verify` 与 `spotless:check` 通过。 +- Order：`mvn -pl hl-order-service-v3 -am verify` 完成，Surefire 零失败并生成可执行 JAR。 +- 部署：Fleet `630858f8`、Order `63f9ba60` 成功，8087/8187 与 8086/8186 双实例健康。 +- 网关：管理端订单详情返回 4 条逐日车费及约定的 6 个逐日字段；internal Feign 正向响应严格为顶层 5 个字段、item 12 个字段。 +- `frontend_status`：`pending`；真实领取后再迁移为 `claimed`。