diff --git a/changelogs-v2/2026-07/82_5146_司机待确认通知与可选确认凭证-修改接口-前端待处理-管理后台.md b/changelogs-v2/2026-07/82_5146_司机待确认通知与可选确认凭证-修改接口-前端待处理-管理后台.md new file mode 100644 index 0000000..ab4549e --- /dev/null +++ b/changelogs-v2/2026-07/82_5146_司机待确认通知与可选确认凭证-修改接口-前端待处理-管理后台.md @@ -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`。