From 3ffef86227a9f2859b408d2b5e3b08d947f7f44b Mon Sep 17 00:00:00 2001 From: wx <2636507191@qq.com> Date: Sat, 25 Jul 2026 11:55:50 +0800 Subject: [PATCH] docs(fleet): correct shortlink preview contract (#5245) --- ...链预览与同槽位改派解析-修改接口-管理后台.md | 37 ++++++++++++------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md b/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md index 8fb597d..a314485 100644 --- a/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md +++ b/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，不清理、不回填存量数据。