changelog-filename-gate / validate (push) Successful in 1s

详情

docs(api): migrate #5216 handoff to schema v2

2026-07-24 15:48:39 +08:00

8.5 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base, generated

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base	generated
hl-changelog/v2	5216	派车看板补充槽位接送路线与就绪摘要	admin	修改接口	deployed	verified	implemented	hl-ui-codex	mmg/hl-ui@41f307090e	hl-ui/v2.1		后端与网关已验证；前端 implemented 状态由前端消费线程维护，本次仅迁移 schema。	2026-07-24	dev-v3	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

影响范围: 车务管理 → 派车看板卡片

业务口径

派车看板卡片本身应足够车务完成日常派车判断，详情页只用于查看更深信息。每张卡对应一个稳定车辆槽位，同时显示当前需求全部槽位的派车进度、该槽位服务范围、接送批次、路线和资料就绪风险。

看板仍按车辆槽位维度返回，不改为订单维度。
只统计订单当前有效用车需求，不混入已驳回、已失活或旧版本需求。
行程或大交通缺失只作风险提示，readiness.blocksAssignment 固定为 false，不改变 canAssign。
卡片接送摘要不返回出行人、接送备注或大交通自由文本备注。

变更接口

GET /admin/fleet/board/orders

请求参数、筛选、排序、分页和 records[] 维度不变；每条 records[] 新增以下字段：

{
  "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。
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；前端按“前端处理清单”接入即可。

8.5 KiB 原始文件 Blame 文件历史 Unescape Escape