---
schema: "hl-changelog/v2"
ticket: "5675"
title: "行程单在派单消息预览时即生成可见（不等派车成功后）"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5685/#5687/#5688 已合并 dev-v3 并部署 TEST（hl-fleet-service 双实例）。预览/HOLD 通知即生成可点行程短链，短码跨确认稳定，确认前行程单已可打开。前端交接见下（预览定位参数与降级文案口径）。"
updated_at: "2026-08-08"
base: "dev-v3"
generated: "2026-08-08T11:20:00+08:00"
---

# 行程单在派单消息预览时即生成可见（不等派车成功后）

> 后端完成：PR [#5685](https://git.1814.love:8443/wx/HL/pulls/5685) / [#5687](https://git.1814.love:8443/wx/HL/pulls/5687) / [#5688](https://git.1814.love:8443/wx/HL/pulls/5688) 已合并 dev-v3 并部署 TEST，网关端到端验证通过。

## 关联 / 联系人

### 链接

- **Issue**: [#5675](https://git.1814.love:8443/wx/HL/issues/5675)
- **PR**: #5685（主）/ #5687（单行组定位配套）/ #5688（中间态容错配套）
- **Merge commit**: [cb44851c9](https://git.1814.love:8443/wx/HL/commit/cb44851c9)

### 联系人

- **后端负责人**: @wx

## 背景

派单消息预览里行程详情显示「行程链接在派单成功后自动生成」——预览时看不到行程单/链接，司机收到的 HOLD 待确认通知也是「行程确认后发送」占位文案。wx 要预览/通知时就有可点行程单链接。

## 变更说明（无接口契约变化，行为升级）

### 行为变化

| 场景 | 变更前 | 变更后 |
|------|--------|--------|
| 派单消息预览（组可定位） | 「行程链接在派单成功后自动生成」占位 | **真实可点短链** `https://…/s/{code}` |
| HOLD 待确认通知（司机收到） | 「行程确认后发送」占位 | **真实可点短链**，确认前即可打开行程单 |
| 司机确认后点同一短链 | —（此前无链接） | 短码不变，仍可打开（代际升级兼容，按当前身份重签） |
| 派单创建前的纯模板预览（无派单上下文） | 占位文案 | 不变（此时车辆/司机未定，无行程可链） |
| 增删槽位/重新确认窗口内的预览 | 500（缺陷） | 「行程链接暂不可用，请联系车务确认」降级文案 |

### 后端实现（hl-fleet-service）

1. **HOLD 待确认组可签发行程 token**（`ItineraryTokenService`）：全组 HOLDING 且未冻结 dispatchPlan 时豁免 generation 非空/finalized=1 校验，代际用稳定哨兵 `PENDING(0L)`；混合状态未冻结组仍拒绝（失败关闭）。
2. **短码跨确认稳定**（`ItineraryShortLinkService.resolveShortLink`）：同组同业务（车/司机/槽位/服务日/旅客快照全同）仅代际升级（PENDING→真实 generation）时放行，按当前身份重签 H5 token；换车/换司机/改期/取消仍失败关闭。
3. **HOLD 态 H5 可渲染**（`ItineraryH5Service`）：全组 HOLDING + PENDING 代际 token 放行。
4. **HOLD 通知冻结真链接**（`AssignmentHoldNotificationSnapshotFactory`）：不再降级占位（#5461 口径演进）。
5. **单行组/全程行定位适配**（`MessageTemplateRenderService`，#5675 配套）：effective 组 id（group_id NULL→assignment_id，#5589 口径）+ 全程行 tripEndDate 取 endDate + 身份未就绪中间态容错降级。
6. **全程行 serviceDates 展开**（`effectiveServiceDates`）：service_date NULL 的全程行按服务期逐日展开，签发与 H5 校验同口径。

## 前端交接

1. **预览要拿真链接，请求需能定位派车组**（三选一）：传 `assignmentGroupId`；或传 `orderId + vehicleId + driverId`（能唯一命中 active 组时自动定位）。都不传的纯模板预览仍显示占位文案（正常——无派单上下文）。
2. **降级文案口径**：`itinerary.url` 可能返回两种文案——「行程链接在派单成功后自动生成」（无派单上下文）/「行程链接暂不可用，请联系车务确认」（组在重新确认窗口等中间态）。前端按文本展示即可，无需特殊处理。
3. **通知文案**：HOLD 待确认通知中行程详情现在直接是可点短链，司机确认前后点同一链接均可见行程单。
4. 短链有效期=行程结束 +7 天（既有口径不变）。

## 验证证据

- **单测**：token 层 +3（HOLD 未冻结可签发/混合状态仍拒绝/全程行展开）、短链层 +2（代际升级放行/换司机失败关闭）、H5 层 +2（HOLD 渲染可见/finalize 后旧 token 失效）、预览链 +2（单行组定位/中间态容错）、快照工厂更新为 HOLD 签发真链接；messagetemplate+h5 **396/396**、assignment 相关 **444/444** 全绿；spotless 通过
- **fleet verify**（mvn-throttle 错峰）：仅基线/环境项失败（ReleaseEOccupancyMysql8033 等 3 个需 mysql:8.0.33 Testcontainers；ReleaseEMixedBinaryHarness flaky 复跑全绿），与本案无关
- **部署**：hl-fleet-service 双实例 UP（11:16）
- **网关端到端**（TEST，VEHICLE_MANAGER）：
  - HOLD 待确认派单（全程槽单行组）render → 返回真短链 `https://web.test.1814.love:9443/s/txU62dA`（非占位）✓
  - 同组幂等重放复用同码 ✓
  - 短链 302 → H5 长链（token payload：PENDING 哨兵代际 + 全程行展开 3 个服务日）✓
  - GET H5 长链 → 200 行程单 JSON（主题/日期/服务日/客户全渲染）——**确认前行程单即可见** ✓
  - 中间态组（增删槽位重新确认窗口）render → 降级文案，不再 500 ✓
