From ccbe2026374ad2d69ec94f8bc0eae0b0d33ac88a Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sun, 12 Jul 2026 17:29:01 +0800
Subject: [PATCH] =?UTF-8?q?docs(fleet):=20=E8=A1=A5=E9=BD=904882=E6=B4=BE?=
 =?UTF-8?q?=E5=8D=95=E7=9C=8B=E6=9D=BF=E5=A5=91=E7=BA=A6=E4=B8=8E=E9=AA=8C?=
 =?UTF-8?q?=E6=94=B6=E8=AF=81=E6=8D=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...�¿å½“å‰�订å�•å­—段统计行程与ä¿�险事务收å�£-管ç�†å�Žå�°.md | 529 ++++++++++++++++++
 1 file changed, 529 insertions(+)
 create mode 100644 changelogs-v2/2026-07/57_4882_车务派�看�当�订�字段统计行程与�险事务收�-管���.md

diff --git a/changelogs-v2/2026-07/57_4882_车务派�看�当�订�字段统计行程与�险事务收�-管���.md b/changelogs-v2/2026-07/57_4882_车务派�看�当�订�字段统计行程与�险事务收�-管���.md
new file mode 100644
index 0000000..7a62ed9
--- /dev/null
+++ b/changelogs-v2/2026-07/57_4882_车务派�看�当�订�字段统计行程与�险事务收�-管���.md
@@ -0,0 +1,529 @@
+# ��端对接·管���】车务派�看�当�订�字段�统计�行程与�险事务收�
+
+> Issue: [wx/HL#4882](https://git.1814.love:8443/wx/HL/issues/4882)
+> PR: [wx/HL#4897](https://git.1814.love:8443/wx/HL/pulls/4897) / [wx/HL#4898](https://git.1814.love:8443/wx/HL/pulls/4898) / [wx/HL#4920](https://git.1814.love:8443/wx/HL/pulls/4920)
+> �务: `hl-fleet-service` / `hl-order-service-v3` / `hl-user-service`
+> 日期: 2026-07-12
+> 影�范围: 车务派�看��派�弹窗详情�状�统计�筛选��日行程��机险自动投退���性
+
+## 1. 对接结论
+
+- 派�看�继续使用分页接�，默认 `page=1&pageSize=20`，`pageSize` 最大 100；��一次性全�拉�。
+- 看��片�筛选和详情以 order-v3 的**当�订�**�**当� active 用车需求**为��数��，��使用旧派�快照覆盖当�团���系人�定制师�日期或诉求。
+- 汇总和列表使用�一套“当�需求 + 派车组状��投影。`summary.statusOptions[].count` 必须和对应状�列表的 `total` 一致。
+- 日期筛选�紧急��排��详情起止日期和�日行程�使用当�订�档期；改期��得展示旧日期。
+- `itinerary.days` �自 `order_itinerary_day`，一天一�；无有效�日行程时返回空数组，�生�伪数�。
+- 定制师显示优先使用 `consultantDisplayName`；�端已按�业微信昵称优先�用户�兜底处�。
+- �端��自己映射车务状�中文，也��自行计算能�派车/驳回；直接使用�端返回的 `statusOptions`�`assignmentStatusLabel`�`canAssign`�`canRejectRequirement`。
+- �机险��性本轮没有新增管���请求字段。派� `ASSIGNED/RESTORED/CANCELED/COMPLETED` 与�险动作改为事务 Outbox，并由 user 微�务既有 Quartz 框架�放兜底。
+
+## 2. 接�清�
+
+| # | 接� | 方法 | 路径 | 本轮契约 |
+|---|------|------|------|----------|
+| 1 | 派�看�汇总 | GET | `/admin/fleet/board/summary` | 六项概览�全状�计数和状�文案统一由�端返回 |
+| 2 | 派�看�列表 | GET | `/admin/fleet/board/orders` | 当�订�字段�组�筛选�确定性排��分页总数收� |
+| 3 | 派�看�详情 | GET | `/admin/fleet/board/orders/{orderId}` | 当�订��当�需求��日行程�大交通�动�步骤和�作记录一次返回 |
+| 4 | 派�时间线 | GET | `/admin/fleet/board/orders/{orderId}/timeline` | 派车域已�生事件，按时间��返回 |
+| 5 | Outbox �放 | POST | `/internal/fleet/jobs/assignment-insurance-outbox/replay` | 仅 user Quartz �内部 Feign 调用，�对�端开放 |
+
+## 3. 派�看�汇总
+
+### 3.1 请求
+
+```http
+GET /admin/fleet/board/summary
+Authorization: Bearer <fleet-manager-token>
+```
+
+无请求�数。
+
+### 3.2 �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "pendingCount": 26,
+    "pendingUrgentCount": 4,
+    "todayDepartCount": 2,
+    "idleVehicleCount": 9,
+    "idleDriverCount": 5,
+    "holdingTimeoutCount": 1,
+    "statusCounts": {
+      "unassigned": 26,
+      "holding": 2,
+      "assigned": 8,
+      "changeRequested": 0,
+      "completed": 32,
+      "canceled": 43,
+      "unassignedUrgent": 4,
+      "holdingUrgent": 1
+    },
+    "statusOptions": [
+      {
+        "value": "unassigned",
+        "label": "待派车",
+        "description": "已�出有效用车需求，车务尚未派车",
+        "count": 26,
+        "urgentCount": 4
+      },
+      {
+        "value": "holding",
+        "label": "排车中",
+        "description": "车务已派车，�机未回�确认",
+        "count": 2,
+        "urgentCount": 1
+      },
+      {
+        "value": "assigned",
+        "label": "已派车",
+        "description": "�机已确认，派车已生效",
+        "count": 8,
+        "urgentCount": 0
+      },
+      {
+        "value": "change_requested",
+        "label": "�车请求",
+        "description": "客户或车务�出�车待处�",
+        "count": 0,
+        "urgentCount": 0
+      },
+      {
+        "value": "completed",
+        "label": "已完结",
+        "description": "用车行程已完结",
+        "count": 32,
+        "urgentCount": 0
+      },
+      {
+        "value": "canceled",
+        "label": "已�消",
+        "description": "派车需求已�消",
+        "count": 43,
+        "urgentCount": 0
+      }
+    ]
+  }
+}
+```
+
+> 上述数字仅用于说明�应结构，�是固定业务值。页��次读�接�实时结果。
+
+### 3.3 一致性规则
+
+```text
+statusOptions[value=unassigned].count
+  == 未附加其他筛选时 GET /admin/fleet/board/orders?statuses=unassigned 返回的 data.total
+```
+
+- 统计维度是派车组，�是数�库�日切片行数。
+- �订�旧需求�已失效需求和孤儿派��计入当�看�。
+- `pendingCount` 与 `statusCounts.unassigned` 是�一业务�径；�端�二选一展示，��相加。
+- 状�筛选值�中文�和急�数直接读� `statusOptions`，�端�得维护独立枚举文案。
+
+## 4. 派�看�列表
+
+### 4.1 请求示例
+
+```http
+GET /admin/fleet/board/orders?page=1&pageSize=20&statuses=unassigned,holding&startDate=2026-07-01&endDate=2026-07-31&typeKeys=suv&keyword=7218&consultantId=2021059720172838914
+Authorization: Bearer <fleet-manager-token>
+```
+
+### 4.2 查询�数
+
+| �数 | 类型 | 必填 | 规则 |
+|------|------|------|------|
+| `page` | int | � | 默认 1。 |
+| `pageSize` | int | � | 默认 20，最大 100。 |
+| `statuses` | string[] | � | 多状�任一命中；支��� query �数或逗�分隔。 |
+| `status` | string | � | 兼容�状�/逗�分隔写法，与 `statuses` �并。 |
+| `startDayFrom` / `startDate` | date | � | 日期起，两个�数是别�；与当�行程区间���匹�。 |
+| `startDayTo` / `endDate` | date | � | 日期止，两个�数是别�；与当�行程区间���匹�。 |
+| `vehicleTypeKeys` / `typeKeys` | string[] | � | 车型大类多选。未派按当�需求车型，已派按实际车辆大类。 |
+| `driverName` | string | � | �机姓�模糊匹�。 |
+| `keyword` | string | � | 统一包�匹�：�机��系人/客户�团��订��。 |
+| `contactName` / `contactKeyword` | string | � | �系人/客户�模糊匹�。 |
+| `teamNo` | string | � | 团�包�匹�，例如 `7218` �命中 `26-7218`。 |
+| `consultantId` | string | � | 当�负责定制师 ID 精确匹�，值�自定制师下拉。 |
+| `plannerName` / `consultantName` | string | � | 旧�端兼容的定制师文本筛选；新页�使用 `consultantId`。 |
+| `variant` | string | � | `list`（默认）或 `grid`；其他值返回�数错误。 |
+
+状�值：
+
+```text
+unassigned / unassigned_urgent / holding / holding_urgent /
+assigned / change_requested / canceled / completed
+```
+
+其中：
+
+- `holding` 的业务�义是“排车中�，�车务已派�机��机尚未确认。
+- `unassigned_urgent` 和 `holding_urgent` 是�端实时派生�，�是独立�库状�。
+- `change_requested` 当�无独立�车请求表时�能�为空；�端�按 `statusOptions` 渲染。
+
+### 4.3 �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "page": 1,
+    "pageSize": 20,
+    "total": 1,
+    "records": [
+      {
+        "id": "HL20260708144557879",
+        "orderNo": "HL20260708144557879",
+        "orderId": "2074746808742928386",
+        "teamNo": "26-7218",
+        "unreadMessageCount": 0,
+        "assignmentId": "2075001000000000001",
+        "assignmentGroupId": "2075001000000000001",
+        "fleetItemIndex": 0,
+        "customerName": "何�墨",
+        "contactName": "何�墨",
+        "productName": "测试核心产�-�档-固定订金",
+        "headcount": 2,
+        "adultCount": 2,
+        "childCount": 0,
+        "youngChildCount": 0,
+        "babyCount": 0,
+        "startDate": "2026-07-20",
+        "endDate": "2026-07-22",
+        "days": 3,
+        "pickupAt": "海拉尔东山机场",
+        "dropoffAt": "海拉尔站",
+        "isHailarPickup": true,
+        "isHailarDropoff": true,
+        "consultantId": "2021059720172838914",
+        "plannerName": "王�",
+        "consultantName": "王�",
+        "consultantDisplayName": "王�",
+        "customerNote": "需�接�机",
+        "vehicleAdvice": null,
+        "specialTags": ["大行�空间", "有 WiFi"],
+        "requirementRemark": "接机�直接�往酒店",
+        "requiredVehicles": [
+          {
+            "vehicleType": "suv",
+            "categoryLabel": "SUV系列",
+            "seats": 5,
+            "count": 1
+          }
+        ],
+        "assignmentStatus": "unassigned_urgent",
+        "assignmentStatusLabel": "待派车",
+        "currentVehiclePlate": null,
+        "currentVehicleModel": null,
+        "currentVehicleSeats": null,
+        "currentVehicleFleet": null,
+        "currentDriverName": null,
+        "currentDriverPhone": null,
+        "urgentBadge": "T-2",
+        "canAssign": true,
+        "canRejectRequirement": true
+      }
+    ]
+  }
+}
+```
+
+### 4.4 字段��与�端用法
+
+| �应字段 | ���� | �端规则 |
+|----------|----------|----------|
+| `orderNo/orderId` | 当� `order_main` | 雪花 ID 按字符串处�。 |
+| `teamNo` | 当� `order_main.team_no` | 没有团�时为 `null`，��显示旧快照团�。 |
+| `customerName/contactName` | 当�订��系人 | 两字段��径，�片优先读 `contactName`。 |
+| `headcount` 与四类人数 | 当�订�出行人统计 | �从派�数��推。 |
+| `startDate/endDate/days` | 当�订�档期 | `days=endDate-startDate+1`，�首尾。 |
+| `consultantId` | 当� `order_main.consultant_id` | 定制师下拉筛选值。 |
+| `consultantDisplayName` | 当�定制师，�微昵称优先 | �片无�件独立展示，�得�客户留言/车辆建议是�存在影�。 |
+| `specialTags/requirementRemark` | 当� active 用车需求 | �读�旧需求或派�快照。 |
+| `requiredVehicles` | 当�需求车型项 | 车型筛选和�片 chip 使用。 |
+| `assignmentStatusLabel` | �端状�投影 | �端直接展示。 |
+| `canAssign` | �端能力判断 | `true` �显示派车入�。 |
+| `canRejectRequirement` | �端能力判断 | `true` �显示驳回需求；已产生有效派��为 `false`。 |
+
+排�固定为：紧急待处�组置顶，普通进行中次之，终�沉底，�优先级使用稳定 ID 兜底。�端��二次改�，�则分页间会出现跳行或��。
+
+## 5. 派�看�详情
+
+### 5.1 请求
+
+```http
+GET /admin/fleet/board/orders/2074746808742928386
+Authorization: Bearer <fleet-manager-token>
+```
+
+`orderId` 是数字订� ID，�是订��。
+
+打开详情�，�端会�试把当� active 用车需求从待处�推进为 `PROCESSING`。车务没有抢�池，任何车务管�员都能处�全部车务订�。
+
+### 5.2 �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "id": "HL20260708144557879",
+    "orderNo": "HL20260708144557879",
+    "teamNo": "26-7218",
+    "customerName": "何�墨",
+    "headcount": 2,
+    "adultCount": 2,
+    "childCount": 0,
+    "youngChildCount": 0,
+    "babyCount": 0,
+    "startDate": "2026-07-20",
+    "endDate": "2026-07-22",
+    "pickupAt": "海拉尔东山机场",
+    "dropoffAt": "海拉尔站",
+    "productName": "测试核心产�-�档-固定订金",
+    "plannerName": "王�",
+    "consultantId": "2021059720172838914",
+    "consultantName": "王�",
+    "consultantDisplayName": "王�",
+    "plannerNote": null,
+    "customerNote": "需�接�机",
+    "requirements": "接机�直接�往酒店",
+    "vehicleAdvice": null,
+    "specialTags": ["大行�空间", "有 WiFi"],
+    "requirementRemark": "接机�直接�往酒店",
+    "itinerary": {
+      "theme": "�原深度 3 日",
+      "route": "海拉尔 → �尔�纳 → 满洲里",
+      "days": [
+        {
+          "dayNumber": 1,
+          "date": "2026-07-20",
+          "title": "海拉尔集�",
+          "detail": "接机�入�酒店"
+        },
+        {
+          "dayNumber": 2,
+          "date": "2026-07-21",
+          "title": "�原行程",
+          "detail": "�往�尔�纳"
+        },
+        {
+          "dayNumber": 3,
+          "date": "2026-07-22",
+          "title": "返程�站",
+          "detail": "�往海拉尔站"
+        }
+      ]
+    },
+    "transport": {
+      "transferTimeHint": null,
+      "arrive": null,
+      "depart": null,
+      "batches": [
+        {
+          "travelerNames": "何�墨, ��",
+          "transportNo": "CA1234",
+          "time": "2026-07-20 10:45:00",
+          "station": "海拉尔东山机场"
+        },
+        {
+          "travelerNames": "何�墨, ��",
+          "transportNo": "K1234",
+          "time": "2026-07-22 16:30:00",
+          "station": "海拉尔站"
+        }
+      ],
+      "pickupRequired": true
+    },
+    "progressSteps": [
+      {
+        "step": 1,
+        "code": "ORDER_DETAIL",
+        "label": "订�详情",
+        "status": "DONE",
+        "statusLabel": "已完�",
+        "active": false,
+        "time": "2026-07-12 16:22:14"
+      },
+      {
+        "step": 2,
+        "code": "DISPATCH",
+        "label": "排车",
+        "status": "PROCESSING",
+        "statusLabel": "进行中",
+        "active": true,
+        "time": "2026-07-12 16:22:14"
+      }
+    ],
+    "operationLog": {
+      "records": [],
+      "total": 0,
+      "summary": { "totalCount": 0 }
+    },
+    "currentAssignment": null,
+    "relatedDetailReady": true
+  }
+}
+```
+
+### 5.3 �日行程规则
+
+- `itinerary.days[].date` 必须�在当� `[startDate,endDate]` 内。
+- 改期�用当� `startDate + dayNumber - 1` 对�日期，历�旧档期行�能继续展示。
+- `order_itinerary_day` 中越界��法 `dayNumber` 或��旧版本数�会被过滤。
+- 结�日当天是有效行程日，�能误删。
+- 没有有效�日行程时：
+
+```json
+{
+  "itinerary": {
+    "theme": null,
+    "route": null,
+    "days": []
+  }
+}
+```
+
+�端显示“暂无�日行程�，�得按总天数生��行程。
+
+### 5.4 大交通空值规则
+
+有到达�返程或分批接�数�时，读� `arrive/depart/batches`。完全没有时间数�时：
+
+```json
+{
+  "transport": {
+    "transferTimeHint": "暂无接�机时间",
+    "arrive": null,
+    "depart": null,
+    "batches": [],
+    "pickupRequired": false
+  }
+}
+```
+
+### 5.5 �级规则
+
+- order-v3 正常：`relatedDetailReady=true`，返回当�订��当�需求��日行程和大交通。
+- order-v3 整体��达：fleet �回退本地派�快照，`relatedDetailReady=false`；�端显示“订�详情暂��用�，��把空字段当�真实无数�。
+- `currentAssignment=null` 表示当�没有有效派�，�表示接�失败。
+
+## 6. 派�时间线
+
+### 6.1 请求
+
+```http
+GET /admin/fleet/board/orders/2074746808742928386/timeline
+Authorization: Bearer <fleet-manager-token>
+```
+
+### 6.2 �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": [
+    {
+      "time": "2026-07-12 15:30:00",
+      "type": "requirement_received",
+      "actor": "系统",
+      "desc": "收到用车需求：SUV系列，5座，1辆"
+    },
+    {
+      "time": "2026-07-12 15:35:00",
+      "type": "hold_sent",
+      "actor": "车务",
+      "desc": "微信通知�机，等待确认"
+    }
+  ]
+}
+```
+
+- �返回已��生的车务事件，�补空步骤。
+- �一派车组的组级动作去�，�日完�事件按实际日期�留。
+- 无事件返回 `data=[]`。
+
+## 7. �险事务��性
+
+本节用于说明�端行为，�需�管���新增调用。
+
+### 7.1 触�关系
+
+| 派�动作 | Outbox 事件 | �险结果 |
+|----------|-------------|----------|
+| �机确认派� | `ASSIGNED` | 按当��机�险类型��务日检查/购买 |
+| ��已�消派� | `RESTORED` | ���障，且��机�日���购买 |
+| �消派� | `CANCELED` | 当天没有其他有效派�时退�；�有有效派�时�留 |
+| ��完结 | `COMPLETED` | �退完结截止日之����务的�� |
+
+### 7.2 一致性��
+
+- 派�状��更与 Outbox 事件�事务�库，��派��功但�险事件丢失。
+- �一派�按事件 ID 顺�处�；�继事件�会越过未完��驱。
+- 失败按退�时间�试，超时 `PROCESSING` ��新领�。
+- �轮最多扫� 100 �，��任务无界执行；这是�端技术�护，�是�端分页规则。
+- 定时�放�用 `hl-user-service` 的 `sys_job`/Quartz：`assignmentInsuranceOutboxJob.execute()`，�分钟执行一次。
+- 内部�放接�� `X-Internal-Token` �护，��置网关路由，�端/admin token �应直接调用。
+
+## 8. �端必须处�
+
+1. 看���分页，按 `data.total/page/pageSize` 驱动分页器。
+2. 状�筛选读� `summary.statusOptions`，��维护独立状�映射或独立计数。
+3. �片始终独立展示 `consultantDisplayName`，��放进 `vehicleAdvice/customerNote` 的�件�。
+4. �片展示当� `teamNo`�`contactName`�`headcount`�`startDate/endDate`�`specialTags`�`requirementRemark`。
+5. 定制师筛选使用 `/admin/user/customizers` 下拉的 `adminId`，传 `consultantId`。
+6. 文本�索框�统一传 `keyword`；�系人�团�和定制师下拉��作为高级精确筛选。
+7. 派车/驳回按钮�看 `canAssign/canRejectRequirement`；急�样��能���作按钮。
+8. 派�详情�日行程直接渲染 `itinerary.days`；空数组显示空�，�造�。
+9. 大交通完全为空时展示 `transport.transferTimeHint`。
+10. 所有雪花 ID 按字符串处�，�止转 JavaScript `Number`。
+
+## 9. �影�范围
+
+- �修改�端仓库，本文件仅��端契约告知。
+- �新增“�分页全�看��接�。
+- �改�车型大类�座�数��机�一座等既有业务规则。
+- �把�机险�本计入客户退款；�机险��计车队�本。
+- 团期�车本轮��。
+
+## 10. 测试环境验收��
+
+环境：`https://api.test.1814.love:9443`，真实角色账� `fleet_mgr_4760 / VEHICLE_MANAGER`�`designer_4760 / CUSTOMIZER`。
+
+```text
+代�验�
+- hl-fleet-service verify: 1537/1537
+- hl-user-service verify: 3168/3168
+- 独立�审: P0/P1=0
+
+部署
+- hl-fleet-service: task 77d19165，8087/8187 �实例�康
+- hl-user-service: task 0c32a732，8081/8181 �实例�康
+- hl-order-service-v3: task 06023fb6，8086/8186 �实例�康
+
+部署�真实网关�程
+- 126/126 通过，失败 0
+- 覆盖新建订��补全两�出行人�补全大交通��交用车需求�车务查看�派�预检�
+  排车��机确认��消（已/未通知�机）������机���完结��机拒接�未派驳回�
+  已派�止驳回�矩阵�车辆/�机�价格日历�对账��险任务与车管模�
+
+数�库地�真相
+- 本轮 3 个真实派�产生 8 ��险 Outbox 事件
+- ASSIGNED/CANCELED/RESTORED/COMPLETED 全部 SUCCESS，retryCount=0
+- sys_job 1037 为 ACTIVE，Quartz trigger 为 WAITING，最近 10 次执行全部 SUCCESS
+```
+
+## 11. 与既有文档关系
+
+- 本文补充并纠正 `53_4871_车务�需求派�看�闭环契约-管���.md` 的当�订�/当�需求�统计一致性和�日行程�径。
+- 定制师下拉�以 `54_4876_派�看�团�与定制师下拉筛选-管���.md` 为准。
+- �机险业务规则�以 `26_4760_车务�机险自动投退�闭环与�险��契约-管���.md` 为准；本文�补充事务��性实现和验收��。