Merge pull request #31: docs(fleet) #5245 changelog handoff

Correct the stable short-link preview contract and document multi-vehicle/multi-driver frontend consumption.

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

@@ -0,0 +1,196 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5245"
+title: "行程短链预览与同槽位改派解析"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "pending"
+gateway_status: "pending"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端正在交付；前端需把派单选择改为批量 items[]，并按 activeAssignments[] 展示全部车辆与司机。"
+updated_at: "2026-07-25"
+base: "dev-v3"
+---
+
+# 车务：行程短链预览与同槽位改派解析
+
+> **服务**: `hl-fleet-service`
+>
+> **工单**: [wx/HL#5245](https://git.1814.love:8443/wx/HL/issues/5245)
+>
+> **后端 PR**: 待创建
+>
+> **影响范围**: 车务管理 → 派车弹窗通知预览、车辆/司机批量选择、派单详情
+
+## 关键变化
+
+- 通知模板预览中的 `itinerary.url` 改为派车组稳定短链
+  `https://{短链域}/s/{code}`，不再把完整 HMAC token URL 放进预览正文。
+- 既有短链和完整 token 长链在原派车组失效后，只允许解析到同一订单、同一
+  `assignmentSlotId` 的唯一当前有效派车组；跨订单、跨槽位、无有效派单或同槽位存在多个
+  active 派车组时继续返回 `605308`。
+- 批量派单和详情多司机字段是既有契约，本次明确前端消费口径：一次提交 `items[]`，详情展示
+  `activeAssignments[]`，不得只处理兼容代表字段 `currentAssignment`。
+
+## 变更接口
+
+| 方法 | 路径 | 本次口径 |
+| --- | --- | --- |
+| `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[]` 一次提交多个车辆/司机槽位 |
+| `GET` | `/admin/fleet/board/orders/{orderId}` | 既有：按 `activeAssignments[]` 返回全部当前有效派车组 |
+
+## 1. 通知模板预览
+
+```http
+POST /admin/fleet/message-templates/{templateId}/render
+```
+
+请求新增可选字段 `assignmentGroupId`，响应结构不变。前端在预览包含
+`itinerary.url` 或 `itinerary.code` 的模板时，应传入当前派车组 ID：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `orderId` | `string` | 是 | 订单雪花 ID |
+| `vehicleId` | `string` | 是 | 当前派车组车辆雪花 ID |
+| `driverId` | `string` | 是 | 当前派车组司机雪花 ID |
+| `assignmentGroupId` | `string` | 行程预览时是 | 派车组雪花 ID；取自批量派单响应，不得用车辆/司机组合反推 |
+
+`assignmentGroupId` 命中已冻结短链时：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "renderedBody": "请查看行程：https://hr.1814.love/s/Dabc1234",
+    "variablesUsed": ["itinerary.url"]
+  }
+}
+```
+
+未传 `assignmentGroupId`、派车组未冻结短链、短链不存在或读取失败时，
+`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. 前端多车辆/多司机消费
+
+### 批量派单
+
+```http
+POST /admin/fleet/assignments/batch
+```
+
+每个已选车辆槽位生成一个 `items[]` 元素，所有槽位一次提交：
+
+```json
+{
+  "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` 代替批量接口。
+- 批量响应按 `data.assignments[].assignment.assignmentGroupId` 返回各槽位派车组 ID；
+  前端逐项调用模板预览时传入对应 `assignmentGroupId`，不得只预览代表项。
+
+### 派单详情
+
+```http
+GET /admin/fleet/board/orders/{orderId}
+```
+
+按 `data.activeAssignments[]` 渲染每个有效派车组，至少消费：
+
+| 字段 | 用途 |
+| --- | --- |
+| `assignmentGroupId` | 派车组稳定展示 key |
+| `assignmentSlotId` | 同一需求车辆槽位的稳定身份 |
+| `fleetItemIndex` | 槽位顺序 |
+| `vehicleId` / `vehiclePlate` / `vehicleModel` | 车辆展示 |
+| `driverId` / `driverName` / `driverPhone` | 司机展示；电话已脱敏 |
+| `assignmentStatus` / `assignmentStatusLabel` | 当前有效状态 |
+| `lifecycleStageCode` | 生命周期阶段 |
+
+`currentAssignment` 仅为兼容代表项，不能用来判断订单只有一辆车或只展示一名司机。
+`activeAssignments` 无数据时使用空列表空态，不复制代表项凑数。
+
+## 前端展示矩阵
+
+| 场景 | 数据源 | 页面行为 |
+| --- | --- | --- |
+| 通知预览命中派车组已冻结短链 | `assignmentGroupId` + `renderedBody` 中的 `itinerary.url` | 展示稳定短链 |
+| 未传派车组或短链尚未冻结 | “行程短链将在派车后生成” | 保留文案并阻止把它当可发送链接 |
+| 一单多个车辆槽位 | `items[]` | 每个槽位各选一辆车和一名司机，一次批量提交 |
+| 详情有多个 active 派车组 | `activeAssignments[]` | 按槽位逐项展示车辆、司机、脱敏电话和状态 |
+| 详情无 active 派车组 | `activeAssignments=[]` | 展示无有效派单空态 |
+
+## 前端处理清单
+
+- [ ] 派车弹窗支持选择多个车辆槽位，并为每个槽位选择司机。
+- [ ] 统一提交 `POST /admin/fleet/assignments/batch` 的 `items[]`，保留批次级 `requestId`。
+- [ ] 批量派单响应逐项保存 `assignmentGroupId`；通知预览传入当前槽位的
+      `orderId`、`vehicleId`、`driverId`、`assignmentGroupId`，只把真实短链视为可发送链接。
+- [ ] 派单详情按 `activeAssignments[]` 展示全部车辆/司机，不只读 `currentAssignment`。
+- [ ] 司机电话使用后端脱敏值，雪花 ID 始终按字符串处理。
+- [ ] 覆盖无 active、多 active、短链不可用等空态/失败封闭场景。
+
+## 验证证据
+
+- OpenAPI/oasdiff：`not_configured`。项目未配置可复现的 Swagger2 → OAS3 导出与 oasdiff 基线；
+  本次使用源码语义比对、Controller/Service 定向测试与测试网关证据兜底。
+- 消费者契约/Spring Cloud Contract：`not_required`。本次没有内部 Feign 或共享 Java DTO 变化。
+- 后端定向测试：50 项通过，0 失败、0 错误、0 跳过。
+- Fleet Spotless：606 个 Java 文件检查通过。
+- 完整 reactor `verify`：3203 项测试，0 失败、0 错误、1 跳过；其中 fleet 2367 项，
+  0 失败、0 错误、1 跳过。
+- 后端 PR、测试部署与网关证据将在后端交付后补充。
+
+## 不影响范围
+
+- 不修改或部署 `D:/work2/hl-ui`。
+- 除模板预览请求新增可选 `assignmentGroupId` 外，不删除 API 字段，不改变既有字段类型、
+  必填性或枚举；模板预览响应结构不变。
+- 不修改批量派单事务、价格、跨常驻确认、保险或通知冻结规则。
+- 不新增 DDL，不清理、不回填存量数据。
+
+> `frontend_status: pending` 表示等待前端真实领取；不代表页面已实现、发布或验证。