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 +``` + +无请求参数。 + +### 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 +``` + +### 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 +``` + +`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 +``` + +### 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` 为准；本文只补充事务可靠性实现和验收证据。