From 92093b73684f6ce93fd45c1e8b7875d9e4e70fcb Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 24 Jul 2026 15:12:42 +0800 Subject: [PATCH] docs(api): hand off fleet board decision summary (#5216) --- ...接送路线与就绪摘要-修改接口-前端待处理-管理后台.md | 191 ++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md diff --git a/changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md b/changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md new file mode 100644 index 0000000..afc7b10 --- /dev/null +++ b/changelogs-v2/2026-07/24_5216_派车看板补充槽位接送路线与就绪摘要-修改接口-前端待处理-管理后台.md @@ -0,0 +1,191 @@ +--- +schema: "hl-changelog/v1" +ticket: "5216" +title: "派车看板补充槽位接送路线与就绪摘要" +consumer: "admin" +backend: "verified" +gateway: "verified" +frontend: "pending" +base: "dev-v3" +generated: "2026-07-24T14:24:00+08:00" +--- + +# 【修改接口·前端待处理·管理后台】派车看板补充槽位接送路线与就绪摘要 + +## 目标前端 + +- 端类型：管理后台（Web） +- 目标仓库：`mmg/hl-ui` +- 目标分支：`v2.1` +- 联调/验收环境： +- 小程序：无需处理 + +> **服务**: 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` 计算。 +- 不修改派单详情、矩阵派单、司机车辆占用、保险和费用。 +- 不迁移数据库，不写入订单、行程、大交通或派单数据。 + +## 验证证据 + +- 后端提交：`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`；前端按“前端处理清单”接入即可。