diff --git a/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md b/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md index a314485..aa01527 100644 --- a/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md +++ b/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md @@ -4,14 +4,14 @@ ticket: "5245" title: "行程短链预览与同槽位改派解析" consumer: "admin" change_type: "修改接口" -backend_status: "pending" -gateway_status: "pending" +backend_status: "deployed" +gateway_status: "verified" frontend_status: "pending" frontend_owner: "" frontend_ref: "" target_release: "" verified_at: "" -status_note: "后端正在交付；前端需把派单选择改为批量 items[]，并按 activeAssignments[] 展示全部车辆与司机。" +status_note: "后端已通过 PR #5249/#5250 合并并部署测试环境；通知预览即时创建/复用短链及 302/H5/错误边界已验证；前端待领取多车多司机消费。" updated_at: "2026-07-25" base: "dev-v3" --- @@ -22,14 +22,15 @@ base: "dev-v3" > > **工单**: [wx/HL#5245](https://git.1814.love:8443/wx/HL/issues/5245) > -> **后端 PR**: 待创建 +> **后端 PR**: [wx/HL#5249](https://git.1814.love:8443/wx/HL/pulls/5249)、 +> [wx/HL#5250](https://git.1814.love:8443/wx/HL/pulls/5250) > > **影响范围**: 车务管理 → 派车弹窗通知预览、车辆/司机批量选择、派单详情 ## 关键变化 -- 通知模板预览中的 `itinerary.url` 改为派车组稳定短链 - `https://{短链域}/s/{code}`，不再把完整 HMAC token URL 放进预览正文。 +- 通知模板预览中的 `itinerary.url` 会为当前派车组即时创建或复用稳定短链， + 例如 `https://hr.example.com/s/Dabc1234`，不再把完整 HMAC token URL 或“派车后生成”占位文案放进预览正文。 - 既有短链和完整 token 长链在原派车组失效后，只允许解析到同一订单、同一 `assignmentSlotId` 的唯一当前有效派车组；跨订单、跨槽位、无有效派单或同槽位存在多个 active 派车组时继续返回 `605308`。 @@ -40,48 +41,48 @@ base: "dev-v3" | 方法 | 路径 | 本次口径 | | --- | --- | --- | -| `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/message-templates//render` | 请求新增可选 `assignmentGroupId`；有效派车组即时创建/复用稳定短链；旧前端未传时仅在订单、车辆、司机唯一定位一个 active 组时兼容 | +| `GET` | `/app/h5/s/` | 继续生成短时 token 并重定向；同槽位改派后的解析由行程接口完成 | +| `GET` | `/app/h5/itinerary/` | 原组失效后仅回退同订单、同稳定槽位的唯一 active 派车组 | | `POST` | `/admin/fleet/assignments/batch` | 既有：按 `items[]` 一次提交多个车辆/司机槽位 | -| `GET` | `/admin/fleet/board/orders/{orderId}` | 既有：按 `activeAssignments[]` 返回全部当前有效派车组 | +| `GET` | `/admin/fleet/board/orders/` | 既有：按 `activeAssignments[]` 返回全部当前有效派车组 | ## 1. 通知模板预览 ```http -POST /admin/fleet/message-templates/{templateId}/render +POST /admin/fleet/message-templates//render ``` 请求新增可选字段 `assignmentGroupId`，响应结构不变。前端在预览包含 -`itinerary.url` 或 `itinerary.code` 的模板时，应传入当前派车组 ID： +`itinerary.url` 或 `itinerary.code` 的模板时，应传入当前派车组 ID；后端仅为兼容旧前端， +在 `orderId` + `vehicleId` + `driverId` 唯一定位一个 active 派车组时允许省略： | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | `orderId` | `string` | 是 | 订单雪花 ID | | `vehicleId` | `string` | 是 | 当前派车组车辆雪花 ID | | `driverId` | `string` | 是 | 当前派车组司机雪花 ID | -| `assignmentGroupId` | `string` | 行程预览时是 | 派车组雪花 ID；取自批量派单响应，不得用车辆/司机组合反推 | +| `assignmentGroupId` | `string` | 行程预览时强烈建议 | 派车组雪花 ID；取自批量派单响应，多车多司机场景必须按槽位传入 | -`assignmentGroupId` 命中已冻结短链时： +派车组有效时，预览会即时创建或复用该组短链： -```json -{ - "code": 200, - "data": { - "renderedBody": "请查看行程：https://hr.1814.love/s/Dabc1234", - "variablesUsed": ["itinerary.url"] - } -} +```yaml +code: 200 +data: + renderedBody: "请查看行程：https://hr.example.com/s/Dabc1234" + variablesUsed: + - "itinerary.url" ``` -未传 `assignmentGroupId`、派车组未冻结短链、短链不存在或读取失败时， -`itinerary.url` 使用“行程短链将在派车后生成”，`itinerary.code` 为空字符串； -预览接口不新建短链，也不会回退或暴露完整 HMAC URL。 +未传 `assignmentGroupId` 且订单、车辆、司机无法唯一定位 active 派车组，或显式派车组无效时， +`itinerary.url` 使用“行程链接暂不可用，请联系车务确认”，`itinerary.code` 为空字符串。 +短链配置、注册或数据库失败时接口直接返回错误，不静默降级为占位文案；任何场景都不会回退或 +暴露完整 HMAC URL。同一派车组通过显式 ID 或兼容定位重复预览、发送、重试时复用同一短链。 ## 2. 同稳定槽位改派后的旧链接 -短链先通过 `/app/h5/s/{code}` 重定向到短时 token；短链与直接保存的完整 token 最终都进入 -`/app/h5/itinerary/{token}`，因此使用同一组回退规则： +短链先通过 `/app/h5/s/` 重定向到短时 token；短链与直接保存的完整 token 最终都进入 +`/app/h5/itinerary/`，因此使用同一组回退规则： | token 原派单与当前派单 | 结果 | | --- | --- | @@ -103,27 +104,20 @@ 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" - } - ] -} +```yaml +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 开始，对应需求展开后的稳定车辆槽位。 @@ -136,7 +130,7 @@ POST /admin/fleet/assignments/batch ### 派单详情 ```http -GET /admin/fleet/board/orders/{orderId} +GET /admin/fleet/board/orders/ ``` 按 `data.activeAssignments[]` 渲染每个有效派车组，至少消费： @@ -158,8 +152,9 @@ GET /admin/fleet/board/orders/{orderId} | 场景 | 数据源 | 页面行为 | | --- | --- | --- | -| 通知预览命中派车组已冻结短链 | `assignmentGroupId` + `renderedBody` 中的 `itinerary.url` | 展示稳定短链 | -| 未传派车组或短链尚未冻结 | “行程短链将在派车后生成” | 保留文案并阻止把它当可发送链接 | +| 通知预览传入有效派车组 | `assignmentGroupId` + `renderedBody` 中的 `itinerary.url` | 即时创建或复用并展示稳定短链 | +| 旧前端未传派车组但订单、车辆、司机唯一定位 | `orderId` + `vehicleId` + `driverId` | 兼容定位并返回同一稳定短链 | +| 派车组缺失、无效或定位不唯一 | “行程链接暂不可用，请联系车务确认” | 展示不可用态，不把文案当可发送链接 | | 一单多个车辆槽位 | `items[]` | 每个槽位各选一辆车和一名司机，一次批量提交 | | 详情有多个 active 派车组 | `activeAssignments[]` | 按槽位逐项展示车辆、司机、脱敏电话和状态 | | 详情无 active 派车组 | `activeAssignments=[]` | 展示无有效派单空态 | @@ -179,17 +174,22 @@ GET /admin/fleet/board/orders/{orderId} - OpenAPI/oasdiff：`not_configured`。项目未配置可复现的 Swagger2 → OAS3 导出与 oasdiff 基线； 本次使用源码语义比对、Controller/Service 定向测试与测试网关证据兜底。 - 消费者契约/Spring Cloud Contract：`not_required`。本次没有内部 Feign 或共享 Java DTO 变化。 -- 后端定向测试：50 项通过，0 失败、0 错误、0 跳过。 +- 后端定向测试：41 项通过，0 失败、0 错误、0 跳过。 - Fleet Spotless：606 个 Java 文件检查通过。 -- 完整 reactor `verify`：3203 项测试，0 失败、0 错误、1 跳过；其中 fleet 2367 项， +- 完整 reactor `verify`：3209 项测试，0 失败、0 错误、1 跳过；其中 fleet 2373 项， 0 失败、0 错误、1 跳过。 -- 后端 PR、测试部署与网关证据将在后端交付后补充。 +- 后端 PR #5249 合并提交：`433ef238f09eba2258c996093b1d8cb2309a8e83`。 +- 后端 PR #5250 合并提交：`d939995bd266f11076eb79ea183e37a968e01afc`。 +- 测试部署任务：`8eae87b2`；`hl-fleet-service` 的 `8187`、`8087` 两实例均健康。 +- 测试网关已验证：显式 `assignmentGroupId` 与唯一兼容定位返回同一 7 位短码； + 重复预览保持稳定，短链 302、H5 JSON 与 HTML 均成功；失效组返回 `605308`， + 篡改签名返回 `605306`。脱敏证据已回写工单 #5245。 ## 不影响范围 - 不修改或部署 `D:/work2/hl-ui`。 - 除模板预览请求新增可选 `assignmentGroupId` 外，不删除 API 字段，不改变既有字段类型、 - 必填性或枚举；模板预览响应结构不变。 + 必填性或枚举；模板预览响应结构不变。预览在命中有效派车组时会幂等写入短链记录。 - 不修改批量派单事务、价格、跨常驻确认、保险或通知冻结规则。 - 不新增 DDL，不清理、不回填存量数据。