# 【前端待处理·管理后台】#4933 车务矩阵图例与空闲格直接派单

## 目标前端

- 端类型：管理后台（Web）
- 目标仓库：`mmg/hl-ui`
- 仓库地址：<https://git.1814.love:8443/mmg/hl-ui.git>
- 联调/验收环境：<http://192.168.100.160:9527>
- 小程序：无需处理，本问题仅涉及管理后台车务矩阵页面
- H5：无需处理，本问题仅涉及管理后台车务矩阵页面

## 问题与结论

2026-07-21 在车务管理员角色访问 `/fleet/matrix` 时确认两处前端缺陷：

1. 页面图例仍显示“绿 海拉尔接/送机、橙 外地接/送机”，把地域误当成衔接状态；这与 #4933 已确认的后端语义不一致。
2. 点击车辆空闲格只弹出“请先从未派订单池拖拽或在订单详情发起派单”，阻断了矩阵页直接派单。矩阵页已有 `AssignModal` 和车辆预选能力，应直接进入本页派单流程。
3. 订单详情“历史操作”把保险退保结果的内部 JSON 原样拼进业务时间线，业务人员无法阅读。
4. 矩阵只解释衔接标记，未解释蓝灰色派车占用条；同车出现重叠时也没有冲突语义。后端 #5109 将统一过滤取消记录，前端仍需区分普通占用与有效派车重叠异常。

后端 #5109 已统一矩阵统计与占用条口径，并新增有效派车重叠异常字段。前端必须消费后端下发的衔接状态和异常信息，不能按“海拉尔/外地”或占用条颜色自行推导。

## 图例适配要求

图例按 `connections[].status/style` 固定展示以下四种业务语义：

| `status` | `style` | 图例文案 | 展示要求 |
| --- | --- | --- | --- |
| `SAME_CITY_OK` | `GREEN` | 同城衔接正常 | 绿色实线/标记 |
| `DIFFERENT_CITY` | `DARK_RED` | 不同城 | 深红色实线/强提醒 |
| `SAME_CITY_TOO_SHORT` | `LIGHT_RED` | 同城间隔不足 | 淡红色实线/提醒 |
| `MISSING_TIME` | `RED_DASHED` | 缺少接送信息 | 红色虚线 |

- 删除“海拉尔接/送机”“外地接/送机”两项旧图例。
- 图例颜色、矩阵连线/标记和悬浮详情必须使用同一份状态映射。
- 悬浮详情优先展示后端 `label`、`reasonText`、`intervalMinutes`、`minIntervalMinutes`；不得覆盖后端文案或重新计算状态。

图例应分成两组，避免混淆：

- 派车占用：说明订单占用条的基础颜色、边框及文字含义。
- 订单衔接：继续展示上述四种后端衔接状态。

若后端返回有效派车重叠异常标记，必须使用独立冲突样式和明确文案，不能复用普通占用色，也不能把两条记录静默叠放。

## 历史操作展示要求

- 时间线默认只展示 `opTypeLabel`、`operationStatusLabel`、`summary`、操作时间和业务操作人。
- `detailJson` 仅供诊断或折叠的技术明细使用，不得直接拼接到 `content`，不得默认展示 JSON。
- 保险退保成功示例应展示为“司机保险退保成功 / 已完成 / 共 1 个服务日，线上成功 1，线下完成 0”，不展示 `resolution`、`refundResult`、日期数组等内部字段名。
- `canceled` 且有效派车组为 0 的订单可在详情中查看取消时间线，但不能在矩阵中继续绘制占用条。

## 空闲格直接派单要求

用户点击车辆某日的空闲格后，应在当前矩阵页面完成派单：

1. 打开未派订单选择层（或复用现有选择组件），只列出当前筛选范围内可派订单。
2. 选中订单后打开现有 `AssignModal`。
3. 自动预选被点击车辆，并将点击日期带入派单日期上下文；仍允许用户在弹窗内调整司机、车辆和合法日期范围。
4. 按现有候选、预校验和创建派单接口完成校验与提交，不能绕过冲突、容量、常驻错配确认等后端门禁。
5. 成功后关闭弹窗并刷新矩阵、统计和未派订单数量；失败时保留用户已填内容并展示后端错误。
6. 当确实没有可派订单时才显示空态“暂无可派订单”，不得再提示用户去订单详情发起派单。

