docs(fleet): correct shortlink preview contract (#5245)

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

@@ -40,7 +40,7 @@ base: "dev-v3"
 
 | 方法 | 路径 | 本次口径 |
 | --- | --- | --- |
-| `POST` | `/admin/fleet/message-templates/{templateId}/render` | `itinerary.url` 预览改为稳定短链；无法唯一定位派车组时显示明确不可用文案 |
+| `POST` | `/admin/fleet/message-templates/{templateId}/render` | 请求新增可选 `assignmentGroupId`；`itinerary.url` 读取该派车组已冻结的稳定短链 |
 | `GET` | `/app/h5/s/{code}` | 继续生成短时 token 并重定向；同槽位改派后的解析由行程接口完成 |
 | `GET` | `/app/h5/itinerary/{token}` | 原组失效后仅回退同订单、同稳定槽位的唯一 active 派车组 |
 | `POST` | `/admin/fleet/assignments/batch` | 既有：按 `items[]` 一次提交多个车辆/司机槽位 |
@@ -52,15 +52,17 @@ base: "dev-v3"
 POST /admin/fleet/message-templates/{templateId}/render
 ```
 
-请求和响应字段结构不变。前端在预览包含 `itinerary.url` 或 `itinerary.code` 的模板时，应同时传：
+请求新增可选字段 `assignmentGroupId`，响应结构不变。前端在预览包含
+`itinerary.url` 或 `itinerary.code` 的模板时，应传入当前派车组 ID：
 
 | 字段 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `orderId` | `string` | 是 | 订单雪花 ID |
-| `vehicleId` | `string` | 是 | 当前车辆雪花 ID |
-| `driverId` | `string` | 是 | 当前司机雪花 ID |
+| `vehicleId` | `string` | 是 | 当前派车组车辆雪花 ID |
+| `driverId` | `string` | 是 | 当前派车组司机雪花 ID |
+| `assignmentGroupId` | `string` | 行程预览时是 | 派车组雪花 ID；取自批量派单响应，不得用车辆/司机组合反推 |
 
-三者必须唯一定位当前 `holding` 或 `assigned` 派车组。成功时：
+`assignmentGroupId` 命中已冻结短链时：
 
 ```json
 {
@@ -72,8 +74,9 @@ POST /admin/fleet/message-templates/{templateId}/render
 }
 ```
 
-缺参、无匹配、多匹配、短链配置缺失或短链写入失败时，`itinerary.url` 使用
-“行程链接暂不可用，请联系车务确认”，`itinerary.code` 为空字符串；不会回退完整 HMAC URL。
+未传 `assignmentGroupId`、派车组未冻结短链、短链不存在或读取失败时，
+`itinerary.url` 使用“行程短链将在派车后生成”，`itinerary.code` 为空字符串；
+预览接口不新建短链，也不会回退或暴露完整 HMAC URL。
 
 ## 2. 同稳定槽位改派后的旧链接
 
@@ -127,6 +130,8 @@ POST /admin/fleet/assignments/batch
 - `vehicleId`、`driverId` 必填；雪花 ID 全程按字符串处理。
 - `protocolPrice`、`messageTemplateId`、`customBody`、`confirmCrossResident` 是单槽位可选字段。
 - 不得为每辆车循环调用单条 `POST /admin/fleet/assignments` 代替批量接口。
+- 批量响应按 `data.assignments[].assignment.assignmentGroupId` 返回各槽位派车组 ID；
+  前端逐项调用模板预览时传入对应 `assignmentGroupId`，不得只预览代表项。
 
 ### 派单详情
 
@@ -153,8 +158,8 @@ GET /admin/fleet/board/orders/{orderId}
 
 | 场景 | 数据源 | 页面行为 |
 | --- | --- | --- |
-| 通知预览唯一命中 active 派车组 | `renderedBody` 中的 `itinerary.url` | 展示稳定短链 |
-| 通知预览无法唯一命中 | 明确不可用文案 | 保留文案并阻止把它当可发送链接 |
+| 通知预览命中派车组已冻结短链 | `assignmentGroupId` + `renderedBody` 中的 `itinerary.url` | 展示稳定短链 |
+| 未传派车组或短链尚未冻结 | “行程短链将在派车后生成” | 保留文案并阻止把它当可发送链接 |
 | 一单多个车辆槽位 | `items[]` | 每个槽位各选一辆车和一名司机，一次批量提交 |
 | 详情有多个 active 派车组 | `activeAssignments[]` | 按槽位逐项展示车辆、司机、脱敏电话和状态 |
 | 详情无 active 派车组 | `activeAssignments=[]` | 展示无有效派单空态 |
@@ -163,7 +168,8 @@ GET /admin/fleet/board/orders/{orderId}
 
 - [ ] 派车弹窗支持选择多个车辆槽位，并为每个槽位选择司机。
 - [ ] 统一提交 `POST /admin/fleet/assignments/batch` 的 `items[]`，保留批次级 `requestId`。
-- [ ] 通知预览传入当前槽位的 `orderId`、`vehicleId`、`driverId`，只把真实短链视为可发送链接。
+- [ ] 批量派单响应逐项保存 `assignmentGroupId`；通知预览传入当前槽位的
+      `orderId`、`vehicleId`、`driverId`、`assignmentGroupId`，只把真实短链视为可发送链接。
 - [ ] 派单详情按 `activeAssignments[]` 展示全部车辆/司机，不只读 `currentAssignment`。
 - [ ] 司机电话使用后端脱敏值，雪花 ID 始终按字符串处理。
 - [ ] 覆盖无 active、多 active、短链不可用等空态/失败封闭场景。
@@ -171,16 +177,19 @@ GET /admin/fleet/board/orders/{orderId}
 ## 验证证据
 
 - OpenAPI/oasdiff：`not_configured`。项目未配置可复现的 Swagger2 → OAS3 导出与 oasdiff 基线；
-  本次字段结构不变，使用源码语义比对、Controller/Service 定向测试与测试网关证据兜底。
+  本次使用源码语义比对、Controller/Service 定向测试与测试网关证据兜底。
 - 消费者契约/Spring Cloud Contract：`not_required`。本次没有内部 Feign 或共享 Java DTO 变化。
-- 后端定向测试：307 项通过，0 失败、0 错误、0 跳过。
+- 后端定向测试：50 项通过，0 失败、0 错误、0 跳过。
 - Fleet Spotless：606 个 Java 文件检查通过。
-- 完整 reactor `verify`、后端 PR、测试部署与网关证据将在后端交付后补充。
+- 完整 reactor `verify`：3203 项测试，0 失败、0 错误、1 跳过；其中 fleet 2367 项，
+  0 失败、0 错误、1 跳过。
+- 后端 PR、测试部署与网关证据将在后端交付后补充。
 
 ## 不影响范围
 
 - 不修改或部署 `D:/work2/hl-ui`。
-- 不新增、不删除 API 字段，不改变字段类型、必填性或枚举。
+- 除模板预览请求新增可选 `assignmentGroupId` 外，不删除 API 字段，不改变既有字段类型、
+  必填性或枚举；模板预览响应结构不变。
 - 不修改批量派单事务、价格、跨常驻确认、保险或通知冻结规则。
 - 不新增 DDL，不清理、不回填存量数据。