---
schema: "hl-changelog/v1"
ticket: "5178"
title: "用车手动加急与派车看板状态颜色"
consumer: "admin"
backend: "verified"
gateway: "verified"
frontend: "implemented"
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@d07506cd3aa8a23cb2aa90f891eb853e1b7dd13f"
updated_at: "2026-07-25T03:18:55.871Z"
base: "dev-v3"
generated: "2026-07-23T10:00:00+08:00"
---

# 【新增接口·前端待处理·管理后台】用车手动加急与派车看板状态颜色

## 目标前端

- 端类型：管理后台（Web）
- 目标仓库：`mmg/hl-ui`
- 目标分支：`v2.1`
- 联调/验收环境：<http://192.168.100.160:9527>
- 小程序：无需处理

> **服务**: hl-order-service-v3、hl-fleet-service
>
> **后端 PR**: [wx/HL#5181](https://git.1814.love:8443/wx/HL/pulls/5181)
>
> **工单**: [wx/HL#5178](https://git.1814.love:8443/wx/HL/issues/5178)
>
> **影响范围**: 订单详情“行程安排”用车卡片、车务派车看板列表及派单详情

## 业务口径

- 用车需求的“加急/取消加急”与房务需求保持一致：只改变优先级和页面提示，不修改需求状态、派单状态、司机车辆占用、保险或费用。
- 手动加急优先于临近出团、等待回复等自动紧急规则；取消后由后端恢复现有自动紧急度。
- 前端不得根据日期自行推断是否加急，也不得乐观修改本地状态；操作成功后重新拉取订单详情和派车看板。
- 已完成或已失效需求不能加急。按钮按后端允许状态 `PENDING`、`PROCESSING` 显示。

## 变更接口

| 方法 | 路径 | 权限 | 说明 |
| --- | --- | --- | --- |
| POST | `/v3/admin/order/vehicle-requirement/{requirementId}/urgent` | 本单定制师或超级管理员 | 手动加急；重复调用幂等 |
| POST | `/v3/admin/order/vehicle-requirement/{requirementId}/urgent/cancel` | 本单定制师或超级管理员 | 取消手动加急；重复调用幂等 |

请求无 Body，成功统一返回：

```json
{
  "code": 200,
  "data": null,
  "message": "成功",
  "success": true
}
```

需要明确处理的业务错误：

| code | 含义 | 建议提示 |
| --- | --- | --- |
| `582084` | 当前账号不是本单定制师且不是超级管理员 | 仅本单定制师可操作用车加急 |
| `582087` | 需求已完成、已失效或状态已变化 | 当前用车需求状态已变化，请刷新后重试 |

## 订单行程接口新增字段

`GET /v3/admin/order/{id}/itinerary` 的 `data.vehicleGroup.requirement` 新增：

```json
{
  "requirementId": "2046400000000000001",
  "status": "PENDING",
  "manualUrgent": true
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `manualUrgent` | `Boolean` | `true` 显示“取消加急”，`false` 显示“加急” |

订单详情“行程安排 → 用车安排”卡片应复用房务卡片的交互：

- 当前有效需求存在且状态为 `PENDING/PROCESSING` 时，在“联系车务”旁显示“加急”或“取消加急”。
- 点击后调用对应接口；成功后重拉订单详情，并让派车看板列表失效/刷新。
- 提交中禁用按钮，防止连续点击；接口错误显示后端业务文案。

## 派车看板列表契约

`GET /admin/fleet/board/orders` 每条 `data.records[]` 新增/统一返回：

```json
{
  "assignmentStatus": "unassigned_urgent",
  "assignmentStatusLabel": "待派车",
  "manualUrgent": true,
  "urgentBadge": "手动加急"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `assignmentStatus` | `String` | 后端计算后的权威状态码 |
| `assignmentStatusLabel` | `String` | 后端统一中文状态文案，页面直接展示 |
| `manualUrgent` | `Boolean` | 是否由定制师手动加急 |
| `urgentBadge` | `String/null` | 手动加急固定为“手动加急”；自动加急返回既有 T-N 文案 |

同一状态内，后端已把手动加急订单排在自动加急和普通订单之前，前端不需要再次排序。

## 派单详情新增字段

`GET /admin/fleet/board/orders/{orderId}` 新增：

- `data.manualUrgent`
- `data.currentAssignment.manualUrgent`
- `data.activeAssignments[].manualUrgent`

当前派单的 `assignmentStatus/assignmentStatusLabel/urgentBadge` 同样是后端计算后的有效状态，详情页不得自行按日期覆盖。

## 页面颜色映射

派车看板卡片参照房务卡片形成清晰的状态色，优先使用现有设计 Token；不要只给状态标签上色。

| 判定顺序 | 卡片语义 | 推荐底色 / 边框 | 标签 |
| --- | --- | --- | --- |
| `manualUrgent=true` | 定制师手动加急 | 淡红 `#FFF1F0` / 红 `#FF4D4F` | `urgentBadge` |
| `assignmentStatus=unassigned_urgent/holding_urgent` | 系统自动加急 | 淡橙 `#FFF7E6` / 橙 `#FA8C16` | `urgentBadge` |
| `assignmentStatus=unassigned` | 待派车 | 淡黄 `#FFFBE6` / 黄 `#FAAD14` | `assignmentStatusLabel` |
| `assignmentStatus=holding` | 待司机/车务确认 | 淡蓝 `#E6F4FF` / 蓝 `#1677FF` | `assignmentStatusLabel` |
| `assignmentStatus=assigned` | 已确认执行 | 淡绿 `#F6FFED` / 绿 `#52C41A` | `assignmentStatusLabel` |
| 完成、取消等终态 | 已结束 | 灰 `#F5F5F5` / 灰 `#BFBFBF` | `assignmentStatusLabel` |

样式优先级必须是 `manualUrgent` > 自动紧急状态 > 普通状态。卡片左侧强调边、背景和状态标签应同步变化，效果与房务“已回配/待处理”卡片一致。

## 前端处理清单

- [ ] `VehicleArrangeCard.vue` 在“联系车务”旁增加“加急/取消加急”，交互和按钮状态复用 `RoomArrangeCard.vue`。
- [ ] `ArrangementTab.vue` 和订单详情父组件透传 `urgent/cancel-urgent` 事件，新增用车加急 API 方法。
- [ ] 操作成功后重新拉取订单详情和派车看板，不在前端直接翻转 `manualUrgent`。
- [ ] 派车看板卡片按上表给整卡着色，优先读取 `manualUrgent`，状态文案读取 `assignmentStatusLabel`。
- [ ] 手动加急与自动加急用不同颜色和标签，不显示英文状态码。
- [ ] 派单详情读取顶层及当前/有效派单的 `manualUrgent`，不根据出团日期反推。
- [ ] 雪花 ID 继续按字符串处理。

## 验证证据

- 用车加急/取消加急的权限、状态门控和幂等覆盖单元测试。
- order-v3 订单详情与 order-v3 → fleet 共享契约均覆盖 `manualUrgent`。
- fleet 有效状态、排序、列表和详情映射覆盖手动加急优先规则。
- order-v3 与 fleet 全量 `verify` 通过，fleet 同时通过 Spotless 门禁。
- 测试环境滚动部署成功：order-v3 任务 `126a59e4`，8086/8186 双实例健康；fleet 任务 `a21c7f2e`，8087/8187 双实例健康。
- 以 `wx` 定制师经网关加急，行程接口实际返回 `manualUrgent=true`；以 `admin` 车务读取看板，实际返回 `unassigned_urgent`、`待派车`、`手动加急`，派单详情顶层也返回 `manualUrgent=true`。
- 验收结束已由 `wx` 取消加急并复查，看板恢复 `manualUrgent=false`、`unassigned`、`urgentBadge=null`，未遗留测试状态。

> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`；前端按“前端处理清单”接入即可。