恢复管理后台 changelog 完整正文

2026-07-27 10:27:17 +08:00 · 2026-07-27 10:27:17 +08:00 · 450c9a6dfc
--- a/changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-管理后台.md
@ -11,23 +11,189 @@ frontend_owner: "hl-ui-codex"
 frontend_ref: "mmg/hl-ui@cd493f83a7881401552494fc5a90fbb87395131b"
 target_release: "hl-ui/v2.1"
 verified_at: ""
-canonical_path: "changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-管理后台.md"
-status_note: "兼容 #5216 在文件重命名前已被前端消费线程持久化的稳定路径；状态更新必须通过 alias-aware transition 同步 canonical。"
+path_aliases: "changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md"
+status_note: "后端与网关已验证；前端 implemented 状态由前端消费线程维护，本次仅迁移 schema。"
 updated_at: "2026-07-26"
 base: "dev-v3"
+generated: "2026-07-24T14:24:00+08:00"
 ---

-# 【路径兼容·管理后台】派车看板补充槽位接送路线与就绪摘要
+# 【修改接口·前端待处理·管理后台】派车看板补充槽位接送路线与就绪摘要

-本文件是 #5216 已下发旧路径的兼容入口。完整接口说明以
-`changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-管理后台.md`
-为 canonical；不得删除或再次重命名本文件。
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 目标分支：`v2.1`
+- 联调/验收环境：<http://192.168.100.160:9527>
+- 小程序：无需处理
+
+> **服务**: hl-order-service-v3、hl-fleet-service
+>
+> **工单**: [wx/HL#5216](https://git.1814.love:8443/wx/HL/issues/5216)
+>
+> **影响范围**: 车务管理 → 派车看板卡片
+
+## 业务口径
+
+派车看板卡片本身应足够车务完成日常派车判断，详情页只用于查看更深信息。每张卡对应一个稳定车辆槽位，
+同时显示当前需求全部槽位的派车进度、该槽位服务范围、接送批次、路线和资料就绪风险。
+
+- 看板仍按车辆槽位维度返回，不改为订单维度。
+- 只统计订单当前有效用车需求，不混入已驳回、已失活或旧版本需求。
+- 行程或大交通缺失只作风险提示，`readiness.blocksAssignment` 固定为 `false`，不改变 `canAssign`。
+- 卡片接送摘要不返回出行人、接送备注或大交通自由文本备注。

 ## 变更接口

- 不新增或修改业务接口；本文件仅恢复前端状态回写所需的稳定路径。
+```http
+GET /admin/fleet/board/orders
+```
+
+请求参数、筛选、排序、分页和 `records[]` 维度不变；每条 `records[]` 新增以下字段：
+
+```json
+{
+  "assignmentSlotId": "2080200000000000001",
+  "slotSummary": {
+    "assignmentSlotId": "2080200000000000001",
+    "slotIndex": 2,
+    "totalSlots": 3,
+    "serviceStartDate": "2026-07-29",
+    "serviceEndDate": "2026-07-31",
+    "serviceDays": 3,
+    "requiredVehicleType": "mpv",
+    "requiredVehicleTypeLabel": "商务车",
+    "requiredSeats": 7
+  },
+  "assignmentProgress": {
+    "totalSlots": 3,
+    "unassignedSlots": 1,
+    "holdingSlots": 1,
+    "assignedSlots": 1,
+    "completedSlots": 0,
+    "canceledSlots": 0
+  },
+  "pickupSummary": {
+    "required": true,
+    "statusCode": "PARTIAL",
+    "statusLabel": "接客信息部分缺失",
+    "batchCount": 2,
+    "readyBatchCount": 1,
+    "transportNos": ["MU8345", "K7091"],
+    "earliestTime": "2026-07-29T10:30:00",
+    "latestTime": "2026-07-29T15:20:00",
+    "stations": ["海拉尔机场"]
+  },
+  "dropoffSummary": {
+    "required": true,
+    "statusCode": "READY",
+    "statusLabel": "送客信息已齐",
+    "batchCount": 1,
+    "readyBatchCount": 1,
+    "transportNos": ["CA1234"],
+    "earliestTime": "2026-07-31T18:00:00",
+    "latestTime": "2026-07-31T18:00:00",
+    "stations": ["海拉尔站"]
+  },
+  "routeSummary": "海拉尔区 → 额尔古纳市 → 满洲里市",
+  "daysUntilDeparture": 5,
+  "readiness": {
+    "statusCode": "PARTIAL",
+    "statusLabel": "部分信息待补",
+    "itineraryStatusCode": "READY",
+    "itineraryStatusLabel": "行程已完整",
+    "itineraryDayCount": 3,
+    "itineraryExpectedDayCount": 3,
+    "missingItemCodes": ["PICKUP_TRANSFER"],
+    "missingItemLabels": ["接客信息"],
+    "blocksAssignment": false
+  }
+}
+```
+
+### 当前槽位 `slotSummary`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `assignmentSlotId` | `String` | 稳定车辆槽位 ID，按雪花 ID 字符串处理 |
+| `slotIndex` | `Integer/null` | 当前槽位序号，**从 1 开始** |
+| `totalSlots` | `Integer` | 当前有效需求车辆槽位总数 |
+| `serviceStartDate/serviceEndDate` | `LocalDate/null` | 当前槽位实际服务范围 |
+| `serviceDays` | `Integer/null` | 服务范围闭区间天数 |
+| `requiredVehicleType` | `String/null` | 当前槽位车型规范编码 |
+| `requiredVehicleTypeLabel` | `String` | 当前槽位车型中文标签 |
+| `requiredSeats` | `Integer/null` | 当前槽位要求座位数 |
+
+不要用既有整单 `requiredVehicles[]` 的数组位置猜当前卡片车型；当前卡片只读取 `slotSummary`。
+
+### 整单进度 `assignmentProgress`
+
+`assignmentProgress` 基于当前有效需求的全部稳定槽位计算，不受本次列表状态、车型、日期或关键词筛选影响。
+前端可直接展示“3 车：待派 1 / 排车中 1 / 已派 1”，不要用当前页 `records[]` 自行计数。
+
+### 接送摘要 `pickupSummary/dropoffSummary`
+
+| `statusCode` | 含义 |
+| --- | --- |
+| `READY` | 所有批次时间和站点均完整 |
+| `PARTIAL` | 至少一个批次完整，但仍有批次缺时间或站点 |
+| `MISSING` | 当前要求该方向接送，但没有完整批次 |
+| `NOT_REQUIRED` | 当前用车需求明确不要求该方向接送 |
+| `SOURCE_UNAVAILABLE` | order-v3 暂不可用，不能把它显示成“无需接送”或“资料已齐” |
+
+`pickupAt/dropoffAt` 兼容字段继续保留；订单实时上下文可用时，优先回填对应方向第一个有效站点。
+
+### 行程与就绪度
+
+- `routeSummary` 按行程天顺序生成，并压缩连续重复地点；无地点时为 `null`。
+- `daysUntilDeparture` 是服务端当前日期到出团日的自然日数；负数表示已出团。
+- `readiness.statusCode` 为 `READY/PARTIAL/MISSING/SOURCE_UNAVAILABLE`。
+- `missingItemCodes` 当前可能包含：
+  - `ORDER_CONTEXT`：订单实时信息不可用；
+  - `ITINERARY_DAYS`：逐日行程缺失、天数不完整或日期仍是旧档期；
+  - `ROUTE_SUMMARY`：行程天没有可用地点；
+  - `PICKUP_TRANSFER`：要求接客但资料不完整；
+  - `DROPOFF_TRANSFER`：要求送客但资料不完整。
+
+页面使用后端 `statusLabel/missingItemLabels` 展示中文，不自行翻译状态码。
+
+## 前端处理清单
+
+- [ ] 卡片主信息区展示“第 `slotIndex/totalSlots` 车”、车型标签、座位数和槽位服务日期。
+- [ ] 展示 `assignmentProgress` 整单进度，不按当前页或筛选后记录重新计算。
+- [ ] 分别展示接客和送客摘要；多批次显示批次数、班次/车次、时间范围和站点。
+- [ ] `NOT_REQUIRED` 显示“无需接客/无需送客”，`SOURCE_UNAVAILABLE` 显示“信息暂不可用”。
+- [ ] 展示 `routeSummary`、`daysUntilDeparture` 和 `readiness` 风险提示。
+- [ ] 资料缺失时不得禁用派车按钮；操作能力继续只读 `canAssign/availableActionCodes`。
+- [ ] 不在卡片展示出行人、接送备注、大交通备注等敏感或自由文本信息。
+- [ ] `assignmentSlotId/assignmentId/assignmentGroupId/requirementId/orderId` 均按字符串处理。
+- [ ] 覆盖单车、多车、部分已派、多批次接送、无需接送、资料缺失和下游降级场景。
+
+## 不影响范围
+
+- 不修改派车看板请求参数、分页、筛选、排序和操作接口。
+- 不修改 `canAssign/canRejectRequirement/availableActionCodes` 计算。
+- 不修改派单详情、矩阵派单、司机车辆占用、保险和费用。
+- 不迁移数据库，不写入订单、行程、大交通或派单数据。

 ## 验证证据

- `changelog-path-aliases.json` 记录旧路径与 canonical 的机器可识别关系。
- alias 校验与状态同步测试覆盖读取、同步写入和重复写入。
+- 后端提交：`e73740c57caf295cac96d964e540279f581f1fb0`；PR：
+  [wx/HL#5221](https://git.1814.love:8443/wx/HL/pulls/5221)。
+- `mvn -pl hl-fleet-service -am verify` 通过：2354 tests，0 failures/errors，skipped 1；
+  Spotless 603 files clean。
+- `OrderFleetProviderServiceTest` 33 项、`BoardOrderServiceTest` 48 项及
+  `AssignmentServiceTest` 稳定槽位聚合测试均通过。
+- `mvn -pl hl-order-service-v3 -am verify` 共执行 6643 tests，其中 6642 项通过；
+  唯一错误是上游 `SettlementFinancialChecksMigrationTest` 在当前环境无法发现 Docker，
+  与本次接口变更无关。Issue #5216 的对应验收项因此仍保持未勾选。
+- 功能分支部署任务：order-v3 `d0e26c90`、fleet `a4776dfa`，均成功完成双实例滚动部署。
+- 经测试网关实测 `GET /admin/fleet/board/orders?page=1&pageSize=20`：HTTP 200，返回 3 条真实记录；
+  8 个新增字段在 3 条记录中全部存在且非空，观测到就绪状态 `PARTIAL`，接送状态
+  `READY/MISSING`。
+- Nacos 实测：`hl-order-service-v3` 8086/8186、`hl-fleet-service` 8087/8187 均为 2/2 健康；
+  四个新实例均有正常启动记录，启动后的运行日志未发现新增 ERROR、FATAL、Exception 或
+  `Caused by`。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`；前端按“前端处理清单”接入即可。
--- a/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md
@ -11,23 +11,102 @@ frontend_owner: "hl-ui-pi"
 frontend_ref: "mmg/hl-ui@2dfe8ab40f3db446d0a079d7511986a2d7fdce33"
 target_release: ""
 verified_at: "2026-07-26T16:37:00+08:00"
-canonical_path: "changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md"
-status_note: "兼容 #5262 首次交接时已发布的稳定路径；状态更新必须通过 alias-aware transition 同步 canonical。"
+path_aliases: "changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md"
+status_note: "后端 PR wx/HL#5266 已合并到 dev-v3（9bfd21de6），Fleet/Order 测试双实例已部署并完成管理端网关与 internal Feign 实测；hl-admin 已在 2dfe8ab40f3db446d0a079d7511986a2d7fdce33 接入逐日车费、只读总价和旧字段移除，verify:changed 通过，尚未发布及页面联调。本契约替代 #5253 的“手工填写每车总价”口径。"
 updated_at: "2026-07-26"
 base: "dev-v3"
+generated: "2026-07-26T16:20:00+08:00"
 ---

-# 【路径兼容·管理后台】派车逐日车费、只读总价与核单实时接口
+# 派车逐日车费、只读总价与核单实时接口

-本文件是 #5262 首次交接路径的兼容入口。完整接口说明以
-`changelogs-v2/2026-07/26_5262_派车逐日车费与核单实时接口-修改接口-管理后台.md`
-为 canonical；不得删除或再次重命名本文件。
+## 关联
+
+- 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 实时读取逐日车辆费用。

 ## 变更接口

- 不新增或修改业务接口；本文件仅保留已下发路径，并把消费方引导到 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` 展示覆盖与缺价状态。
+- [ ] 创建、批量派车、确认和改派请求不再传旧总价字段。
+- [ ] 行程结束后禁用逐日车费、槽位和改派入口。

 ## 验证证据

- `changelog-path-aliases.json` 记录旧路径与 canonical 的机器可识别关系。
- alias 校验确保前端状态字段与 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`。