From 584f0b76edf3b35657e291d1711867ee9e0d151b Mon Sep 17 00:00:00 2001
From: wx <2636507191@qq.com>
Date: Sun, 19 Jul 2026 19:34:19 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=80=9A=E7=9F=A5=E8=BD=A6=E5=8A=A1?=
 =?UTF-8?q?=E6=B4=BE=E5=8D=95=E5=8F=AF=E9=9D=A0=E9=80=9A=E7=9F=A5=E4=B8=8E?=
 =?UTF-8?q?=E5=8F=96=E6=B6=88=E9=87=8D=E6=B4=BE=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...�¯é� é€šçŸ¥å�–消é‡�派与å�‘é€�状æ€�-修改接å�£-管ç�†å�Žå�°.md | 370 ++++++++++++++++++
 1 file changed, 370 insertions(+)
 create mode 100644 changelogs-v2/2026-07/68_4933_车务派���通知�消�派与��状�-修改接�-管���.md

diff --git a/changelogs-v2/2026-07/68_4933_车务派���通知�消�派与��状�-修改接�-管���.md b/changelogs-v2/2026-07/68_4933_车务派���通知�消�派与��状�-修改接�-管���.md
new file mode 100644
index 0000000..4c67916
--- /dev/null
+++ b/changelogs-v2/2026-07/68_4933_车务派���通知�消�派与��状�-修改接�-管���.md
@@ -0,0 +1,370 @@
+# ��端对接·管���】车务派���通知��消��派与��状�契约
+
+> Issue: [wx/HL#4933](https://git.1814.love:8443/wx/HL/issues/4933)
+>
+> PR: [wx/HL#5073](https://git.1814.love:8443/wx/HL/pulls/5073)�[wx/HL#5084](https://git.1814.love:8443/wx/HL/pulls/5084)
+>
+> �务: `hl-fleet-service` / `hl-user-service` / `hl-order-service-v3` / `hl-gateway`
+>
+> 日期: 2026-07-19
+>
+> 影�范围: 派�/改派弹窗�派�详情�作记录�通知��日志�订�详情推�记录��消��新派车
+
+## 一��端结论
+
+- `holdMode=1` 的创建派�和改派现在会冻结本次通知模�与正文，并由�端异步执行��短信��。
+- 创建 HOLD �功�表示派�和通知�图已�库；首次�应中的 `holdSentAt` 固定为 `null`。�有供应商真实���，派�详情的 `currentAssignment.holdSentAt` �会回显��时间。
+- 通知日志 `status` 已从旧的少�状�扩展为 `0~6`。�端必须展示“投递中�结果�确定�授�撤销�，�得把它们归并����功或失败。
+- �消派��功�，�端会��地把当�生效用车需求�新打开，�许�次派车；该过程为最终一致。�端刷新看�和详情，并以最新 `canAssign`/当�需求状�决定是�开放�派，�调用内部�开接�。
+- 订�详情推�记录的归一化状�枚举已调整，�端需��步新枚举。
+- `/internal/**`�`/v3/internal/**` �为�务间接�，�网关调用返回业务� `403`；任何 Web/�程�代�都�得调用。
+
+## 二��端�调用接�
+
+| 接� | 方法 | 路径 | 本轮�化 |
+|---|---|---|---|
+| 创建派� | POST | `/admin/fleet/assignments` | 新增 `messageTemplateId/customBody`；明确 `holdSentAt` 语义 |
+| 修改派� | POST | `/admin/fleet/assignments/{assignmentId}/change` | HOLD 改派新增 `messageTemplateId/customBody` |
+| 派�看�详情 | GET | `/admin/fleet/board/orders/{orderId}` | 回显真实 `holdSentAt`；�作记录补��消/退�完整时间线 |
+| 派�看�汇总 | GET | `/admin/fleet/board/summary` | �消�刷新当�状�与能力字段 |
+| 派�看�列表 | GET | `/admin/fleet/board/orders` | �消�刷新当�状�与能力字段 |
+| 通知��日志 | GET | `/admin/notification/logs` | 状�扩展为 `0~6`，新增��投递审计字段 |
+| 通知��统计 | GET | `/admin/notification/logs/stats` | 新增跳过�投递中��确定�撤销等统计 |
+| 人工核对��短信 | PUT | `/admin/notification/logs/{id}/resolve-reliable` | 新增，仅专用���用 |
+| 订�详情推�记录 | GET | `/v3/admin/order/{id}/push-records` | 归一化状�枚举调整 |
+
+## 三�创建/修改 HOLD 派�
+
+### 3.1 请求字段
+
+两个写接�新增相�的�选字段：
+
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `messageTemplateId` | string | HOLD 通知模� ID；�空，空时使用 `hold_notify` 默认模�；`holdMode=0` 时忽略 |
+| `customBody` | string | 本次通知自定义正文；�空，最大 4000 字符；�冻结本次内容，�回写模� |
+
+所有雪花 ID 继续按字符串传递和�存，�止转为 JavaScript `Number`。
+
+创建 HOLD 请求示例：
+
+```http
+POST /admin/fleet/assignments
+Content-Type: application/json
+Authorization: Bearer <fleet-admin-token>
+```
+
+```json
+{
+  "orderId": "2074746808742928386",
+  "requirementId": "2075001000000000001",
+  "vehicleId": "2076001000000000001",
+  "driverId": "2077001000000000001",
+  "startDate": "2026-07-20",
+  "endDate": "2026-07-22",
+  "headcount": 4,
+  "holdMode": 1,
+  "messageTemplateId": "20260706000101",
+  "customBody": "王师傅您好，26-7218 团 7 月 20 日待确认。",
+  "fromEntry": "from-board",
+  "requestId": "hold-2074746808742928386-001"
+}
+```
+
+修改为 HOLD 请求示例：
+
+```http
+POST /admin/fleet/assignments/2078001000000000001/change
+Content-Type: application/json
+Authorization: Bearer <fleet-admin-token>
+```
+
+```json
+{
+  "effectiveDate": "2026-07-21",
+  "newVehicleId": "2076001000000000002",
+  "newDriverId": "2077001000000000002",
+  "holdMode": 1,
+  "messageTemplateId": "20260706000101",
+  "customBody": "�师傅您好，本团 7 月 21 日起调整由您�务，请确认。",
+  "reason": "原�机临时无法执行",
+  "requestId": "change-2078001000000000001-001"
+}
+```
+
+### 3.2 创建�应与 `holdSentAt`
+
+HOLD 创建�功�应示例：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "id": "2078001000000000001",
+    "assignmentGroupId": "2078001000000000001",
+    "assignmentSlotId": "2078001000000000001",
+    "assignmentStatus": "holding",
+    "stageCode": "holding_wait_driver",
+    "stageLabel": "排车中·等待�机确认",
+    "currentStep": 3,
+    "skippedStepCodes": [],
+    "protocolPrice": "1300.00",
+    "holdSentAt": null,
+    "confirmedAt": null,
+    "sideEffects": null,
+    "dailyDifferences": []
+  }
+}
+```
+
+�端处�规则：
+
+1. `code=200` 且 `assignmentStatus=holding` �立�关闭���交入�，并刷新详情。
+2. `holdSentAt=null` �是接�失败，也�能显示“短信已���；应显示“通知处�中/等待��结果�。
+3. �续读� `GET /admin/fleet/board/orders/{orderId}`，仅当 `currentAssignment.holdSentAt` �空时显示真实��时间。
+4. 模�缺失�供应商失败或结果�确定时，派���� `holding`，�端通过通知日志查看真实状�，�自行改派�状�。
+
+## 四�通知��日志状�
+
+### 4.1 状�枚举
+
+`GET /admin/notification/logs` 的请求筛选�数和�应字段 `status` 统一使用：
+
+| status | �义 | �端展示建议 |
+|---:|---|---|
+| 0 | ���功，供应商明确�� | �功 |
+| 1 | 明确失败 | 失败 |
+| 2 | 无收件人 | 已跳过·无收件人 |
+| 3 | 无模� | 已跳过·无模� |
+| 4 | 投递中 | 投递中 |
+| 5 | 结果�确定 | 待核对 |
+| 6 | 授�撤销 | 已撤销 |
+
+�端�得把 `4/5/6` 计入�功或失败。状� `5` 也�能自动��，��供应商实际已��时��通知�机。
+
+��日志新增字段：
+
+```json
+{
+  "id": 2080001000000000001,
+  "eventCode": "FLEET_DISPATCH_CREATED",
+  "channel": "SMS",
+  "bizId": "2078001000000000001",
+  "bizType": "FLEET_ASSIGNMENT_HOLD",
+  "status": 5,
+  "latestProviderAttemptAt": "2026-06-19T10:00:00",
+  "providerSentAt": null,
+  "resultTime": null,
+  "manualResolvedAt": null,
+  "manualResolvedBy": null,
+  "manualResolutionReason": null
+}
+```
+
+新增统计字段：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "totalToday": 20,
+    "successToday": 12,
+    "failToday": 2,
+    "skippedToday": 3,
+    "dispatchingToday": 1,
+    "unknownToday": 1,
+    "canceledToday": 1,
+    "terminalAttemptToday": 14,
+    "successRate": 85.71,
+    "channelStats": []
+  }
+}
+```
+
+`successRate` 的分�是 `terminalAttemptToday = successToday + failToday`，�端���用 `totalToday` 自行计算。
+
+## 五�人工核对结果�确定短信
+
+该入��处�超过供应商 29 天查询窗���为 `status=5` 的车务��短信，并�求 `NOTIFICATION_RELIABLE_RESOLVE` 专用��。当��端�授予 `SUPER_ADMIN`；普通管�员�使手工构造请求也会被拒�。
+
+确认已��：
+
+```http
+PUT /admin/notification/logs/2080001000000000001/resolve-reliable
+Content-Type: application/json
+Authorization: Bearer <super-admin-token>
+```
+
+```json
+{
+  "resolution": "SUCCESS",
+  "reason": "阿里云控制���记录核对，工� SMS-20260719-001",
+  "externalMessageId": "SMS-20260719-001",
+  "providerSentAt": "2026-06-19T10:00:30"
+}
+```
+
+确认未��：
+
+```json
+{
+  "resolution": "NOT_SENT",
+  "reason": "阿里云控制�未查到对应��记录",
+  "externalMessageId": null,
+  "providerSentAt": null
+}
+```
+
+�功�应：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": null
+}
+```
+
+处�规则：
+
+- `SUCCESS` 必须传 `externalMessageId` 和 `providerSentAt`；事实时间必须�于最近一次供应商�试时间�� 5 分钟内。
+- `NOT_SENT` �得传 `providerSentAt`。
+- 请求返回 `100001` 表示�数或��时间��法；返回 `100003` 表示无���日志�符�人工核对�件或状�已�化。
+- �作�功�刷新当�日志行和统计；��在�端直接篡改状�。
+
+## 六�订�详情推�记录状�
+
+`GET /v3/admin/order/{id}/push-records` 的 `records[].status` 改为：
+
+| status | �义 |
+|---|---|
+| `SENT` | 供应商明确�� |
+| `FAILED` | 明确失败 |
+| `SKIPPED_NO_RECIPIENT` | 无收件人 |
+| `SKIPPED_NO_TEMPLATE` | 无模� |
+| `DISPATCHING` | 投递中 |
+| `UNKNOWN` | 结果�确定 |
+| `CANCELED` | 授�已撤销 |
+| `UNRECOGNIZED` | 未识别的存�状� |
+
+�应示例：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "total": 1,
+    "records": [
+      {
+        "id": 2080001000000000001,
+        "eventCode": "FLEET_DISPATCH_CREATED",
+        "channel": "SMS",
+        "channelName": "短信",
+        "kind": "sms",
+        "target": "王师傅",
+        "status": "UNKNOWN",
+        "statusName": "结果�确定",
+        "rawStatus": 5,
+        "failReason": null,
+        "bizId": "2078001000000000001",
+        "bizType": "FLEET_ASSIGNMENT_HOLD",
+        "sentAt": "2026-07-19T10:00:00"
+      }
+    ],
+    "summary": {
+      "all": 1,
+      "sms": 1,
+      "miniapp": 0,
+      "officialAccount": 0,
+      "inapp": 0,
+      "internal": 0,
+      "wework": 0,
+      "other": 0,
+      "failed": 0
+    }
+  }
+}
+```
+
+`summary.failed` �统计 `rawStatus=1`，�包� `UNKNOWN/DISPATCHING/CANCELED`。
+
+## 七��消��新派车
+
+�端�调用既有接��消：
+
+```http
+DELETE /admin/fleet/assignments/{assignmentId}
+```
+
+�功�的正确�程：
+
+1. 接��消�应中的 `assignmentStatus=canceled`。
+2. �新请求 `/admin/fleet/board/summary`�`/admin/fleet/board/orders` 和 `/admin/fleet/board/orders/{orderId}`。
+3. �端完�需求�开�，当�订��新出现�派状�；按钮�看最新�应的 `canAssign`，��本地强制改为�派。
+4. 如果首次刷新�未开放�派，��处�中并短暂�试刷新；��调用 `/v3/internal/order/**`，也��让用户���消。
+5. �新派车�功��次刷新�务端状�，�能沿用已�消派�的 `assignmentId`。
+
+派�详情 `operationLog.records[]` 会�留����消时间线，新增/强化的 `opType` 包括：
+
+- `cancel_requested`
+- `driver_notification_recorded`
+- `cancel_evidence_recorded`
+- `insurance_refund_pending`
+- `insurance_refund_succeeded`
+- `insurance_refund_failed`
+- `cancel_completed`
+- `cancel_restored`
+- `cancel_failed`
+
+�端优先展示�端返回的 `opTypeLabel`�`operationStatusLabel` 和 `summary`，���维护中文文案。`operationStatus` �许 `pending/succeeded/failed`。
+
+## 八�网关 internal 边界
+
+下列路径全部�止客户端调用：
+
+```text
+/internal
+/internal/**
+/v3/internal
+/v3/internal/**
+```
+
+网关按项目�议返回 HTTP 200，但�应体为：
+
+```json
+{
+  "code": 403,
+  "message": "接���访问",
+  "success": false,
+  "data": null
+}
+```
+
+请�端全仓检查是��有 `/v3/internal/mp/**` 等历�调用；如存在，��自行改��一个 internal 地�，应�馈�端补正� BFF/admin 契约。
+
+## ���端待处�清�
+
+- [ ] 派�/改派弹窗在 HOLD 模�支� `messageTemplateId/customBody`，DIRECT 模���交或忽略这两个字段。
+- [ ] HOLD 创建�功时把 `holdSentAt=null` 展示为处�中，�显示“已���。
+- [ ] 通知日志筛选�标签和统计适� `0~6` 状��新增字段。
+- [ ] 仅对具备专用��的账�展示“人工核对��短信�入�，并实现 `SUCCESS/NOT_SENT` 两�表�校验。
+- [ ] 订�详情推�记录适�新的归一化状�枚举。
+- [ ] �消派��刷新�务端状�，以 `canAssign` 控制�新派车入�。
+- [ ] 确认�端�存在任何 `/internal/**` 或 `/v3/internal/**` 调用。
+- [ ] 所有雪花 ID ��字符串。
+
+## ���端交付与测试环境状�
+
+- �端 PR #5073�#5084 已�并到 `dev-v3`。
+- `hl-order-service-v3`�`hl-fleet-service`�`hl-gateway` 已按顺�部署 TEST，�实例�康；当� OpenAPI 已公开本文全部管�端接�。
+- 已用真实测试订�完� DIRECT��消�需求�开��次 DIRECT��机�步和退�时间线验收。
+- TEST 当� `hold_notify` 短信模��是���置，真实 HOLD 短信会失败关闭，`holdSentAt` �� `null`；这是环境�置阻塞，�应由�端伪造����功。
+- 本文件��契约交接，�修改 `hl-ui`。
+