docs(changelog): hand off final-confirm itinerary SMS (#5263)

changelogs-v2/2026-07/26_5263_最终确认按车选择发送行程短信-修改接口-前端待处理-管理后台.md

@@ -0,0 +1,156 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5263"
+title: "最终确认按车选择发送行程短信"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "pending"
+gateway_status: "pending"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端已在最新 dev-v3 基线上完成源码与全量测试验证，PR、测试部署和网关实测尚待完成；前端尚未领取，owner/ref 保持为空。"
+updated_at: "2026-07-26"
+base: "dev-v3"
+generated: "2026-07-26T17:33:00+08:00"
+---
+
+# 最终确认按车选择发送行程短信
+
+## 关联
+
+- Issue: [wx/HL#5263](https://git.1814.love:8443/wx/HL/issues/5263)
+- 服务：`hl-fleet-service`、`hl-user-service`
+- 前端仓库：`mmg/hl-ui`（本文仅交接，不代表已修改前端）
+- 前置车费契约：[#5262 派车逐日车费、只读总价与核单实时接口](./26_5262_派车逐日车费与核单实时接口-修改接口-前端待处理-管理后台.md)
+
+## 关键变化
+
+1. 仅在 HOLD 排车的最终确认阶段，每个车辆组必须显式选择“发送短信”或“不发送短信”，没有默认值。
+2. 选择发送时，确认事务只落可靠发送意图；短信异步发送失败不会回滚已完成的派车确认。
+3. 短信只发给该车辆组当前师傅，包含订单摘要、接送摘要和签名行程短链，不包含客户手机号。
+4. 选择不发送时只完成派车确认，不创建行程短信事件。
+5. 多车订单逐车独立选择、独立投递、独立查询状态和受控重试。
+6. 已派定后的订单人数基线复核只能沿用原选择，不允许借复核修改选择或重复发送。
+7. 直接派车流程不受影响；#5262 已废弃的手工车辆总价入参仍然禁止提交。
+
+## 变更接口
+
+| 方法 | 路径 | 变化 |
+| --- | --- | --- |
+| `POST` | `/admin/fleet/assignments/:assignmentId/confirm` | 请求新增必填 `sendItinerarySms`；响应新增短信选择、事件与状态 |
+| `GET` | `/admin/fleet/assignments/:assignmentId/itinerary-sms` | 新增单车/车辆组短信审计状态查询 |
+| `POST` | `/admin/fleet/assignments/:assignmentId/itinerary-sms/retry` | 新增明确失败后的车务受控重试 |
+
+## 最终确认
+
+### `POST /admin/fleet/assignments/:assignmentId/confirm`
+
+#### 请求字段
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `sendItinerarySms` | `Boolean` | 是 | `true` 发送；`false` 不发送；省略或 `null` 返回参数错误 |
+| `requestId` | `String` | 是 | 最长 64 字符的幂等请求标识 |
+| `vehicleFeeTotal` | `Decimal` | 否 | 历史兼容字段；非空即拒绝，最终总车费继续由 #5262 逐日车费只读合计 |
+| `vehicleFeeAdjustmentReason` | `String` | 否 | 历史兼容字段；非空即拒绝 |
+
+请求示例：
+
+```json
+{
+  "sendItinerarySms": true,
+  "requestId": "fleet-final-confirm-26-8411-car-1"
+}
+```
+
+#### 新增响应字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `sendItinerarySms` | `Boolean` | 本车辆组最终确认时保存的选择 |
+| `itinerarySmsEventId` | `String/null` | 可靠短信事件 ID；不发送时为空 |
+| `itinerarySmsStatus` | `String` | 首次确认返回 `PENDING` 或 `NOT_SENT`；已派定复核回显真实状态 |
+
+## 短信状态
+
+### `GET /admin/fleet/assignments/:assignmentId/itinerary-sms`
+
+响应 `data`：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `assignmentId` | `String` | 派单 ID |
+| `assignmentGroupId` | `String` | 跨服务日车辆组 ID |
+| `assignmentSlotId` | `String` | 稳定车辆槽位 ID |
+| `sendItinerarySms` | `Boolean/null` | 未最终确认或历史数据时为 `null` |
+| `status` | `String` | `NOT_APPLICABLE` / `NOT_SENT` / `PENDING` / `SENT` / `FAILED` / `CANCELED` |
+| `eventId` | `String/null` | 可靠短信事件 ID |
+| `retryCount` | `Integer` | 已发生的失败重试次数 |
+| `canRetry` | `Boolean` | 当前是否允许受控重试 |
+| `sentAt` | `LocalDateTime/null` | 供应商确认的真实发送时间 |
+| `lastError` | `String/null` | 已脱敏的最近失败或待对账原因 |
+
+前端以 `status` 为权威，不得仅凭最终确认接口成功就显示“短信已发送”。
+
+## 受控重试
+
+### `POST /admin/fleet/assignments/:assignmentId/itinerary-sms/retry`
+
+请求：
+
+```json
+{
+  "reason": "短信通道配置已恢复，车务确认重发",
+  "requestId": "retry-sms-26-8411-car-1"
+}
+```
+
+规则：
+
+- 仅 `FAILED` 且 `canRetry=true` 时展示并调用重试。
+- `SENT`、`PENDING`、待供应商对账、`CANCELED`、未选择发送时禁止重试。
+- 重试复用原事件与供应商幂等键，不新建并行短信事件。
+- 司机或车辆组身份已变化时，旧事件收敛为 `CANCELED`，不得发给旧师傅。
+
+## 短信与隐私约束
+
+短信模板参数固定为：
+
+| 参数 | 内容 |
+| --- | --- |
+| `summary` | 脱敏订单摘要 |
+| `transfer` | 接送摘要 |
+| `code` | 签名行程短链 |
+
+短信正文及模板参数不得包含客户手机号。真实联系人信息仅在既有签名行程 H5 中按授权展示。
+
+## 页面展示矩阵
+
+| 区域/状态 | 数据源 | 展示 | 空态/禁用 | 颜色 | 守恒规则 |
+| --- | --- | --- | --- | --- | --- |
+| 最终确认车辆卡片 | 本地待提交选择 | “发送短信”/“不发送短信”二选一 | 未选择时禁止确认并提示必选 | 发送蓝色，不发送中性灰 | 每个车辆组恰好一个选择 |
+| 确认后状态 | `GET .../itinerary-sms.status` | 待发送/已发送/发送失败/已取消/未发送 | 历史数据为“不适用” | 待发送蓝、已发送绿、失败红、取消灰、未发送中性灰 | 不以确认成功冒充发送成功 |
+| 失败操作 | `canRetry` | “重试短信” | `canRetry=false` 时隐藏或禁用 | 可重试橙色 | 同一事件串行重试 |
+| 多车订单 | 每个 `assignmentGroupId` | 每车独立选择与状态 | 不做订单级统一默认 | 各卡片独立 | 一车选择不得覆盖另一车 |
+
+## 前端处理清单
+
+- [ ] 最终确认页按车辆组渲染无默认值的短信二选一。
+- [ ] 未完成选择时不提交确认请求，并展示明确校验提示。
+- [ ] 确认请求始终显式提交 `sendItinerarySms`，不再依赖后端默认值。
+- [ ] 确认后通过状态接口展示真实投递状态。
+- [ ] 仅在 `FAILED && canRetry=true` 时允许填写原因并调用重试。
+- [ ] 已派定复核回显原选择并保持只读，不提供改选入口。
+- [ ] 短信状态按展示矩阵处理空态、颜色及多车独立性。
+- [ ] 确认和复核请求继续不提交 #5262 已废弃的手工总车费字段。
+
+## 验证证据
+
+- OpenAPI/oasdiff：`not_configured`；已完成 Controller/VO 源码比对和接口测试回退证据。
+- 消费者契约：`not_required`；未修改 internal Feign 或共享 Java DTO。
+- Fleet：`mvn -pl hl-fleet-service -am clean verify` 与 `spotless:check` 通过。
+- User：`mvn -pl hl-user-service -am verify` 通过。
+- `frontend_status`：`pending`；真实领取后再迁移为 `claimed` 并填写 `frontend_owner`。