From e816810210f2b7b0c66a7f24747a63a34c0854e5 Mon Sep 17 00:00:00 2001
From: wx <2636507191@qq.com>
Date: Sun, 26 Jul 2026 17:34:23 +0800
Subject: [PATCH] docs(changelog): hand off final-confirm itinerary SMS (#5263)

---
 ...¡®è®¤æŒ‰è½¦é€‰æ‹©å�‘é€�行程短信-修改接å�£-管ç�†å�Žå�°.md | 157 ++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 changelogs-v2/2026-07/26_5263_最终确认按车选择��行程短信-修改接�-管���.md

diff --git a/changelogs-v2/2026-07/26_5263_最终确认按车选择��行程短信-修改接�-管���.md b/changelogs-v2/2026-07/26_5263_最终确认按车选择��行程短信-修改接�-管���.md
new file mode 100644
index 0000000..b30b6bb
--- /dev/null
+++ b/changelogs-v2/2026-07/26_5263_最终确认按车选择��行程短信-修改接�-管���.md
@@ -0,0 +1,157 @@
+---
+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)
+- Changelog PR: [wx/hl-api-changelog#41](https://git.1814.love:8443/wx/hl-api-changelog/pulls/41)
+- �务：`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`。