建议直接修正当前 `@idle-click="onIdleClick"` 分支：现实现只调用 `message.info`，但同页已经挂载 `AssignModal`、`activeOrder`、`preselectVehicle` 和 `assignMode`，应复用现有派单链路。

## 接口证据

矩阵响应已提供后端判定结果，核心字段位于车辆相邻订单衔接集合 `connections`：

```json
{
  "status": "SAME_CITY_OK",
  "label": "同城衔接正常",
  "style": "GREEN",
  "reasonCode": "SAME_CITY_INTERVAL_SUFFICIENT",
  "reasonText": "同城前后订单衔接间隔满足配置阈值",
  "intervalMinutes": 180,
  "minIntervalMinutes": 120
}
```

后端允许值：

- `status`：`MISSING_TIME`、`DIFFERENT_CITY`、`SAME_CITY_TOO_SHORT`、`SAME_CITY_OK`
- `style`：`RED_DASHED`、`DARK_RED`、`LIGHT_RED`、`GREEN`

每辆车新增 `overlaps`，仅在两个不同的有效派车组日期重叠时返回；无异常时固定为空数组：

```json
{
  "id": "100",
  "assignments": [],
  "overlaps": [
    {
      "firstAssignmentGroupId": "1001",
      "secondAssignmentGroupId": "1002",
      "overlapStartDate": "2026-05-03",
      "overlapEndDate": "2026-05-04",
      "code": "ACTIVE_ASSIGNMENT_OVERLAP",
      "message": "同一车辆存在有效派车日期重叠"
    }
  ]
}
```

- `canceled` 派车切片不进入 `assignments`、顶部统计、衔接计算或 `overlaps`。
- 同一派车组的有效日期被取消日切断时，`assignments` 返回两个不连续日期段，但顶部仍按一个派车组计数。
- `unassigned-orders` 条目及 `parallelAssignments[]` 新增 `serviceDateSegments[]`，每项包含 `startDate/endDate`；存在取消日期缺口时返回多个连续有效段。旧 `startDate/endDate` 仅表示该组总体边界，前端绘制或判断逐日有效性必须以 `serviceDateSegments` 为准。
- `overlaps` 是明确的数据异常，不是新的普通占用颜色；前端应显示独立冲突提示并允许定位涉及的两个派车组。

派单继续复用现有车务候选、预校验和创建派单接口，不新增接口。

## 验收清单

- [ ] `/fleet/matrix` 图例只展示四种后端衔接语义，不再出现地域型图例。
- [ ] 构造四种 `status/style` 数据，图例、矩阵标记和悬浮说明三者一致。
- [ ] 点击任意车辆空闲格可在当前页面选择未派订单并打开派单弹窗。
- [ ] 派单弹窗自动预选点击车辆及日期上下文。
- [ ] 正常派单成功后矩阵、统计与未派数刷新。
- [ ] 冲突或校验失败时展示后端错误且不产生半成品派单。
- [ ] 无可派订单时展示空态，不再引导去订单详情。
- [ ] 图例分别说明“派车占用”和“订单衔接”，普通占用、衔接标记与重叠异常不会混淆。
- [ ] 历史操作默认不显示或拼接 `detailJson`，保险退保记录使用中文业务摘要。
- [ ] 已取消且有效派车组为 0 的订单只保留详情历史，不绘制矩阵占用条。
- [ ] `vehicles[].overlaps[]` 非空时展示明确重叠异常；为空时不显示冲突样式。
- [ ] 在 <http://192.168.100.160:9527> 以车务管理员角色完成页面、Network/API 响应和截图验收。

## 现场证据

- 页面：`/fleet/matrix`
- 角色：车务管理员
- 现象：错误地域图例；点击车辆空闲格连续出现阻断性提示
- 现场截图：由 #4933 验收反馈于 2026-07-21 提供
- 当前调试 Chrome 登录态已失效，自动复核跳转登录页；修复后需在上述固定验收环境重新登录并完成验收清单。
