14 KiB
schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
| schema | ticket | title | consumer | author | change_type | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 7937 | 全团需求汇总：车型座位合计新增车型大类中文名 vehicleTypeName | admin | jw(GIT) | 修改接口 | deployed | verified | not_required | mmg | 全团需求汇总 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）。前端实证（hl-ui v2.1，2026-09-20）：vehicleSeatSummary 全仓 grep 0 命中，前端尚未消费该汇总端点；vehicleTypeName 同名命中全在 fleet 司机列表/车辆选择器/趣味项调整等别域既有 API 字段，与本端点无关。纯增量出参对现有页面零影响，将来「查看需求」页接入车型中文名属新功能排期，非本件义务，翻 not_required。 | 2026-09-20 | dev-v3 |
order-v3: 全团需求汇总车型座位合计补车型大类中文名
存放目录:
changelogs-v2/{YYYY-MM}/（管理后台，二期 order-v3）服务: hl-order-service-v3 (端口 8086)、hl-fleet-service (端口 8087) PR: #7996 Issue: #7937 日期: 2026-09-20 影响范围: 团期详情「查看需求」页的全团需求汇总 —— 车型座位合计那一块
⚠️ 关键变化
- 新增一个出参
vehicleSeatSummary[].vehicleTypeName（纯增量，不接入也不影响现有功能）。 vehicleType一直是编码（suv/mpv/bus/sedan），本次只是补了它的中文名字段，编码本身原样返回、语义不变。此前该字段的接口文档描述误写成「车型名称（如 大巴 / 商务车）」，本次一并改正为「车型大类编码」。- 中文名的来源是车队「车型管理库」（后台菜单：资源管理 → 车型管理库），不是数据字典。所以前端看到的名字与车队后台里维护的一字不差。
- 既有字段全部保留；入参、路径、错误码、判权都没变。
一、背景
「查看需求」页的车型座位合计此前只有编码：页面上显示 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 | 合计车辆台数（不变） |
请求示例
GET /v3/admin/order/group-batch/2099927193172815873/requirement-summary
Authorization: Bearer <token>
响应示例
（测试服真实响应，2026-09-20，1 台 5 座 SUV）
{
"code": 200,
"message": "成功",
"data": {
"activeOrderCount": 5,
"vehicleRequirementCount": 1,
"vehicleSeatSummary": [
{ "vehicleType": "suv", "vehicleTypeName": "SUV系列", "totalSeats": 5, "totalCount": 1 }
],
"orderSpecialTags": []
},
"success": true
}
空数据 / 降级响应
全团没有用车需求时，vehicleSeatSummary 为空数组，且不会去调车队：
{
"code": 200,
"message": "成功",
"data": {
"activeOrderCount": 1,
"vehicleRequirementCount": 0,
"vehicleSeatSummary": [],
"orderSpecialTags": []
},
"success": true
}
车队服务不可用、或某编码在车型管理库里查不到时，只有 vehicleTypeName 为 null，编码与座位数照常返回，汇总接口不报错：
{
"code": 200,
"message": "成功",
"data": {
"vehicleSeatSummary": [
{ "vehicleType": "suv", "vehicleTypeName": null, "totalSeats": 5, "totalCount": 1 }
]
},
"success": true
}
错误响应
{ "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
- 关联 PR: wx/HL#7996
- 同一接口的房间合计口径与房型中文名（#7925）见同目录
20_7925_全团需求汇总房间合计对齐预检判定与补房型中文名-修改接口-管理后台.md - 前端不得自建编码→中文映射的约定见 wx/HL#6921