diff --git a/changelogs-v2/2026-08/11_5827_派车取消司机确认一步到位派定-修改接口-管理后台.md b/changelogs-v2/2026-08/11_5827_派车取消司机确认一步到位派定-修改接口-管理后台.md new file mode 100644 index 0000000..c192215 --- /dev/null +++ b/changelogs-v2/2026-08/11_5827_派车取消司机确认一步到位派定-修改接口-管理后台.md @@ -0,0 +1,284 @@ +--- +schema: "hl-changelog/v2" +ticket: "5827" +title: "⚠️ 派车取消「司机确认」环节:提交即派定、行程单短链直接生成;新增 sendItinerarySms 勾选字段;driver-confirmation 端点下线" +consumer: "admin" +change_type: "修改接口" +author: "wx(GIT)" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #5873 已合并 dev-v3 并部署测试服(19:22:57 构建,jar 早于进程启动,确认跑新代码)。测试服真实 API 实测通过:driver-confirmation 端点 404 已下线;不传 holdMode 不再 400;派车响应 assignmentStatus=assigned + confirmedAt 有值(提交即派定);未传 sendItinerarySms 时 itinerarySmsStatus=NOT_SENT 且 outbox 无 ITINERARY_SMS/HOLD_NOTIFICATION(不勾不发、Step3 不发通知);行程单链接派车后立即可打开(HTTP 200,带真实定稿代际);看板 progressSteps 三步、holdNotificationStatus=NOT_REQUIRED、状态文案已更新。实测使用无人占用的测试单,验证后已取消还原。" +updated_at: "2026-08-11" +base: "dev-v3" +--- + +# ⚠️ 车务派车取消「司机确认」环节 —— 一步到位派定(#5827) + +> **服务**: hl-fleet-service +> **性质**: **破坏性变更**(流程步骤减少、端点下线、默认行为变更),前端必须跟进 + +--- + +## 一、业务变化(一句话) + +**派车提交即派定**:不再有「等司机回复确认 → 车务登记司机已确认 → 车务确认执行」这一段,提交后当场落 `assigned`、当场生成行程单短链,车务**不用再点第二次**。 + +配套:**Step3 不再自动给司机发「排车待确认」通知**;行程短信改为**只在车务显式勾选时发这一次**。 + +--- + +## 二、变更接口清单 + +| 方法 | 路径 | 变更 | +|---|---|---| +| `POST` | `/admin/fleet/assignments` | 请求新增 `sendItinerarySms`;响应新增三字段;`holdMode` 摘 `@NotNull` 并废弃;提交即派定 | +| `POST` | `/admin/fleet/assignments/batch` | 同上(`sendItinerarySms` 放 body 顶层,批次级统一决策) | +| `POST` | `/admin/fleet/assignments/{assignmentId}/change` | 同上;不勾选不再给司机重发行程短信 | +| `POST` | `/admin/fleet/assignments/{assignmentId}/driver-confirmation` | **端点下线** | +| `POST` | `/admin/fleet/assignments/{assignmentId}/confirm` | 契约文案更新(不再要求「已登记司机确认」);新流程下非必经步骤 | +| `POST` | `/admin/fleet/assignments/requirements/{requirementId}/confirm` | 同上 | +| `POST` | `/admin/fleet/assignments/{assignmentId}/cancel` | 错误码清单更正:605024 → **605028** | +| `GET` | `/admin/fleet/board/orders/{orderId}` | `holdNotificationStatus` / `currentStep` / `stageCode` / 状态说明文案语义变更 | + +## 三、⚠️ 前端必须做的四件事 + +### 1. 删掉「待司机确认」开关 + +派车表单底部的「待司机确认 · 先锁定司机并发送通知」开关(`holdMode`)**请删除**。 + +- 后端已**摘除该字段的 `@NotNull`**,不传不会再 400; +- 字段保留兼容但**服务端一律忽略**(传任何值都按一步派定处理)。 + +### 2. 删掉「等待司机回复确认」整块 UI + +- 司机回复摘要输入框 +- 司机确认凭证上传(最多 10 个) +- 「登记司机已确认」按钮 + +对应端点 **`POST /admin/fleet/assignments/{assignmentId}/driver-confirmation` 已下线**。 + +### 3. 新增「发送行程短信」勾选,并在派车/改派时传 `sendItinerarySms` + +**这是本次最关键的行为变更。** 详见第四节。 + +### 4. 派车向导由 4 步改为 3 步 + +「订单详情 → 排车 → 确认执行」。后端 `currentStep` 已由 4 改 3,`stageCode` 不再产出 `driver_confirmed`。 + +--- + +## 四、新增字段 `sendItinerarySms`(三个写端点) + +### 请求 + +| 端点 | 位置 | 字段 | 类型 | 必填 | 缺省 | +|---|---|---|---|---|---| +| `POST /admin/fleet/assignments` | body 顶层 | `sendItinerarySms` | Boolean | 否 | **不传 = `false` = 不发** | +| `POST /admin/fleet/assignments/batch` | **body 顶层**(不是 items 里) | `sendItinerarySms` | Boolean | 否 | 不传 = `false` | +| `POST /admin/fleet/assignments/{assignmentId}/change` | body 顶层 | `sendItinerarySms` | Boolean | 否 | 不传 = `false` | + +> 批量为**批次级统一决策**:整批用同一个值,避免同一需求同一代际内 `itinerary_sms_decision` 不一致。 + +### 响应(三个端点新增,与 `ConfirmRespVO` 同口径) + +| 字段 | 类型 | 说明 | +|---|---|---| +| `sendItinerarySms` | Boolean | 本次是否选择发送行程短信 | +| `itinerarySmsEventId` | String(雪花,字符串序列化) | 行程短信事件 ID;未发送时为 `null` | +| `itinerarySmsStatus` | String | `PENDING`(已入队待发) / `NOT_SENT`(未勾选,不发) | + +### 🔴 行为口径(务必理解) + +- **不勾(含不传)→ 一条司机短信都不发**。 +- **行程单短链与短信无关**:不发短信也照样生成短链、照样可打开。 +- 改派同理:**「只改计费日期 / 只改车费」不勾就不会给司机重发短信**(此前会重发)。 +- 改派的幂等载荷哈希**不含**该字段:同一 `requestId` 改了勾选再提交会返回已冻结的旧回执,**换新 `requestId` 即生效**。 + +### 请求示例 + +```json +POST /admin/fleet/assignments +Authorization: Bearer +Content-Type: application/json + +{ + "orderId": 2086270138171994114, + "vehicleId": 2064998142394183681, + "driverId": 2065272145633591298, + "startDate": "2026-08-17", + "endDate": "2026-08-19", + "headcount": 10, + "sendItinerarySms": true, + "requestId": "f3c1c8e2-0a1a-4f2b-9a77-1b2c3d4e5f60" +} +``` + +### 成功响应示例(**测试服实测原样**,未传 `sendItinerarySms` / 未传 `holdMode`) + +```json +{ + "code": 200, + "message": "成功", + "data": { + "id": "2086824442578542594", + "assignmentGroupId": "2086824442578542594", + "assignmentSlotId": "345214258881105920", + "assignmentStatus": "assigned", + "stageCode": "assigned", + "stageLabel": "已派车", + "currentStep": 3, + "skippedStepCodes": [], + "protocolPrice": "800.00", + "vehicleFeeAutoTotal": "2400.00", + "vehicleFeeAutoComplete": true, + "vehicleFeeTotal": "2400.00", + "vehicleFeeSource": "AUTO", + "vehicleFeeAdjustmentReason": null, + "dailyVehicleFees": null, + "holdSentAt": null, + "confirmedAt": "2026-08-11 19:28:02", + "sideEffects": { + "vehicleStatusUpdated": "busy", + "driverStatusUpdated": "busy", + "reconPrepRowsCreated": 0, + "reconPrepMarkedCanceled": null + }, + "sendItinerarySms": false, + "itinerarySmsEventId": null, + "itinerarySmsStatus": "NOT_SENT", + "dailyDifferences": null + } +} +``` + +勾选发短信时,仅这三个字段不同: + +```json +"sendItinerarySms": true, +"itinerarySmsEventId": "345528786529423360", +"itinerarySmsStatus": "PENDING" +``` + +### ⚠️ 行程单链接不在派车响应里 + +派车响应**不含** `itineraryUrl`。行程单链接在**看板订单详情**里取: + +``` +GET /admin/fleet/board/orders/{orderId} +→ data.currentAssignment.itineraryUrl +``` + +**实测**:派车成功后立刻读该字段即有值,且链接**当场可打开**(HTTP 200 返回完整行程数据),token 内 `dispatchPlanGeneration` 为**真实定稿代际**(不是待确认期的 `0` 哨兵)。 + +**未勾选发短信时链接同样可用** —— 行程单链接与是否发短信无关。 + +> 补充说明:`fleet_itinerary_short_link` 里的**短码**(`/s/xxxx` 形式)只在**发短信时**才铸造(它只服务于短信长度限制)。不发短信时使用的是上面这个完整 token 链接,功能等价、当场可用。 + +--- + +## 五、废弃字段(保留兼容,服务端忽略) + +| 字段 | 所在端点 | 现在的行为 | +|---|---|---| +| `holdMode` | create / batch / change | **已摘 `@NotNull`**,传任何值都被忽略,一律按一步派定落库 | +| `messageTemplateId` | create / batch.items / change | 已废弃(不再发「待司机确认」通知,无模板可冻结) | +| `customBody` | create / batch.items / change | 同上 | + +--- + +## 六、下线端点 + +| 方法 | 路径 | 说明 | +|---|---|---| +| `POST` | `/admin/fleet/assignments/{assignmentId}/driver-confirmation` | 「登记司机已确认」,随司机确认环节一并下线 | + +--- + +## 七、响应语义变更(读侧) + +| 位置 | 原来 | 现在 | +|---|---|---| +| 派车/批量/改派响应 `assignmentStatus` | 可能是 `holding` | **恒 `assigned`** | +| 派车/批量/改派响应 `skippedStepCodes` | 可能非空 | **恒空数组**(字段保留兼容) | +| 派车/批量/改派响应 `holdSentAt` | 可能有值 | **恒 `null`** | +| 派车/批量/改派响应 `confirmedAt` | 仅确认后才有 | **恒有值**(提交即派定) | +| 看板 `currentAssignment.holdNotificationStatus` | `assigned`/`completed` 行恒返回 `PENDING` | **恒返回 `NOT_REQUIRED`**(此前会诱导车务点无效重发) | +| 生命周期 `currentStep` | 四阶段 / 4 | **三阶段 / 3** | +| 生命周期 `stageCode` | 可能是 `driver_confirmed` | **不再产出该派生态**(时间轴事件类型 `driver_confirmed` 仍保留,用于存量数据回显) | +| `holding` 状态中文名 | 「待确认」 | **「待确认执行」**(新流程下只有存量数据会停在该态) | +| 看板状态筛选项「已派车」说明 | 「司机已确认,派车已生效」 | **「车务已派定,行程单已生成」** | + +--- + +## 八、错误码变化 + +### 从契约中移除(不会再抛出,常量保留仅供历史数据字典对照) + +| 码 | 原含义 | +|---|---| +| `605024` | 排车模式不合法 | +| `605025` | 请先登记司机已确认接单 | + +### 更正(此前文档错标) + +`POST /admin/fleet/assignments/{assignmentId}/cancel` 的错误码清单里原写「605024 取消生效日无效」是**错标**(605024 的真实含义是排车模式不合法),已更正为: + +| 码 | 含义 | +|---|---| +| `605028` | 生效日期不在派单服务日期范围内 | + +--- + +## 九、不变的部分(免得误删) + +- **行程单短链**照常生成,且带真实定稿代际;短链身份与「是否发短信」无关。 +- **时间轴事件类型 `driver_confirmed`** 保留(存量数据回显用)。 +- **取消 / 撤销取消 / 改派 / 逐日派车**的既有入参与语义不变。 +- 保险投保时序、槽位锁互斥、占用释放四条链路不变。 + +--- + +## 十、验证证据 + +### 测试服实测(2026-08-11 19:22 部署,19:28 实测) + +部署核实:服务器仓库含合并提交 `1c46e6abf`;fleet jar 构建于 19:22:57,两个实例进程分别启动于 19:23:08 / 19:23:25(**jar 早于进程,确认跑的是新代码**);8087 / 8187 健康检查均 200。 + +| 验证项 | 方法 | 结果 | +|---|---|---| +| `driver-confirmation` 端点已下线 | `POST .../driver-confirmation` | **HTTP 404「接口不存在」** ✅ | +| 不传 `holdMode` 不再 400 | 派车请求省略该字段 | **code 200** ✅ | +| **提交即派定** | 派车响应 | `assignmentStatus: "assigned"` + `confirmedAt: "2026-08-11 19:28:02"`,**无需第二次调用** ✅ | +| 向导 3 步 | 派车响应 + 看板 | `currentStep: 3`;看板 `progressSteps = [ORDER_DETAIL, DISPATCH, CONFIRM_EXECUTE]` ✅ | +| `skippedStepCodes` 恒空 / `holdSentAt` 恒 null | 派车响应 | `[]` / `null` ✅ | +| **不勾不发** | 未传 `sendItinerarySms` | `sendItinerarySms: false`、`itinerarySmsStatus: "NOT_SENT"`、`itinerarySmsEventId: null` ✅ | +| **Step3 不发任何通知** | 查 outbox 全部事件 | 只有 `OCCUPANCY_RECOMPUTE` + `ASSIGNED`(均 SUCCESS),**无 `ITINERARY_SMS`、无 `HOLD_NOTIFICATION`** ✅ | +| **行程单链接直接可用** | 看板 `itineraryUrl` → 直接 GET | **HTTP 200 返回完整行程**,token 内 `dispatchPlanGeneration` 为真实定稿代际 ✅ | +| `holdNotificationStatus` 修复 | 看板 `currentAssignment` | 已派定行返回 **`NOT_REQUIRED`**(此前恒 `PENDING`)✅ | +| 状态说明文案 | 看板 `statusOptions` | `holding` →「车务已排车,待车务确认执行」;`assigned` →「车务已派定,行程单已生成」✅ | +| 占用副作用 | 派车响应 `sideEffects` | 车与司机均置 `busy` ✅ | + +> 实测用的是一张**无人使用的测试单**(非现场在用订单),验证完毕已通过业务接口取消还原,占用已释放、无脏数据残留。 + +### 后端质量门禁(rebase 到最新 dev-v3 后) + +| 项 | 结果 | +|---|---| +| `mvn -pl hl-fleet-service clean test-compile` | BUILD SUCCESS | +| `mvn -pl hl-fleet-service test -Dtest=*ArchTest` | Tests run **13**,Failures 0 | +| `mvn -pl hl-fleet-service spotless:check` | BUILD SUCCESS | +| `mvn -pl hl-fleet-service test`(全量) | Tests run **3605**,Failures **0**,Errors **0**,Skipped 5(Docker 门控自跳过的容器类 IT) | + +--- + +## 十一、关联 + +- 工单 #5827 +- 换版槽位人工制:#5810 +- 换版后看板缺口:#5824 +- 换版即作废定稿:#5851