From c76d5f72c7fc9e7e4b6eb0e9b08b1170e6f6b82c Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 24 Jul 2026 10:07:10 +0800 Subject: [PATCH] docs(fleet): hand off dashboard order summary fix (#5199) --- ...首页订单去重与字段补全-修改接口-管理后台.md | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 changelogs-v2/2026-07/24_5199_车务首页订单去重与字段补全-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/24_5199_车务首页订单去重与字段补全-修改接口-管理后台.md b/changelogs-v2/2026-07/24_5199_车务首页订单去重与字段补全-修改接口-管理后台.md new file mode 100644 index 0000000..9cbd70e --- /dev/null +++ b/changelogs-v2/2026-07/24_5199_车务首页订单去重与字段补全-修改接口-管理后台.md @@ -0,0 +1,108 @@ +--- +schema: "hl-changelog/v1" +ticket: "5199" +title: "车务首页订单去重与字段补全" +consumer: "admin" +backend: "verified" +gateway: "verified" +frontend: "pending" +base: "dev-v3" +generated: "2026-07-24T09:46:00+08:00" +--- + +# 【修改接口·前端待处理·管理后台】车务首页订单去重与字段补全 + +## 目标前端 + +- 端类型：管理后台（Web） +- 目标仓库：`mmg/hl-ui` +- 目标分支：`v2.1` +- 联调/验收环境： +- 小程序：无需处理 + +> **服务**: hl-fleet-service、hl-user-service +> +> **工单**: [wx/HL#5199](https://git.1814.love:8443/wx/HL/issues/5199) +> +> **影响范围**: 车务角色首页的待安排车辆统计、即将用车订单表格和操作列 + +## 关键变化 + +`GET /admin/profile/dashboard?period=today` 在当前角色为 `VEHICLE_MANAGER` 时，`data.upcomingTrips` 的口径调整为： + +- 只返回近 7 天仍存在未完成派车槽位的订单，未完成态为 `unassigned/unassigned_urgent/holding/holding_urgent`； +- 同一订单的多个车型、车辆或派车槽位按 `orderId` 合并为一行； +- 返回符合条件的完整订单集合，不再固定截断为 5 条； +- 全部派车槽位均已进入 `assigned` 的订单不再出现在待处理列表。 + +派车看板 `/admin/fleet/board/orders` 仍保持派车槽位维度和原分页规则，本次不修改。 + +## 响应字段 + +`data.upcomingTrips[]` 完整结构： + +```json +{ + "orderId": "70123456789", + "assignmentId": "80123456789", + "orderNo": "HL202607010001", + "teamNo": "26-7218", + "productName": "呼伦贝尔 6 日", + "customerName": "张先生", + "contactName": "张先生", + "plannerName": "苏日娜", + "consultantName": "苏日娜", + "consultantDisplayName": "苏日娜", + "departureDate": "2026-07-10", + "endDate": "2026-07-15", + "headcount": 4, + "status": "unassigned_urgent", + "statusLabel": "待派车", + "urgentBadge": "T-1", + "canAssign": true, + "canRejectRequirement": true +} +``` + +本次补齐的字段： + +| 字段 | 类型 | 页面用途 | +| --- | --- | --- | +| `teamNo` | `String/null` | 团号列 | +| `contactName` | `String/null` | 联系人列，当前与 `customerName` 同值 | +| `plannerName` | `String/null` | 定制师兼容字段 | +| `consultantName` | `String/null` | 定制师兼容字段 | +| `consultantDisplayName` | `String/null` | 定制师优先展示字段 | +| `canAssign` | `Boolean` | 是否显示派车/调整入口 | +| `canRejectRequirement` | `Boolean` | 是否显示驳回需求入口 | + +`orderId` 和 `assignmentId` 继续按字符串处理，不得转为 JavaScript `Number`。同订单存在多个未完成派车槽位时，`assignmentId/status/statusLabel/urgentBadge/操作权限` 来自后端排序最靠前的代表槽位。 + +## 前端处理清单 + +- [ ] 表格行以 `orderId` 为订单级唯一键，不按 `assignmentId` 重复渲染。 +- [ ] 不在前端截取前 5 条，也不再自行做派车槽位去重。 +- [ ] 团号列读取 `teamNo`。 +- [ ] 定制师列优先读取 `consultantDisplayName`，为空时可回退 `consultantName/plannerName`。 +- [ ] 操作列按 `canAssign/canRejectRequirement` 显示已有操作入口，不根据中文状态文案推断。 +- [ ] 覆盖同订单多车型、多车、超过 5 个未完成订单、部分槽位已派和全部槽位已派场景。 + +## 不影响范围 + +- 不修改 `pendingArrangeVehicle` 字段名。 +- 不修改派车看板、矩阵派单、车辆列表或司机列表的分页和展示维度。 +- 不新增前端路由、权限码或请求参数。 + +## 后端验证 + +- 后端 PR：[wx/HL#5201](https://git.1814.love:8443/wx/HL/pulls/5201)。 +- `FleetDashboardSummaryServiceTest` 覆盖 8 条派车槽位聚合为 6 个未完成订单、重复订单去重和 `assigned` 过滤。 +- `LogisticsDashboardServiceTest` 覆盖团号、联系人、定制师与操作权限字段透传及 Feign 降级空态。 +- `hl-fleet-service` 测试环境滚动部署任务 `0944b306` 成功，8087/8187 双实例健康。 +- `hl-user-service` 测试环境滚动部署任务 `e306a054` 成功，8081/8181 双实例健康。 +- 经网关请求 `GET /admin/profile/dashboard?period=today` 返回 HTTP 200、业务码 200；`upcomingTrips` + 与相同日期和状态条件下的派单看板订单集合一致，共 4 个唯一订单，重复订单数 0，无已完成订单混入。 +- `teamNo/contactName/plannerName/consultantName/consultantDisplayName/canAssign/canRejectRequirement` + 在 4 条记录中均存在且均有有效值；user-service 与 gateway 近期日志未发现本次调用异常。 + +> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。