---
schema: "hl-changelog/v2"
ticket: "5697"
title: "行程链接预览恢复真链接（确认执行组级冻结派车方案代际）"
consumer: "admin"
author: "wx"
change_type: "修复"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "后端完成：PR #5700 已合并 dev-v3（e95cfc89a）并部署 TEST（hl-fleet-service 双实例 UP 14:52）。根因两层：①26-8778 确认执行（08-08 11:27）早于 #5681 finalize 逻辑部署（11:40）→ 存量遗留中间态（assigned+generation NULL+finalized=0）→ 预览/短链身份缺失（#5689 已把 500 降级为暂不可，本单恢复真链接）；②confirm 的 finalize 依赖需求级 publishDailySnapshotIfComplete 条件（拓扑全派+无既有代），需求内存在 legacy 遗留行/非最终拓扑时新确认组不冻结。修复：确认执行组级冻结（markDispatchPlanFinalizedForRows：仅确认组、finalized=0 幂等、不退休同需求其他组；legacy 分支锁内重解析当前代，无代签发新代；confirmRequirement 多组沿用 expected 代或一次新代）+ TEST 存量数据修复（26-8778 原行补 generation/finalized）。网关验证：26-8778 渲染 200 返回真链接（改派后新组 t6wpsPy，8/17-8/20，有效期至 08-27）+ render-batch success=true + H5 解析 200（新旧链均正常）。"
updated_at: "2026-08-09"
base: "dev-v3"
generated: "2026-08-08T15:00:00+08:00"
---

# 行程链接预览恢复真链接（#5697）

## 背景

#5675/#5689 修复部署后，26-8778 派单预览行程详情仍显示「行程链接暂不可，联系车务确认」。

## 根因（库表+代码+时间线定位）

1. **存量遗留中间态**：26-8778 确认执行（08-08 11:27:31）早于 #5681 finalize 逻辑部署（11:40）——行保持 assigned + dispatch_plan_generation NULL + finalized=0 → 预览/短链解析身份缺失（#5689 已把 500 降级为「暂不可」，本单恢复真链接）。
2. **代码缺口**：confirm 的 finalize 依赖需求级 `publishDailySnapshotIfComplete` 条件（拓扑全派 + 无既有代）——需求内存在 legacy 遗留行或非最终拓扑时，新确认组不会冻结 → 确认组预览/短链身份仍缺失。

## 修复（PR #5700）

1. `FleetAssignmentMapper.markDispatchPlanFinalizedForRows`：组级冻结——仅确认组行、finalized=0 幂等、不退休同需求其他组（改派/换版仍由 retire/clear 全需求退休）。
2. `confirm` legacy 分支：锁内重解析需求当前代（并发组先冻结则沿用同代），无代签发新 snowflake 代，确认组组级冻结。
3. `confirmRequirement` 原子引擎：多组确认沿用 `expectedPlanGeneration` 或循环外签发一次新代（多组共用），逐个确认组组级冻结。
4. **存量数据修复（TEST）**：26-8778 原行补写 generation/finalized（精确单行 UPDATE + 前后 SELECT 对比）；该行后续（14:33-14:37）被测试改派流程取消，改派新组已带代际（finalized=1）。

## 行为变化

- 确认执行后的派车组（含与 legacy 遗留行共存的场景）预览返回可点行程链接，不再「暂不可」。
- 新 HOLD/DIRECT 派单创建即冻结代际（#5681 既有行为不变）；本修复补充确认执行组级冻结，需求级最终快照事件语义不变。
- 短链解析侧代际升级兼容（哨兵→真实代）不变；取消派车后旧短链随身份失效（既有语义）。

## 前端动作

- 预览区「行程链接暂不可用，请联系车务确认」为业务降级文案：确认执行后（dispatchPlan 冻结前窗口）或派车组身份失效时展示；正常确认后展示可点链接（h5 行程契约页）。
- 无需字段适配；模板渲染接口行为与错误码口径不变。

## 验证证据

- 定向测试：+2（render 确认后已冻结全程行返回真实链接；legacy 遗留行共存时新组确认组级冻结且不误发需求级快照）；confirm 相关 4 用例回归；保险并发确认测试补 stub 回归。
- 全量 verify 3294 tests 0 失败 4 skipped + spotless:check 通过。
- 网关实测（TEST，26-8778）：渲染 200 返回真链接（https://web.test.1814.love:9443/s/t6wpsPy，8/17-8/20，有效期至 08-27）；render-batch 200 + item success=true；H5 短链解析 200（行程契约 V2 全 4 天）。
- 部署：hl-fleet-service dev-v3=e95cfc89a 双实例 UP（14:52）。

## 前端实证确认（2026-08-09 mmg，hl-admin v2.1）

纯后端修复（确认执行组级冻结代际），前端无需改动：

- changelog §前端动作明确「无需字段适配；模板渲染接口行为与错误码口径不变」。
- 已 grep 实证：全 `src/` 无任何行程链接预览 / 「暂不可用」文案 / 短链解析 / `render-batch` / `dispatchPlan` 相关代码——行程链接预览为后端渲染（H5 / 网关）能力，hl-admin 不持有该预览组件或降级文案。
- 预览区「行程链接暂不可用」为后端业务降级文案，正常确认后由后端返回可点 h5 链接，前端无字段适配需求。