diff --git a/changelogs-v2/2026-08/08_5675_行程单在派单消息预览时即生成可见(不等派车成功后)-修改接口-管理后台.md b/changelogs-v2/2026-08/08_5675_行程单在派单消息预览时即生成可见(不等派车成功后)-修改接口-管理后台.md new file mode 100644 index 0000000..bd0b795 --- /dev/null +++ b/changelogs-v2/2026-08/08_5675_行程单在派单消息预览时即生成可见(不等派车成功后)-修改接口-管理后台.md @@ -0,0 +1,79 @@ +--- +schema: "hl-changelog/v2" +ticket: "5675" +title: "行程单在派单消息预览时即生成可见(不等派车成功后)" +consumer: "admin" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +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 ✓