Mimingguang
734d06d7b5
changelog-filename-gate / validate (push) Failing after 1s
确认弹窗键名缺陷(01acf773)、用车汇总逐条列出(a73ef932)
166 行
8.4 KiB
Markdown
166 行
8.4 KiB
Markdown
---
|
||
schema: hl-changelog/v2
|
||
ticket: "frontend"
|
||
title: "团期详情「用车汇总」块，行程用车与接送机从按车型聚合改逐条列出，调用既有 /requirement/vehicle-households 接口"
|
||
consumer: admin
|
||
author: "wx(GIT)"
|
||
change_type: "前端优化"
|
||
backend_status: "not_required"
|
||
gateway_status: "not_required"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "a73ef932b4b230d70c7fab793da5c08c910d408b"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-09-29"
|
||
status_note: "前端 2026-09-29 已交付：两板块改逐条列表(团号/客户/车型/单车座位/台数/状态),复用 vehicle-households 经父级转发零新请求,按 kind 过滤不按状态/不用 countedInSummary,teamNo null 显—,statusName 原文直显,表尾合计=列表加总(用户拍板保留),统计摘要保留;spec 5 例全绿"
|
||
updated_at: "2026-09-29"
|
||
base: dev-v3
|
||
---
|
||
|
||
# 团期详情用车汇总改逐条列出
|
||
|
||
> **服务**: hl-order-service-v3（**后端无改动，复用既有接口**）
|
||
> **页面**: 管理后台 → 团期订单 → 进入团期（团期详情）→「查看需求」Tab →「用车 · 汇总」块
|
||
> **数据源接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households`（既有，VehicleHouseholdsSection 已在调）
|
||
> **日期**: 2026-09-29
|
||
> **影响范围**: 前端页面展示逻辑。行程用车与接送机块从按车型聚合的 N 行改为逐户逐行的完整列表。
|
||
|
||
---
|
||
|
||
## 一、需求
|
||
|
||
改变「用车 · 汇总」块的行程用车与接送机两个板块展示形态——从当前按车型聚合（显示「车型 / 合计座位 / 台数」）改为**逐条列出**（显示「团号 / 客户 / 车型 / 单车座位 / 台数」），让信息粒度与「用车 · 子订单用车需求记录」块对齐。
|
||
|
||
---
|
||
|
||
## 二、前提订正
|
||
|
||
当前「接送机」块**其实也是按车型汇总的**，而非逐条列表——只是恰好本次测试团的两户选了不同车型（suv / mpv），所以看起来像列表。后端 `requirement-summary` 接口的 `vehicleSeatSummary`（行程）与 `transferSummary.vehicleSeatSummary`（接送机）都用同一个聚合方法（hl-order-service-v3 `GroupBatchRequirementService.java` 第 343、346 行都调 `aggregateVehicleSeats`）。
|
||
|
||
wx 的原话是「行程用车也不需要汇总，list 列出来就行，和接送机需求一样就行」。既然接送机现状也是汇总，按「逐条列出」的本意，**行程用车与接送机两块都改成逐条列表**。
|
||
|
||
---
|
||
|
||
## 三、数据源
|
||
|
||
使用既有接口 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households`，契约不变：
|
||
|
||
- 响应字段见同目录 `22_8152_团期用车需求补车辆规格与接送机汇总-修改接口-管理后台.md` 与 `22_8195_团期查看需求页五处缺口-修改接口-管理后台.md`。
|
||
- query 参数 `kind` 可选，只收单个值 `TRAVEL` 或 `TRANSFER`；不传或传空时两类都返回。**不支持逗号多值**（`kind=TRAVEL,TRANSFER` 会被判为非法取值，返错误码 809000）。本需求建议不传 `kind`，一次拿两类。
|
||
|
||
**关键字段**：
|
||
- `households[n].teamNo` —— 团号（可为 null，显示「—」，**禁用 orderNo 顶替**）
|
||
- `households[n].customerName` —— 客户名
|
||
- `households[n].requirements[m].kind` —— 类型（`TRAVEL` 或 `TRANSFER`）
|
||
- `households[n].requirements[m].fleet[p]` —— 车型数组，其中：
|
||
- `vehicleTypeName` —— 车型名称（为空时退回 `vehicleType`）
|
||
- `seats` —— 单车座位数
|
||
- `count` —— 台数
|
||
|
||
---
|
||
|
||
## 四、数据处理规则
|
||
|
||
### ① 按 kind 过滤
|
||
|
||
行程用车：取所有 `kind='TRAVEL'` 的行，不按 `countedInSummary` 过滤。
|
||
|
||
接送机：取所有 `kind='TRANSFER'` 的行，不按 `countedInSummary` 过滤。
|
||
|
||
**禁用 `countedInSummary` 作为过滤条件**。后端 `countedInSummary` 的定义是「该户有活跃 TRAVEL 行」（hl-order-service-v3 `GroupBatchVehicleHouseholdService.java` 第 233 行），用它筛接送机会漏掉只报了接送机的户。聚合数已经按 kind 隔离，前端只需按 kind 对应过滤。
|
||
|
||
### ② 按状态
|
||
|
||
**不按状态过滤**。汇总的车侧口径不看状态（待审核的也计入），列表要与汇总对得上就不能自行二次筛选。
|
||
|
||
### ③ 逐行展开
|
||
|
||
对每个 `households[n].requirements[m].fleet` 数组，**每个元素出一行**。行组成：
|
||
|
||
```
|
||
[团号] | [客户名] | [车型] | [单车座位] | [台数] | [状态]（可选）
|
||
```
|
||
|
||
具体列如下：
|
||
|
||
| 列 | 来源字段 | 说明 |
|
||
|---|---|---|
|
||
| 团号 | `teamNo` | 为 null 显「—」；禁用 orderNo 顶替 |
|
||
| 客户 | `customerName` | — |
|
||
| 车型 | `vehicleTypeName` 或 `vehicleType` | 优先用 `vehicleTypeName`；空时退回 `vehicleType` |
|
||
| 单车座位 | `seats` | — |
|
||
| 台数 | `count` | — |
|
||
| 状态 | `statusName`（可选） | 仅供展示，不作过滤依据。直接用后端给的 `statusName`，不要按 `status` 自己翻译：同为 `PENDING_REVIEW`，行程用车返「待提交车务」、接送机返「待审核」 |
|
||
|
||
---
|
||
|
||
## 五、页面形态
|
||
|
||
**VehicleSummarySection.vue** 修改位置（现约第 14-33 行行程用车块 + 第 35-61 行接送机块）：
|
||
|
||
### 行程用车块
|
||
- 小标题保持「行程用车」。
|
||
- **替代当前汇总表**：用逐行列表替代按车型聚合的表。
|
||
- **表头**：`团号 | 客户 | 车型 | 单车座位 | 台数`。
|
||
- **合计行保留**（可选）：表尾显「合计 X 座」「合计 Y 辆」，取 `requirement-summary.vehicleSeatSummary` 或由前端加总。
|
||
- **空态**：列表为空时显「暂无行程用车需求」。
|
||
|
||
### 接送机块
|
||
- 小标题保持「接送机」。
|
||
- **分为两部分**：
|
||
1. **逐行列表**（同行程用车的结构），但 `kind='TRANSFER'` 过滤。
|
||
2. **既有统计摘要保留**（取 `requirement-summary.transferSummary`）：接机 N 户、送机 N 户、合计 N 人、服务日期。
|
||
- **空态**：接送机列表为空时显「暂无接送机需求」。
|
||
|
||
---
|
||
|
||
## 六、已实测对账
|
||
|
||
测试团期：`2100856430494973953`（王晓测试团期产品·第3期 10月8日出发团）。两户样本数据：
|
||
|
||
**行程用车（TRAVEL）**：
|
||
- 户 1（王有亿，teamNo=`26-7060`）：大巴系列（bus）19 座 ×1
|
||
- 户 2（王二麻子，teamNo=`26-2355`）：大巴系列（bus）19 座 ×1
|
||
- **列表加总**：bus 合计 38 座，2 辆
|
||
- **汇总返回**（`requirement-summary.vehicleSeatSummary`）：bus 38 座，2 辆
|
||
- **一致性**：✓ 一致
|
||
|
||
**接送机（TRANSFER）**：
|
||
- 户 1（王有亿）：SUV系列（suv）5 座 ×1
|
||
- 户 2（王二麻子）：商务车（mpv）7 座 ×1
|
||
- **列表加总**：suv 5/1，mpv 7/1
|
||
- **汇总返回**（`requirement-summary.transferSummary.vehicleSeatSummary`）：suv 5 座 1 辆，mpv 7 座 1 辆
|
||
- **一致性**：✓ 一致
|
||
|
||
列表逐条数据已与取数接口（`GET /v3/admin/order/group-batch/2100856430494973953/requirement/vehicle-households`）的返回原文核对。
|
||
|
||
**覆盖边界声明**：本次对账团两户都有 TRAVEL 行，所以「只报接送机、无 TRAVEL 行的户」分支未被实测覆盖；结论依据后端源码逻辑推出（`countedInSummary` 定义来自源码第 233 行）。
|
||
|
||
---
|
||
|
||
## 七、业务边界
|
||
|
||
- `vehicle-households` 单次最多返 500 户（超出截断并记后端日志）；超限时列表加总会小于汇总数。
|
||
- 户可能 `requirements` 为空数组（还未提交需求）——该户不出行。
|
||
- 某行 `fleet` 若为空数组，该行不出列表行（汇总加总同样不计它）。
|
||
- 列表为空时各块显示对应的「暂无」文案。
|
||
- 与「用车 · 子订单用车需求记录」块共用同一接口，建议前端在父组件缓存一份响应以避免重复请求（非硬需求）。
|
||
|
||
---
|
||
|
||
## 八、后端接口（无改动）
|
||
|
||
- 接口：`GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households`
|
||
- 路由、权限、响应字段、错误码均不变。
|
||
- 测试服 2026-09-29 实调可用（HTTP 200 / code=200）。
|
||
|
||
---
|
||
|
||
## 九、验收
|
||
|
||
1. 在测试团期 `2100856430494973953` 打开团期详情「查看需求」Tab。
|
||
2. 「用车 · 汇总」块的行程用车板显示 2 行（两户 bus 各一行），接送机板显示 2 行（一户 suv、一户 mpv）。
|
||
3. 逐条列表核对字段完整性：每行都有团号、客户名、车型、座位、台数。
|
||
4. 将列表按车型加总，与汇总摘要中的合计座位数、台数逐项核对，**完全相等**。
|
||
5. 接送机块保留既有的「接机 N 户、送机 N 户」等统计行。
|