docs(changelog): #7937 全团需求汇总车型座位合计补车型大类中文名 vehicleTypeName（修改接口）

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

changelogs-v2/2026-09/20_7937_全团需求汇总补车型大类中文名-修改接口-管理后台.md

@@ -0,0 +1,282 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7937"
+title: "全团需求汇总：车型座位合计新增车型大类中文名 vehicleTypeName"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 的 vehicleSeatSummary[] 新增一个出参 vehicleTypeName（车型大类中文名，如 SUV系列），取自车队「车型管理库」fleet_vehicle_type.type_name。既有的 vehicleType 仍是编码（suv/mpv/bus/sedan）、原样返回，没删没改；本次是纯增量，其余字段与入参、路径、错误码均不变。车队不可用或该编码在车型管理库里查不到时 vehicleTypeName 为 null，汇总接口本身照常 200。配套在 hl-fleet-service 新增内部只读端点（服务间调用，前端不可见）。后端已合并 dev-v3（079732ca2）并部署 TEST，网关实测通过（工单 #7937 AC-4/AC-5）。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 全团需求汇总车型座位合计补车型大类中文名
+
+> **存放目录**: `changelogs-v2/{YYYY-MM}/`（管理后台，二期 order-v3）
+>
+> **服务**: hl-order-service-v3 (端口 8086)、hl-fleet-service (端口 8087)
+> **PR**: [#7996](https://git.1814.love:8443/wx/HL/pulls/7996)
+> **Issue**: [#7937](https://git.1814.love:8443/wx/HL/issues/7937)
+> **日期**: 2026-09-20
+> **影响范围**: 团期详情「查看需求」页的全团需求汇总 —— 车型座位合计那一块
+
+---
+
+## ⚠️ 关键变化
+
+1. **新增一个出参** `vehicleSeatSummary[].vehicleTypeName`（纯增量，不接入也不影响现有功能）。
+2. **`vehicleType` 一直是编码**（`suv` / `mpv` / `bus` / `sedan`），本次只是补了它的中文名字段，**编码本身原样返回、语义不变**。此前该字段的接口文档描述误写成「车型名称（如 大巴 / 商务车）」，本次一并改正为「车型大类编码」。
+3. **中文名的来源是车队「车型管理库」**（后台菜单：资源管理 → 车型管理库），不是数据字典。所以前端看到的名字与车队后台里维护的一字不差。
+4. **既有字段全部保留**；入参、路径、错误码、判权都没变。
+
+---
+
+## 一、背景
+
+「查看需求」页的车型座位合计此前只有编码：页面上显示 `suv`，运营看不懂，而按规定前端不能自建编码到中文的映射（#6921）。本次由后端补中文名。
+
+名字取自车型管理库而不是数据字典，是因为**用车需求提交时的座位数校验走的就是车型管理库**——同源才能保证「页面显示的车型名」和「车队后台维护的车型名」始终一致；数据字典里的那套 `vehicle_type` 值与车型管理库对不上（字典是大写 `SUV`/`MPV`，车型管理库是小写开放集 `suv2`/`mpv`），用它会两头漂移。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 全团需求汇总 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement-summary` | 修改 | `vehicleSeatSummary[]` 新增出参 `vehicleTypeName` |
+
+---
+
+## 三、接口详情
+
+### 1. 全团需求汇总 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary`
+
+**VO**: `Result<GroupRequirementSummaryRespVO>`
+
+#### 使用场景
+
+团期详情「查看需求」页：展示全团逐日要订几间房、车型座位合计、各户的特殊需求标签。运营据此向酒店 / 车队报数，车型那一栏现在可以直接显示中文名。
+
+#### 入参
+
+本次入参**不变**。
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期 ID | 团期不存在返回 589500 |
+
+#### 出参
+
+仅列与本次相关的字段，其余字段（`activeOrderCount`、`hotelRequirementCount`、`hotelNeededOrderCount`、`hotelSubmittedOrderCount`、`dailyRoomBreakdown`、`orderSpecialTags` 等）本次**一个没动**，见 #7925 的 changelog。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| vehicleSeatSummary | List | 车型座位合计（本次新增子字段，合计口径不变） |
+| vehicleSeatSummary[].vehicleType | String | 车型大类**编码**：`suv` / `mpv` / `bus` / `sedan`；明细里缺车型时为 `未知`（不变，仅文档描述改正） |
+| vehicleSeatSummary[].vehicleTypeName | String | **新增**。车型大类中文名，取自车型管理库，如 `SUV系列`；车型管理库里查不到该编码、或车队服务不可用时为 `null` |
+| vehicleSeatSummary[].totalSeats | Integer | 合计座位数（seats × count 之和，不变） |
+| vehicleSeatSummary[].totalCount | Integer | 合计车辆台数（不变） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2099927193172815873/requirement-summary
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+（测试服真实响应，2026-09-20，1 台 5 座 SUV）
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "activeOrderCount": 5,
+    "vehicleRequirementCount": 1,
+    "vehicleSeatSummary": [
+      { "vehicleType": "suv", "vehicleTypeName": "SUV系列", "totalSeats": 5, "totalCount": 1 }
+    ],
+    "orderSpecialTags": []
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+全团没有用车需求时，`vehicleSeatSummary` 为空数组，且**不会去调车队**：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "activeOrderCount": 1,
+    "vehicleRequirementCount": 0,
+    "vehicleSeatSummary": [],
+    "orderSpecialTags": []
+  },
+  "success": true
+}
+```
+
+车队服务不可用、或某编码在车型管理库里查不到时，**只有 `vehicleTypeName` 为 `null`**，编码与座位数照常返回，汇总接口不报错：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "vehicleSeatSummary": [
+      { "vehicleType": "suv", "vehicleTypeName": null, "totalSeats": 5, "totalCount": 1 }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{ "code": 589507, "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 589507 | 当前角色没有 `group-batch:view`（本次不变） |
+| 589500 | 团期不存在（本次不变） |
+| 401 | 未登录（网关拦截） |
+
+本次无新增错误码。车队取名失败**不产生错误码**，降级为 `vehicleTypeName: null`。
+
+#### 业务边界
+
+- **编码只有四类**：用车需求提交时后端已把车型归一成 `suv` / `mpv` / `bus` / `sedan` 再落库，所以汇总里不会出现别的编码。
+- **名字按归一编码去车型管理库里匹配**，不是按车型管理库的原始 key 精确相等。例：测试服 SUV 大类的原始 key 是 `suv2`、名字「SUV系列」，需求里存的是 `suv`，归一后命中，返回「SUV系列」。
+- **已删除的车型大类不参与**：车型管理库里被删掉的大类不会再被取名（测试服上 `suv`+「SUV越野专线」那条已于 2026-05-21 删除，不会返回它的名字）。
+- **同一类下有多条大类时取排最前的一条**（按车型管理库的排序值升序）。
+- 明细里缺车型的那部分会归到编码 `未知` 下，车型管理库没有这个编码，故其 `vehicleTypeName` 为 `null`。
+- 一次汇总只向车队取一次名称，不按车型逐个调用。
+
+---
+
+## 四、契约约束与正确调用方式
+
+| 场景 | 做法 |
+|------|------|
+| ✅ 车型显示中文 | 优先 `vehicleTypeName`，为 null 时回落显示 `vehicleType` 编码，别显示空白 |
+| ✅ 按车型做筛选 / 分组 / 上报 | 一律用 `vehicleType` 编码，中文名随车队后台改名而变，不能当 key |
+| ❌ 前端自己维护车型编码→中文映射 | 会与车队后台漂移（#6921 已明确禁止），直接用 `vehicleTypeName` |
+| ❌ 把 `vehicleTypeName` 当作必有字段 | 它可能为 `null`（车队不可用 / 编码查不到 / 「未知」），渲染前判空 |
+| ❌ 拿字典 `vehicle_type` 的中文名去对 | 那套值与车型管理库对不上，名字会与车队后台不一致 |
+
+---
+
+## 五、数据库行为
+
+**零变更**。本接口是只读汇总，本次改动不新增/修改任何表与列，也不写任何数据。
+
+- 名称数据来自车队既有表 `fleet_vehicle_type` 的既有列 `type_name`，**只读**。
+- 车型编码来自订单既有表 `order_vehicle_requirement.fleet` 的 JSON，**只读**。
+- 无 Flyway 迁移、无索引变更、无数据订正。
+
+---
+
+## 六、边界行为
+
+- 全团无用车需求 → `vehicleSeatSummary` 为空数组，且不调车队取名。
+- 车队服务不可用（熔断 / 超时 / 返回失败）→ 该次汇总所有 `vehicleTypeName` 为 `null`，编码与座位数照常返回，接口 200。
+- 编码在车型管理库里查不到（含「未知」）→ 该项 `vehicleTypeName` 为 `null`，同项其余字段不受影响。
+- 车队后台给某大类改名 → 下一次调用即返回新名字（不缓存）。
+- 车型管理库里该大类被删除 → 其名字不再返回，该编码的 `vehicleTypeName` 变为 `null`。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `vehicleSeatSummary[].vehicleTypeName` | 无 | 新增，String，可为 null |
+| `vehicleSeatSummary[].vehicleType` | 编码（文档描述误写为「车型名称」） | 编码不变，**仅文档描述改正**为「车型大类编码」 |
+| 其余既有字段 | — | 不变（无删除、无改名、无类型变化） |
+| 入参 / 路径 / 错误码 / 判权 | — | 不变 |
+
+### 行为级对比
+
+| 场景 | 改前 | 改后 |
+|------|------|------|
+| 页面要显示车型中文名 | 后端只给编码，前端无合规途径拿到中文 | 后端直接给 `vehicleTypeName` |
+| 车队服务不可用 | 与本字段无关 | 名称为 null，汇总本身不受影响、照常 200 |
+| 车队后台给车型改名 | — | 汇总返回的中文名随之变化（编码不变） |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。纯增量，既有字段与数值一个没变。
+- **前端是否必须同步上线**: 否。不接入不影响现有页面；接入后车型那一栏才显示中文。
+- **回滚**: 回滚 PR #7996 即可，无数据变更（只读接口）。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 本接口 `vehicleSeatSummary[]` 新增的这一个出参。
+- **零影响**: 房间合计与房型中文名（#7925）、各户特殊需求标签、整体确认与预检、用车需求提交与座位数校验、车队派车看板与矩阵、数据库结构（只读接口，无表变更）。
+- **其他仍返回车型编码的接口不在本次范围**，它们没有 `vehicleTypeName`。
+
+---
+
+## 八、测试环境已验证
+
+被测版本：hl-order-service-v3 与 hl-fleet-service 均为 dev-v3 `079732ca2`（2026-09-20 部署：fleet 11:58:59、order-v3 12:09:59，各双实例 running）。
+
+```
+团期 2099927193172815873
+  vehicleSeatSummary[0] = {vehicleType:"suv", vehicleTypeName:"SUV系列",
+                           totalSeats:5, totalCount:1}                          ✓
+团期 2099919607530762241
+  同样返回 vehicleTypeName="SUV系列"                                            ✓
+与来源一致性（查测试库 fleet_vehicle_type）
+  未删大类 4 条：suv2→SUV系列 / mpv→商务车 / sedan→轿车系列 / bus→大巴系列
+  需求里的 suv 经归一命中 suv2，故中文名「SUV系列」，与车型管理库一致            ✓
+  已软删的 suv→「SUV越野专线」（2026-05-21 删）未参与取名                        ✓
+判权（自签 token 按角色打真实网关，未用超管取证）
+  团期管理员 GROUP_BATCH_MANAGER (cw_test_7442)  → 200，vehicleTypeName=SUV系列  ✓
+  房务管理员 ROOM_MANAGER (shuxin，无 group-batch:view) → 589507                 ✓
+```
+
+本地（在 dev-v3 `20465f21e` 之上实跑）：`VehicleTypeServiceTest` 20/20（含归一匹配 `suv2`→`suv`、同类取排序最前、无法归一与空名跳过、空库四例）、`FleetVehicleTypeNameLoaderTest` 4/4（成功 / 返回失败 / 数据为空 / 抛异常均降级）、`GroupBatchRequirementSummaryTest` 16/16（含命中填名、查不到留 null、车队不可用全 null、无用车需求不调车队）、`GroupBatchRequirementControllerTest` 14/14，order-v3 受影响回归合计 420/420。
+
+> 说明：车队不可用的降级路径以单测覆盖（工单 AC-2 原文即如此要求），未在测试服注入实测——注入需压低该 Feign 客户端超时，而同一客户端还承担用车需求提交时的座位数校验，会波及并发使用测试服的其他同学。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7937](https://git.1814.love:8443/wx/HL/issues/7937)
+- 关联 PR: [wx/HL#7996](https://git.1814.love:8443/wx/HL/pulls/7996)
+- 同一接口的房间合计口径与房型中文名（#7925）见同目录 `20_7925_全团需求汇总房间合计对齐预检判定与补房型中文名-修改接口-管理后台.md`
+- 前端不得自建编码→中文映射的约定见 [wx/HL#6921](https://git.1814.love:8443/wx/HL/issues/6921)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7937](https://git.1814.love:8443/wx/HL/issues/7937)
+- **PR**: [#7996](https://git.1814.love:8443/wx/HL/pulls/7996)
+- **Merge commit**: [079732ca2](https://git.1814.love:8443/wx/HL/commit/079732ca2)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg