From ec1d8b3c69b8beed3d4211b023cfce5e77620145 Mon Sep 17 00:00:00 2001
From: jw <jinwei@1814.love>
Date: Sun, 20 Sep 2026 12:14:27 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7937=20=E5=85=A8=E5=9B=A2?=
 =?UTF-8?q?=E9=9C=80=E6=B1=82=E6=B1=87=E6=80=BB=E8=BD=A6=E5=9E=8B=E5=BA=A7?=
 =?UTF-8?q?=E4=BD=8D=E5=90=88=E8=AE=A1=E8=A1=A5=E8=BD=A6=E5=9E=8B=E5=A4=A7?=
 =?UTF-8?q?=E7=B1=BB=E4=B8=AD=E6=96=87=E5=90=8D=20vehicleTypeName=EF=BC=88?=
 =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=8E=A5=E5=8F=A3=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...œ€æ±‚汇总补车型大类中文å��-修改接å�£-管ç�†å�Žå�°.md | 282 ++++++++++++++++++
 1 file changed, 282 insertions(+)
 create mode 100644 changelogs-v2/2026-09/20_7937_全团需求汇总补车型大类中文�-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/20_7937_全团需求汇总补车型大类中文�-修改接�-管���.md b/changelogs-v2/2026-09/20_7937_全团需求汇总补车型大类中文�-修改接�-管���.md
new file mode 100644
index 00000000..cd3aaa27
--- /dev/null
+++ b/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