285 行
13 KiB
Markdown
285 行
13 KiB
Markdown
---
|
||
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 <admin token>
|
||
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
|