wx/hl-api-changelog

派生 0

文件

T

Mimingguang 875a682ea9

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): #7925/#7937/#8023/#8030 前端接入「用房·汇总」建页交付,翻 verified(mmg@9a14ad86)

2026-09-20 17:39:04 +08:00

14 KiB

原始文件 Blame 文件历史

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	verified	mmg	9a14ad866b3ef6ac9acb0ca9ab9e9f0fe98f6559		2026-09-20	全团需求汇总 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 前端接入(mmg):「用房 · 汇总」建页随 hl-admin v2.1 交付——requirement-summary 经 getGroupRequirementSummary 接入「查看需求」页 RoomSummarySection:户数条(在团/需订房/已提交)+不一致只提示不扣减+Day N\|酒店\|房型\|所需间数扁平表;stayDate null 按 Day N、hotelName null 显「未知酒店」不隐藏行、roomCategoryName null 回落编码、全天合计直读 rooms[] 禁跨酒店累加、hotelId null 组间数不丢;整团确认/按户打回后自动重拉。定向 Vitest 17/17,checkpoint 全绿。	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

14 KiB

原始文件 Blame 文件历史

order-v3: 全团需求汇总车型座位合计补车型大类中文名

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

1. 全团需求汇总 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary`

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

四、契约约束与正确调用方式

五、数据库行为

六、边界行为

六.6、修改前后对比

字段级对比

行为级对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

链接

联系人

14 KiB 原始文件 Blame 文件历史 Unescape Escape

order-v3: 全团需求汇总车型座位合计补车型大类中文名

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

1. 全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

四、契约约束与正确调用方式

五、数据库行为

六、边界行为

六.6、修改前后对比

字段级对比

行为级对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

链接

联系人

14 KiB

原始文件 Blame 文件历史

1. 全团需求汇总 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary`