# 【前端待处理·管理后台】#5156 车务团号、中文状态与常驻关系筛选

> **服务**: `hl-fleet-service`
> **Issue**: [wx/HL#5156](https://git.1814.love:8443/wx/HL/issues/5156)
> **日期**: 2026-07-22
> **影响范围**: 管理后台车务派单看板、订单详情、车务矩阵、派单候选弹窗

---

## 关键结论

1. 看板与矩阵的可见订单主标识统一使用完整团号：

   ```js
   const visibleOrderCode = teamNo?.trim() || orderNo?.trim() || '—'
   ```

   该规则只替换可见文案，不得用 `teamNo` 替换 `id`、`orderNumericId`、`assignmentId` 或 `assignmentGroupId`，不得改变行键、路由和派单接口入参。

   **2026-07-23 漏验收补充**：矩阵“已派订单占用条”的正文必须直接显示
   `visibleOrderCode`，不能只把团号放在鼠标悬浮 `title` 中。当前页面正文仍是
   “人员构成 · 路线”，车务无法在矩阵中直接识别团号。建议正文按
   “团号 · 人员构成 · 路线”排列；空间不足时优先保留完整团号，人员构成和路线可
   省略或截断，悬浮提示继续展示完整信息。

2. 订单详情 `activeAssignments[]` 新增 `assignmentStatusLabel`。页面只展示中文标签，例如 `assignmentStatus=assigned` 对应 `assignmentStatusLabel=已派车`；`assignmentStatus` 继续用于程序判断，不直接显示英文状态码。

3. 派单候选支持双向常驻关系展示和筛选：

   - 车辆候选有常驻司机时，展示 `primaryDriverName` 和 `primaryDriverMaskedPhone`；`vehicleKeyword` 支持车牌、车型、常驻司机姓名或 11 位完整手机号。
   - 司机候选有常驻车辆时，展示 `residentVehiclePlate`；`driverKeyword` 支持司机姓名、11 位完整手机号或常驻车牌。
   - 完整手机号只作为精确筛选入参，响应仍只返回脱敏手机号。

## 接口契约

### 1. 看板、详情与矩阵团号

| 页面场景 | 接口 | 团号字段 |
| --- | --- | --- |
| 看板列表 | `GET /admin/fleet/board/orders` | `data.records[].teamNo` |
| 看板详情 | `GET /admin/fleet/board/orders/{orderId}` | `data.teamNo` |
| 矩阵已派占用 | `GET /admin/fleet/matrix/grid` | `data.vehicles[].assignments[].teamNo` |
| 矩阵未派清单 | `GET /admin/fleet/matrix/unassigned-orders` | `data[].teamNo` |
| 矩阵单日清单 | `GET /admin/fleet/matrix/day-orders` | `data[].teamNo` |

前端处理位置：

- `src/views/fleet/board/index.vue`
- `src/views/fleet/board/components/OrderRowList.vue`
- `src/views/fleet/board/components/OrderDrawer.vue`
- `src/views/fleet/matrix/composables/useFleetMatrixData.js`
- `src/views/fleet/_shared/gantt/components/OrderGantt.vue`
- `src/views/fleet/_shared/gantt/components/OrderBar.vue`
- `src/views/fleet/_shared/gantt/components/VehicleGantt.vue`
- `src/views/fleet/_shared/gantt/components/UnassignedPool.vue`
- `src/views/fleet/matrix/components/DayListModal.vue`

### 2. 订单详情中文状态

`GET /admin/fleet/board/orders/{orderId}` 的每个 `data.activeAssignments[]` 新增：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `assignmentStatus` | `string` | 稳定状态码，供逻辑判断 |
| `assignmentStatusLabel` | `string` | 后端统一解析的中文状态标签，供页面展示 |

```json
{
  "assignmentStatus": "assigned",
  "assignmentStatusLabel": "已派车"
}
```

`OrderDrawer.vue` 中有效派车组右侧标签改为 `assignment.assignmentStatusLabel || '—'`，不要再以 `assignmentStatus` 作为可见兜底。

### 3. 派单候选常驻关系

接口：`POST /admin/fleet/assignments/candidates`

请求关键词：

| 字段 | 新口径 |
| --- | --- |
| `vehicleKeyword` | 车牌/车型包含匹配；常驻司机姓名包含匹配；常驻司机 11 位完整手机号精确匹配 |
| `driverKeyword` | 司机姓名包含匹配；司机 11 位完整手机号精确匹配；常驻车牌包含匹配 |

车辆候选 `data.vehicles.records[]`：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `primaryDriverId` | `string \| null` | 常驻司机 ID |
| `primaryDriverName` | `string \| null` | 常驻司机姓名 |
| `primaryDriverMaskedPhone` | `string \| null` | 常驻司机脱敏手机号 |

司机候选 `data.drivers.records[]` 继续返回：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `residentVehicleId` | `string \| null` | 常驻车辆 ID |
| `residentVehiclePlate` | `string \| null` | 常驻车牌 |

前端处理要求：

- `VehiclePickerList.vue`：有常驻司机时显示“常驻司机：姓名 脱敏手机号”，无常驻时显示“无常驻”；搜索提示改为“搜索车牌/车型/常驻司机姓名/完整手机号”。
- `DriverPickerList.vue`：保留现有“常驻 {residentVehiclePlate}”展示；搜索提示改为“搜索姓名/完整手机号/常驻车牌”。
- `useVehicleDriverPicker.js`：关键词变化后分别重置对应页码为 1，并将原值传给 `vehicleKeyword` / `driverKeyword`；不在前端对当前页二次过滤。
- 所有雪花 ID 保持字符串处理。

## 示例

```json
{
  "vehicles": {
    "records": [
      {
        "vehicleId": "2000000000000000101",
        "plate": "蒙A77777",
        "primaryDriverId": "2000000000000000201",
        "primaryDriverName": "张师傅",
        "primaryDriverMaskedPhone": "138****5678"
      }
    ]
  },
  "drivers": {
    "records": [
      {
        "driverId": "2000000000000000201",
        "name": "张师傅",
        "maskedPhone": "138****5678",
        "residentVehicleId": "2000000000000000101",
        "residentVehiclePlate": "蒙A77777"
      }
    ]
  }
}
```

## 验收清单

- [ ] 看板卡片、详情标题和矩阵各订单入口优先显示完整 `teamNo`，空值回退 `orderNo`。
- [ ] 矩阵已派占用条正文直接显示 `teamNo || orderNo || '—'`；不能只在悬浮提示中显示。窄占用条优先保留完整团号，其次才是人员构成和路线。
- [ ] 有效派车组状态只显示 `assignmentStatusLabel` 中文文案，不再出现 `assigned` 等英文状态码。
- [ ] 有常驻司机的车辆显示姓名和脱敏手机号；可按姓名或完整手机号筛到对应车辆。
- [ ] 有常驻车辆的司机显示常驻车牌；可按常驻车牌筛到对应司机。
- [ ] 车牌/车型搜索和司机姓名/完整手机号搜索保持有效，关键词变化后分页正确重置。
- [ ] 团号展示不改变详情、拖拽、派单、改派、取消等操作使用的稳定 ID。
- [ ] 前端单元测试覆盖已派占用条正文团号、团号回退、中文状态、双向常驻关系显示与筛选参数。

## 后端核查证据

- `BoardOrderServiceTest` 覆盖 `assigned -> 已派车`。
- `AssignmentCandidateServiceTest` 覆盖车辆按常驻司机姓名/完整手机号筛选、司机按常驻车牌筛选及双向关系回显。
- `DriverServiceTest` 覆盖指定常驻司机集合内的姓名/完整手机号查询，明文手机号不离开司机域。