docs(frontend): hand off vehicle urgency contract (#5178)

changelogs-v2/2026-07/89_5178_用车手动加急与派车看板状态颜色-新增接口-前端待处理-管理后台.md

@@ -0,0 +1,148 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5178"
+title: "用车手动加急与派车看板状态颜色"
+consumer: "admin"
+backend: "verified"
+gateway: "pending"
+frontend: "pending"
+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#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,
+  "msg": "success"
+}
+```
+
+需要明确处理的业务错误：
+
+| code | 含义 | 建议提示 |
+| --- | --- | --- |
+| `582084` | 当前账号不是本单定制师且不是超级管理员 | 仅本单定制师可操作用车加急 |
+| `582087` | 需求已完成、已失效或状态已变化 | 当前用车需求状态已变化，请刷新后重试 |
+
+## 订单详情新增字段
+
+订单详情 `data.itinerary.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 有效状态、排序、列表和详情映射覆盖手动加急优先规则。
+- fleet `spotless:check`、`verify` 与测试环境网关验证完成后补充最终证据。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`；前端按“前端处理清单”接入即可。