---
schema: "hl-changelog/v2"
ticket: "5216"
title: "派车看板补充槽位接送路线与就绪摘要"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@cd493f83a7881401552494fc5a90fbb87395131b"
target_release: "hl-ui/v2.1"
verified_at: ""
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"
---

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

## 目标前端

- 端类型：管理后台（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` 计算。
- 不修改派单详情、矩阵派单、司机车辆占用、保险和费用。
- 不迁移数据库，不写入订单、行程、大交通或派单数据。

## 验证证据

- 后端提交：`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`；前端按“前端处理清单”接入即可。
