docs(fleet): hand off driver confirmation changes (#5146)
这个提交包含在：
API Changelog Bot
父节点
6a8f6d870b
当前提交
00365d3d26
@ -0,0 +1,157 @@
|
||||
---
|
||||
schema: "hl-changelog/v1"
|
||||
ticket: "5146"
|
||||
title: "司机待确认通知与可选确认凭证"
|
||||
consumer: "admin"
|
||||
backend: "verified"
|
||||
gateway: "verified"
|
||||
frontend: "pending"
|
||||
base: "dev-v3"
|
||||
generated: "2026-07-22T15:20:00+08:00"
|
||||
---
|
||||
|
||||
# 【修改接口·前端待处理·管理后台】司机待确认通知与可选确认凭证
|
||||
|
||||
## 业务变化
|
||||
|
||||
派单待司机确认不再使用内部订单号和“模拟司机回复”。系统默认微信正文改为司机可直接判断是否接单的订车单，展示团号、服务日期、人数及人员类型构成、车辆、接送信息、客户备注和行程详情。
|
||||
|
||||
司机通过微信或电话真实回复后，由车务人员在页面登记“司机已确认接单”。确认凭证用于上传微信截图等佐证，改为选填，不上传也能登记司机确认并继续最终确认执行。
|
||||
|
||||
## 默认通知正文
|
||||
|
||||
```text
|
||||
呼伦旅行—订车单
|
||||
大含服务品质包，已包含接送机/站费用。不得与客人同餐；纯玩、无购物、无自费。请认真完成服务群内容。
|
||||
|
||||
师傅您好，请确认以下订车信息：
|
||||
团号：26-0503
|
||||
日期：2026-07-29 至 2026-07-31
|
||||
人数：4人（成人2、幼童1、婴儿1）
|
||||
车辆：蒙B-34567 丰田汉兰达（7座）
|
||||
接团：CA1234 2026-07-29 10:40 海拉尔东山国际机场
|
||||
送团：G529 2026-07-31 16:20 海拉尔站
|
||||
备注：草原沙漠精华6日
|
||||
行程详情：https://示例短链（有效期至 2026-07-31 23:59）
|
||||
请确认是否接单。
|
||||
```
|
||||
|
||||
- 不展示内部订单号。
|
||||
- 不展示客户姓名。
|
||||
- 人员构成仅展示数量大于 0 的类型，例如“成人2、儿童1、婴儿1”。
|
||||
- 运营已人工修改过的自定义模板不会被迁移覆盖。
|
||||
|
||||
## 变更接口
|
||||
|
||||
### 登记司机已确认
|
||||
|
||||
```http
|
||||
POST /admin/fleet/assignments/{assignmentId}/driver-confirmation
|
||||
```
|
||||
|
||||
请求示例（无凭证）：
|
||||
|
||||
```json
|
||||
{
|
||||
"requestId": "driver-confirm-20260722-001",
|
||||
"driverReplyNote": "司机微信回复已确认接单"
|
||||
}
|
||||
```
|
||||
|
||||
请求示例（有凭证）：
|
||||
|
||||
```json
|
||||
{
|
||||
"requestId": "driver-confirm-20260722-002",
|
||||
"driverReplyNote": "司机微信回复已确认接单",
|
||||
"evidenceFileIds": ["1934567890123456701"]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `requestId` | 是 | 幂等标识，最长 64 字符；每次真实提交生成并在重试时保持不变 |
|
||||
| `driverReplyNote` | 否 | 司机回复原话或摘要，最长 512 字符 |
|
||||
| `evidenceFileIds` | 否 | 已上传文件的 fileId，最多 10 个；空数组、不传均允许 |
|
||||
|
||||
成功响应仍保持派单落库状态 `holding`，但返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"assignmentStatus": "holding",
|
||||
"stageCode": "driver_confirmed",
|
||||
"stageLabel": "司机已确认·待车务确认执行",
|
||||
"currentStep": 4,
|
||||
"assignmentGroupId": "1934567890123456790",
|
||||
"driverConfirmedAt": "2026-07-22T15:20:00",
|
||||
"evidenceFileIds": []
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### 最终确认执行
|
||||
|
||||
登记司机确认成功后，再调用：
|
||||
|
||||
```http
|
||||
POST /admin/fleet/assignments/{assignmentId}/confirm
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"requestId": "fleet-final-confirm-20260722-001"
|
||||
}
|
||||
```
|
||||
|
||||
- 最终确认不再要求存在凭证。
|
||||
- 未调用 `driver-confirmation` 就直接最终确认，返回业务错误 `605025`，文案“请先登记司机已确认接单”。
|
||||
- `assignmentId`、`assignmentGroupId`、`evidenceFileIds[]` 均按字符串处理。
|
||||
|
||||
## 前端页面调整要求
|
||||
|
||||
目标区域：派单弹窗“待确认”步骤，当前实现位于 `src/views/fleet/board/components/Step3DriverConfirm.vue` 及其父级流程。
|
||||
|
||||
1. 删除 `useDispatchMessage.js` 中 `messageTemplates` 三条本地假模板和 `buildMessage()` 拼接正文，不再使用 `standard/sched/itin` 这类前端自造 ID。
|
||||
2. 弹窗打开时调用 `GET /admin/fleet/message-templates?templateType=hold_notify` 加载真实车管模板；默认选中后端返回的 `isDefault=true` 模板。
|
||||
3. 选择订单、车辆、司机或模板后，调用 `POST /admin/fleet/message-templates/{templateId}/render`，传 `orderId/vehicleId/driverId`，以响应 `renderedBody` 作为消息预览。
|
||||
4. 创建 HOLD 派单时传真实雪花 `messageTemplateId`。用户未编辑正文时不要传 `customBody`；用户确实改过本次正文时才传 `customBody`。
|
||||
5. 删除“对方正在输入…”和“模拟·师傅回复确认”，不得用本地布尔值伪造司机回复。
|
||||
6. 改为明确操作“登记司机已确认”，可同时填写可选的“司机回复摘要”。
|
||||
7. 增加“上传确认凭证（选填）”，复用现有文件上传能力；上传成功后只传 fileId，不传 URL。
|
||||
8. 点击登记时调用 `driver-confirmation`；只有响应成功且 `stageCode=driver_confirmed` 后，才允许进入最终确认执行。
|
||||
9. 没有上传凭证时不得禁用登记按钮，也不得阻止下一步；`evidenceFileIds` 可省略或传 `[]`。
|
||||
10. 最终确认调用 `confirm` 时只传新的 `requestId`，不要再传 `driverReplyNote`。
|
||||
11. 页面刷新后以详情返回的 `driverConfirmedAt`/阶段信息恢复状态，不使用前端临时模拟状态。
|
||||
|
||||
现有 API 文件 `src/api/fleet/message-template.js` 已封装模板列表和渲染接口，应直接复用。页面显示的模板名、正文和最终创建请求必须来自同一个后端模板，禁止再次在前端维护一套同名文案。
|
||||
|
||||
推荐文案：
|
||||
|
||||
- 操作按钮：“登记司机已确认”
|
||||
- 上传项：“确认凭证（选填）”
|
||||
- 等待态：“等待司机回复确认”
|
||||
- 已登记态：“司机已确认接单，待车务确认执行”
|
||||
|
||||
## 前端处理清单
|
||||
|
||||
- [ ] 模板列表来自后端 `hold_notify` 模板，默认选中 `isDefault=true`，不再使用前端假模板。
|
||||
- [ ] 消息预览调用后端 `render`，HOLD 创建传同一个真实 `messageTemplateId`，确保预览与发送一致。
|
||||
- [ ] 删除模拟司机回复入口及伪造回复气泡。
|
||||
- [ ] 增加真实“登记司机已确认”操作并调用 `driver-confirmation`。
|
||||
- [ ] 支持上传最多 10 个确认凭证，明确标记为选填。
|
||||
- [ ] 无凭证时仍可成功登记司机确认并执行最终确认。
|
||||
- [ ] `605025` 时提示“请先登记司机已确认接单”，不提示“缺少凭证”。
|
||||
- [ ] 页面刷新后能按后端状态恢复待回复/已确认阶段。
|
||||
|
||||
## 验证证据
|
||||
|
||||
- 后端：`hl-order-service-v3` clean verify、shared/Feign 生产者与消费者测试、fleet 定向测试、`spotless:check` 和 fleet `verify` 通过。
|
||||
- 部署：`hl-order-service-v3` 的 8086/8186、`hl-fleet-service` 的 8087/8187 两组测试实例均滚动发布成功并通过健康检查。
|
||||
- 网关：使用 `admin / VEHICLE_MANAGER` 经 `https://api.test.1814.love:9443` 验证模板列表、车务看板、车辆列表、司机列表和模板 render，HTTP 均为 200。
|
||||
- 默认 `hold_notify` 模板已按真实动态模板 ID 升级；固定服务规则、新变量、内部订单号/客户变量移除及渲染后无未解析变量均通过断言。
|
||||
- 扩大聚合测试排除了三个与本次无关的既有失败：`CrossSchemaMigrationAuditTest`、`InternalUserControllerTest2`、`MpOrderDetailJsonSampleTest`；本次受影响的 order-v3/fleet 验证未排除。
|
||||
|
||||
> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户