hl-api-changelog/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md

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

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
hl-changelog/v2	5245	行程短链预览与同槽位改派解析	admin	修改接口	pending	pending	pending					后端正在交付；前端需把派单选择改为批量 items[]，并按 activeAssignments[] 展示全部车辆与司机。	2026-07-25	dev-v3

车务：行程短链预览与同槽位改派解析

服务: hl-fleet-service

工单: wx/HL#5245

后端 PR: 待创建

影响范围: 车务管理 → 派车弹窗通知预览、车辆/司机批量选择、派单详情

关键变化

• 通知模板预览中的 itinerary.url 改为派车组稳定短链 https://{短链域}/s/{code}，不再把完整 HMAC token URL 放进预览正文。
• 既有短链和完整 token 长链在原派车组失效后，只允许解析到同一订单、同一 assignmentSlotId 的唯一当前有效派车组；跨订单、跨槽位、无有效派单或同槽位存在多个 active 派车组时继续返回 605308。
• 批量派单和详情多司机字段是既有契约，本次明确前端消费口径：一次提交 items[]，详情展示 activeAssignments[]，不得只处理兼容代表字段 currentAssignment。

变更接口

方法	路径	本次口径
POST	/admin/fleet/message-templates/{templateId}/render	itinerary.url 预览改为稳定短链；无法唯一定位派车组时显示明确不可用文案
GET	/app/h5/s/{code}	继续生成短时 token 并重定向；同槽位改派后的解析由行程接口完成
GET	/app/h5/itinerary/{token}	原组失效后仅回退同订单、同稳定槽位的唯一 active 派车组
POST	/admin/fleet/assignments/batch	既有：按 items[] 一次提交多个车辆/司机槽位
GET	/admin/fleet/board/orders/{orderId}	既有：按 activeAssignments[] 返回全部当前有效派车组

1. 通知模板预览

POST /admin/fleet/message-templates/{templateId}/render

请求和响应字段结构不变。前端在预览包含 itinerary.url 或 itinerary.code 的模板时，应同时传：

字段	类型	必填	说明
orderId	string	是	订单雪花 ID
vehicleId	string	是	当前车辆雪花 ID
driverId	string	是	当前司机雪花 ID

三者必须唯一定位当前 holding 或 assigned 派车组。成功时：

{
  "code": 200,
  "data": {
    "renderedBody": "请查看行程：https://hr.1814.love/s/Dabc1234",
    "variablesUsed": ["itinerary.url"]
  }
}

缺参、无匹配、多匹配、短链配置缺失或短链写入失败时，itinerary.url 使用 “行程链接暂不可用，请联系车务确认”，itinerary.code 为空字符串；不会回退完整 HMAC URL。

2. 同稳定槽位改派后的旧链接

短链先通过 /app/h5/s/{code} 重定向到短时 token；短链与直接保存的完整 token 最终都进入 /app/h5/itinerary/{token}，因此使用同一组回退规则：

token 原派单与当前派单	结果
原派车组仍有 holding / assigned 服务日	使用原派车组当前 active 视图
原组失效，同 orderId + 同 assignmentSlotId 恰有一个 active 组	使用当前改派组
仅有其他订单或其他槽位的 active 组	605308
同槽位无 active 组	605308
同槽位存在多个 active 组	605308，失败封闭

本次不改变 token 签名、有效期、短链 code 结构或错误码。

3. 前端多车辆/多司机消费

批量派单

POST /admin/fleet/assignments/batch

每个已选车辆槽位生成一个 items[] 元素，所有槽位一次提交：

{
  "orderId": "2080000000000000001",
  "requirementId": "2080000000000000002",
  "startDate": "2026-07-29",
  "endDate": "2026-07-31",
  "holdMode": 1,
  "requestId": "assign-2080000000000000001-v1",
  "items": [
    {
      "fleetItemIndex": 0,
      "vehicleId": "2080000000000000101",
      "driverId": "2080000000000000201"
    },
    {
      "fleetItemIndex": 1,
      "vehicleId": "2080000000000000102",
      "driverId": "2080000000000000202"
    }
  ]
}

• fleetItemIndex 从 0 开始，对应需求展开后的稳定车辆槽位。
• vehicleId、driverId 必填；雪花 ID 全程按字符串处理。
• protocolPrice、messageTemplateId、customBody、confirmCrossResident 是单槽位可选字段。
• 不得为每辆车循环调用单条 POST /admin/fleet/assignments 代替批量接口。

派单详情

GET /admin/fleet/board/orders/{orderId}

按 data.activeAssignments[] 渲染每个有效派车组，至少消费：

字段	用途
assignmentGroupId	派车组稳定展示 key
assignmentSlotId	同一需求车辆槽位的稳定身份
fleetItemIndex	槽位顺序
vehicleId / vehiclePlate / vehicleModel	车辆展示
driverId / driverName / driverPhone	司机展示；电话已脱敏
assignmentStatus / assignmentStatusLabel	当前有效状态
lifecycleStageCode	生命周期阶段

currentAssignment 仅为兼容代表项，不能用来判断订单只有一辆车或只展示一名司机。 activeAssignments 无数据时使用空列表空态，不复制代表项凑数。

前端展示矩阵

场景	数据源	页面行为
通知预览唯一命中 active 派车组	renderedBody 中的 itinerary.url	展示稳定短链
通知预览无法唯一命中	明确不可用文案	保留文案并阻止把它当可发送链接
一单多个车辆槽位	items[]	每个槽位各选一辆车和一名司机，一次批量提交
详情有多个 active 派车组	activeAssignments[]	按槽位逐项展示车辆、司机、脱敏电话和状态
详情无 active 派车组	activeAssignments=[]	展示无有效派单空态

前端处理清单

• 派车弹窗支持选择多个车辆槽位，并为每个槽位选择司机。
• 统一提交 POST /admin/fleet/assignments/batch 的 items[]，保留批次级 requestId。
• 通知预览传入当前槽位的 orderId、vehicleId、driverId，只把真实短链视为可发送链接。
• 派单详情按 activeAssignments[] 展示全部车辆/司机，不只读 currentAssignment。
• 司机电话使用后端脱敏值，雪花 ID 始终按字符串处理。
• 覆盖无 active、多 active、短链不可用等空态/失败封闭场景。

验证证据

• OpenAPI/oasdiff：not_configured。项目未配置可复现的 Swagger2 → OAS3 导出与 oasdiff 基线； 本次字段结构不变，使用源码语义比对、Controller/Service 定向测试与测试网关证据兜底。
• 消费者契约/Spring Cloud Contract：not_required。本次没有内部 Feign 或共享 Java DTO 变化。
• 后端定向测试：307 项通过，0 失败、0 错误、0 跳过。
• Fleet Spotless：606 个 Java 文件检查通过。
• 完整 reactor verify、后端 PR、测试部署与网关证据将在后端交付后补充。

不影响范围

• 不修改或部署 D:/work2/hl-ui。
• 不新增、不删除 API 字段，不改变字段类型、必填性或枚举。
• 不修改批量派单事务、价格、跨常驻确认、保险或通知冻结规则。
• 不新增 DDL，不清理、不回填存量数据。

frontend_status: pending 表示等待前端真实领取；不代表页面已实现、发布或验证。