diff --git a/changelogs-v2/2026-07/89_5178_用车手动加急与派车看板状态颜色-新增接口-前端待处理-管理后台.md b/changelogs-v2/2026-07/89_5178_用车手动加急与派车看板状态颜色-新增接口-前端待处理-管理后台.md new file mode 100644 index 0000000..1619206 --- /dev/null +++ b/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` +- 联调/验收环境: +- 小程序:无需处理 + +> **服务**: 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`;前端按“前端处理清单”接入即可。