wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

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

浏览代码
这个提交包含在：
API Changelog Bot 2026-07-12 17:29:01 +08:00
父节点 77ba6986b1
当前提交 ccbe202637
共有 1 个文件被更改，包括 529 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

529
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` 为准；本文只补充事务可靠性实现和验收证据。