hl-api-changelog/changelogs-v2/2026-08/11_5827_派车取消司机确认一步到位派定-修改接口-管理后台.md

schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	author	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5827	⚠️ 派车取消「司机确认」环节：提交即派定、行程单短链直接生成；新增 sendItinerarySms 勾选字段；driver-confirmation 端点下线	admin	修改接口	wx(GIT)	deployed	not_required	pending	mmg				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、状态文案已更新。实测使用无人占用的测试单，验证后已取消还原。	2026-08-11	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 即生效。

请求示例

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）

{
  "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
  }
}

勾选发短信时，仅这三个字段不同：

"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