---
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`。