docs(fleet): 补齐4882派单看板契约与验收证据

2026-07-12 17:29:01 +08:00 · 2026-07-12 17:29:01 +08:00 · ccbe202637
--- a/changelogs-v2/2026-07/57_4882_车务派单看板当前订单字段统计行程与保险事务收口-管理后台.md
+++ 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` 为准；本文只补充事务可靠性实现和验收证据。