wx/hl-api-changelog

派生 0

文件

T

API Changelog Bot和Claude Opus 5 b3de329869

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

详情

docs(changelog): 8548 出参表标明待审户数的计数单位是户不是需求行

同一户同时报行程用车与接送机用车只计 1 户。字段名 requirementReopenPendingHouseholds 与本单主题（两类用车需求并存）放在一起时，前端按需求行数理解会得到偏大的数。四个接口块各补一处，保持自包含。

Refs #8548

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

2026-09-30 14:27:54 +08:00

28 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	8548	团期需求重开待审提示接入 4 个只读端点，并修复整团免车团确认时接送机需求放行不到的问题	admin	wx(GIT)	修改接口	deployed	verified	pending					PR #8586 合并 dev-v3（ddea7e710c）；测试网关部署确认：hl-order-service-v3 @ ff6863754、hl-fleet-service @ 99fb369ba（deploy-status.sh 实测，两者均以 ddea7e710c 为祖先）。4 个只读端点中 3 个（团期详情 A2、房务看板详情 H2、fleet 配车总览）已用同一真实团期（groupBatchId=2104839654727618562，团号 T26-3963）实测捕获非空取值，三端一致；第 4 个（房务看板列表 H1）因该团未被房务认领、不出现在列表口，改用另一真实团期（groupBatchId=2104838272570245121）捕获到已确认团的双 null 基线，未能在本轮独立捕获 H1 的非空实例——这是列表口与详情口可见集合不同导致的结构性限制，不是契约缺口，H1 的字段契约与 H2/A2/总览完全同源同算法（同一个 GroupBatchRequirementReopenHintService）。#8548 的确认端点行为修复（整团免车放行接送机）本身是写操作，为避免误改测试服现存业务数据未做原子调用，已按源码逐行核实：GroupBatchRequirementService.java 505-593 行（doConfirm 内核 javadoc 与分支代码）、1161-1296 行（release 集合装配与 waivedVehicleSnapshot）。	2026-09-30	dev-v3

hl-order-service-v3 / hl-fleet-service：团期需求重开待审提示接入 4 个只读端点，并修复整团免车团确认时接送机需求放行不到的问题

存放目录: changelogs-v2/2026-09/ 服务: hl-order-service-v3（主，#8549 新提示的唯一产出口 + #8548 行为修复）、hl-fleet-service（透传消费方，无独立业务逻辑改动） PR: #8586 Issue: #8548、#8549（一个 PR 同时处理两张关联工单）日期: 2026-09-30 影响范围: 4 个只读端点响应新增 2 字段（团期详情 A2、房务看板列表 H1、房务看板详情 H2、fleet 团期配车总览）；1 个写端点（团期整体确认需求）行为修复，响应结构不变

⚠️ 关键变化

新增 2 个响应字段：requirementReopenPendingHouseholds（Integer）、requirementReopenResourceType（String），出现在 4 个只读端点：GET /v3/admin/order/group-batch/{groupBatchId}、GET /v3/admin/house/group-batches、GET /v3/admin/house/group-batches/{groupBatchId}、GET /admin/fleet/group-dispatch/batches/{groupBatchId}/overview。四处取值同源同算法（GroupBatchRequirementReopenHintService，唯一产出口），不存在四套口径分叉的风险。
🔴 null 不代表 0，不要折算成 0 渲染「0 户需求待审核」。字段只在同时满足 3 个条件时才非空：① 团级 requirementConfirmed=false；② 能查到「定制师改需求触发的自动重开」留痕（区别于管理员手动打回，后者无此留痕）；③ 重开后该团确实还有在团户处于待审核状态。三者任一不满足，两个新字段都是 null，前端应继续渲染原有的「待管理员重新确认」文案。
两个新字段不是「要么都有要么都无」的一对：requirementReopenPendingHouseholds 非空时，requirementReopenResourceType 仍可能单独为 null（重开留痕的 extra JSON 解析失败/缺键时的降级），此时只渲染「N 户需求待审核」，不带 HOTEL/VEHICLE 类别文案，户数本身不受影响。
不要与既有字段 pendingReviewHouseholds 混淆（仅 H2 详情端点有此字段）：pendingReviewHouseholds 是房务看板自己的统计口径，只数房需求，任何时候都下发；新增的 requirementReopenPendingHouseholds 是团级确认闸的提示，数的是房、车两类待审需求的户去重并集，且只在上述 3 道闸门都满足时才有值。同一个团这两个数字不一致是正常的，不能互相对账。
#8548 行为修复（不涉及任何字段新增/删除）：POST /v3/admin/order/group-batch/{groupBatchId}/requirement/confirm 整团确认时，若团期处于「整团免车」（管理员声明免车，vehicleWaived=true）状态，此前该分支对车侧释放集合恒返回空，导致该团后续补交的接送机（TRANSFER）需求永远放行不到、团级需求闸永久卡在待确认。修复后免车团确认会释放 TRANSFER 需求，但仍不释放 TRAVEL（整团免车声明的管辖范围只到 TRAVEL，释放 TRAVEL 等于替管理员推翻免车声明）。可观察的变化只是响应里既有字段 transferDispatchedOrderIds/vehicleDispatchedCount 现在对免车团也可能非空，响应 VO 结构本身零改动。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	A2 团期详情	GET	`/v3/admin/order/group-batch/{groupBatchId}`	字段新增（非破坏性）	响应新增 `requirementReopenPendingHouseholds`/`requirementReopenResourceType`
2	H1 房务团期看板列表	GET	`/v3/admin/house/group-batches`	字段新增（非破坏性）	同上，列表项级别
3	H2 房务团期看板详情	GET	`/v3/admin/house/group-batches/{groupBatchId}`	字段新增（非破坏性）	同上
4	团期配车总览	GET	`/admin/fleet/group-dispatch/batches/{groupBatchId}/overview`	字段新增（非破坏性）	同上，order-v3 原样透传，fleet 不自算

三、接口详情

1. A2 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`

VO: (无请求体，仅路径参数) → GroupBatchDetailRespVO

使用场景

团期管理员在团期详情页查看需求确认状态。此前该页只能看到 requirementConfirmed=false，无法区分「等定制师第一次提交」「被管理员打回」「已重新提交但还有户没处理完」三种情况，一律渲染「待管理员重新确认」。本次起，属于第三种情况（定制师改需求触发的自动重开，且确实还有户在等审）时，响应额外带出具体待审户数与是谁（房/车）推倒了确认闸。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	-	团期聚合主键

出参字段表

以下是本次新增/说明文案更新的字段；其余既有字段结构未变，不重复列出。

字段	类型	说明
requirementConfirmed	Boolean	需求整体确认标记（既有字段，说明文案本次更新）：为 `false` 时不要直接渲染「待管理员重新确认」，先看 `requirementReopenPendingHouseholds`
requirementReopenPendingHouseholds	Integer	新增。需求待审核户数：`requirementConfirmed=false` 且是「定制师改需求触发的自动重开」时下发；为 `null` 表示不下发（已确认 / 管理员打回置 0 / 已无人待审），按原有文案渲染。计数单位是「户」不是「需求行」——同一户同时报行程用车与接送机用车只计 1 户
requirementReopenResourceType	String	新增。触发最近一次需求重开的资源类别 `HOTEL` / `VEHICLE`：只标「谁把确认闸推倒了」，与户数口径无关（户数是房、车两类的并集）；取不到时为 `null`，此时文案不带类别

请求示例

GET /v3/admin/order/group-batch/2104839654727618562

响应示例

真实实测（测试网关，业务 admin 身份）。以下为节选（仅摘录本次相关字段，其余既有字段结构未变，不重复列出）：

{
  "code": 200,
  "data": {
    "groupBatchId": "2104839654727618562",
    "batchNo": "T26-3963",
    "requirementConfirmed": false,
    "requirementReopenPendingHouseholds": 1,
    "requirementReopenResourceType": "VEHICLE"
  },
  "success": true
}

空数据 / 降级响应

3 道闸门任一不满足（已确认 / 管理员手动打回 / 重开后已无人待审）：两个新字段均为 null，前端按原有文案渲染。
重开留痕的 extra JSON 解析失败或缺键：仅 requirementReopenResourceType 单独降级为 null，requirementReopenPendingHouseholds 不受影响照常下发（服务端 readResourceType() 的不对称降级，不会因为类别取不到而连户数一起丢）。

错误响应

{"code":589500,"message":"团期不存在","data":null,"traceId":null,"success":false}

其余既有错误码本次未变：589507（无操作权限：当前角色未授予团期权限，或该团期不在您名下）。

业务边界

🔴 requirementReopenPendingHouseholds 为 null 不代表 0，不要折算成 0 渲染。
requirementReopenResourceType 可能单独为 null（即使户数非空），此时只显示户数、不带类别文案。
判断是否要展示这两个字段，先看 requirementConfirmed；requirementConfirmed=true 时两个新字段恒为 null，不需要额外判断。

2. H1 房务团期看板列表 `GET /v3/admin/house/group-batches`

VO: HouseGroupBatchBoardPageReqVO → PageResult<HouseGroupBatchBoardSimpleRespVO>

使用场景

房务在看板列表页浏览已认领的团期。列表项与详情页（见下）共用同一套团级字段判定逻辑，此前列表页同样只能看到 requirementConfirmed=false 一个布尔值，本次起可展示与详情页一致的待审户数与类别提示。

入参字段表

字段	位置	类型	必填	约束	说明
scope	Query	String	❌	最长 8	可见范围 `MINE`（默认，只看本人认领）/ `ALL`（看全部已认领团，#8491 起全体房务可传）
claimerAdminId	Query	Long	❌	-	按认领人筛（仅 `scope=ALL` 生效）
planStatus	Query	String	❌	最长 16	计划行状态 `PENDING` / `CONFIRMED`，不传=全部
batchStatus	Query	String	❌	最长 200	团期状态多选，逗号分隔；默认四态；`CANCELLED` 传入被忽略
stayDateFrom	Query	LocalDate	❌	ISO 日期	住期区间起
stayDateTo	Query	LocalDate	❌	ISO 日期	住期区间止
departDateFrom	Query	LocalDate	❌	ISO 日期	出发日区间下界
departDateTo	Query	LocalDate	❌	ISO 日期	出发日区间上界
keyword	Query	String	❌	最长 32	团期号或产品名包含匹配
page	Query	Long	❌	≥1，默认 1	页码
pageSize	Query	Long	❌	1~50，默认 20	每页条数

出参字段表

以下是本次新增/说明文案更新的字段（列表项级别）；其余既有字段结构未变，不重复列出。

字段	类型	说明
requirementConfirmed	Boolean	需求整体确认标记（既有字段，说明文案本次更新）：为 `false` 时先看 `requirementReopenPendingHouseholds` 再定文案
requirementReopenPendingHouseholds	Integer	新增。语义与 A2 完全一致（同一产出口）
requirementReopenResourceType	String	新增。语义与 A2 完全一致

请求示例

GET /v3/admin/house/group-batches?scope=ALL&pageSize=50

响应示例

真实实测（测试网关，房务角色）。列表口只显示已被房务认领的团，本次实测命中的这一条是已确认团（双 null 基线），节选：

{
  "code": 200,
  "data": {
    "list": [
      {
        "groupBatchId": "2104838272570245121",
        "requirementConfirmed": true,
        "requirementReopenPendingHouseholds": null,
        "requirementReopenResourceType": null
      }
    ],
    "total": 1
  },
  "success": true
}

说明：本轮实测范围内命中的已认领团恰好都是已确认状态，未独立捕获非空实例；非空实例已在 A2/H2/fleet 总览三端用同一真实团期（T26-3963）交叉验证一致，H1 走的是同一个 GroupBatchRequirementReopenHintService 产出口，字段契约同源，只是列表口的可见集合（仅已认领团）与详情口不同。

空数据 / 降级响应

无匹配团期：list 为空数组，total 为 0（既有行为未变）。
候选集超 500 时 total 返回 -1 表示未统计（既有行为，本次未变，与新字段无关）。
3 道闸门任一不满足：该行的两个新字段均为 null。

错误响应

{"code":808090,"message":"未登录或非房务角色，无权操作","data":null,"traceId":null,"success":false}

业务边界

未认领的团不在本列表口，与团期抢单池页以「认领动作」为界互斥，新字段不改变这条边界。
同上，null 不代表 0；requirementReopenResourceType 可单独为 null。

3. H2 房务团期看板详情 `GET /v3/admin/house/group-batches/{groupBatchId}`

VO: (无请求体，仅路径参数) → HouseGroupBatchBoardRespVO

使用场景

房务点开具体团期查看逐日配房详情。全体房务可读任意团期（不校验认领归属），他人认领的团返回 readOnly=true（#8491，与本次改动无关）。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	-	团期主订单 ID

出参字段表

以下是本次新增/说明文案更新的字段；其余既有字段（hotelReady、pendingReviewHouseholds、days[] 等）结构未变，不重复列出。

字段	类型	说明
requirementConfirmed	Boolean	需求整体确认标记（既有字段，说明文案本次更新）：为 `false` 时先看 `requirementReopenPendingHouseholds` 再定文案
requirementReopenPendingHouseholds	Integer	新增。语义与 A2 完全一致；🔴 与既有字段 `pendingReviewHouseholds` 不是一回事——后者只数房需求、任何时候都下发，前者是房车并集且只在 3 道闸门满足时下发，同一个团两者数字不一致是正常的，不能互相对账
requirementReopenResourceType	String	新增。语义与 A2 完全一致

请求示例

GET /v3/admin/house/group-batches/2104839654727618562

响应示例

真实实测（测试网关，房务角色）。节选：

{
  "code": 200,
  "data": {
    "groupBatchId": "2104839654727618562",
    "requirementConfirmed": false,
    "requirementReopenPendingHouseholds": 1,
    "requirementReopenResourceType": "VEHICLE",
    "pendingReviewHouseholds": 0
  },
  "success": true
}

与同一团在 A2、fleet 总览的实测结果逐字段一致（requirementReopenPendingHouseholds=1、requirementReopenResourceType="VEHICLE"），印证三端同源同算法；pendingReviewHouseholds=0 与 requirementReopenPendingHouseholds=1 在此例中不同，正是上表说明的两套口径不对账的真实样本。

空数据 / 降级响应

3 道闸门任一不满足：两个新字段均为 null。
requirementReopenResourceType 单独降级为 null 时 requirementReopenPendingHouseholds 不受影响。

错误响应

{"code":589500,"message":"团期不存在","data":null,"traceId":null,"success":false}

{"code":808090,"message":"未登录或非房务角色，无权操作","data":null,"traceId":null,"success":false}

业务边界

🔴 requirementReopenPendingHouseholds 非空不要与 pendingReviewHouseholds 混淆或相加，两者统计口径不同。
null 不代表 0；requirementReopenResourceType 可单独为 null。

4. fleet 团期配车总览 `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/overview`

VO: (无请求体，仅路径参数) → GroupDispatchOverviewRespVO

使用场景

车务在配车总览页查看该团的需求确认状态、逐日排车与接送机缺口。requirementReopenPendingHouseholds/requirementReopenResourceType 由 order-v3 内部覆盖口（GET /v3/internal/group-batch/{id}/vehicle-coverage，Feign 专用，非前端可直接调用）原样透传，fleet 侧不做任何二次计算，与 A2/H2 保证同一口径。

入参字段表

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	-	团期主订单 ID

出参字段表

以下是本次新增/说明文案更新的字段；其余既有字段（serviceDates、vehicleReady、days[]、orders[]、transferPendingTotal、conversationKey 等）结构未变，不重复列出。

字段	类型	说明
requirementConfirmed	Boolean	整团需求是否已确认（既有字段，说明文案本次更新）：为 `false` 时先看 `requirementReopenPendingHouseholds` 再定文案
requirementReopenPendingHouseholds	Integer	新增。order-v3 覆盖口原样透传，fleet 不自算；🔴 `null` 不代表 0，不要折算成 0 渲染
requirementReopenResourceType	String	新增。order-v3 覆盖口原样透传，语义与 A2 完全一致

请求示例

GET /admin/fleet/group-dispatch/batches/2104839654727618562/overview

响应示例

真实实测（测试网关，车务角色，roleId=5）。节选：

{
  "code": 200,
  "data": {
    "groupBatchId": "2104839654727618562",
    "batchNo": "T26-3963",
    "requirementConfirmed": false,
    "requirementReopenPendingHouseholds": 1,
    "requirementReopenResourceType": "VEHICLE"
  },
  "success": true
}

与同一团在 A2、H2 的实测结果逐字段一致。

空数据 / 降级响应

3 道闸门任一不满足：两个新字段均为 null，与 A2/H2 同步（同一份覆盖口数据）。
order-v3 覆盖口不可达时，整个端点按既有降级规则返回 600012（团期配车基线不可达），不会出现「新字段单独降级、其余字段正常」的中间态——两个新字段与其余团级字段是同一次 Feign 调用的产物，不可能分开失败。

错误响应

{"code":600012,"message":"团期配车基线不可达，请稍后重试","data":null,"traceId":null,"success":false}

其余既有错误码本次未变：401（未登录）。

业务边界

🔴 requirementReopenPendingHouseholds 为 null 不代表 0。
该字段与 fleet 自己的 transferPendingTotal（接送机未配计数）是两回事：前者是「团级需求确认闸的提示」，后者是「已确认需求里还有多少接送机缺口没排车」，两者可以同时非空，互不覆盖。

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

本节只写后端响应字段的正确消费方式，不写 UI 渲染建议。

✅ 正确 / ❌ 错误 payload 对照

场景	说明
✅ 判断是否展示「N 户需求待审核」	先判 `requirementConfirmed===false`，再判 `requirementReopenPendingHouseholds != null`
✅ 处理 `requirementReopenPendingHouseholds` 非空但 `requirementReopenResourceType` 为 `null`	只渲染「N 户需求待审核」，不带类别文案，这是合法的降级态，不是异常
❌ 把 `requirementReopenPendingHouseholds` 为 `null` 折算成 0 渲染	`null` 与「0 户待审」是两种不同状态：前者是「不适用/无需提示」，后者是「重开了但已处理完」——本次实现中「已处理完」同样落到 `null`（闸门 3 过滤），所以两者当前观察上是同一渲染结果，但契约上不保证永远如此，不要做数值折算
❌ 拿 H2 的 `pendingReviewHouseholds` 和 `requirementReopenPendingHouseholds` 相加或对账	两个字段统计口径不同（前者只数房、恒下发；后者数房车并集、条件下发）

切换状态时的必要动作

无。本次 4 个端点均为只读字段新增，不涉及任何请求体/入参变化，前端无需在调用序列上做任何调整。

五、数据库行为

GroupBatchRequirementReopenHintService 只读、不写任何表。查库固定 3 次批量查询（不随团期数量线性增长）：① 从 group_batch 内存过滤未确认团；② 按团期 ID 批量查 group_batch 状态时间线，取最近一条 BATCH_REQUIREMENT_REOPENED 事件日志；③ 按事件命中的团批量取在团子订单 ID，再批量查待审核户。看板一页多团时同样是固定 3 次查询，不退化为 N+1。

#8548 修复：doConfirm 内核在整团免车分支新增一次车侧需求释放调用（dispatchGroupTransferRequirements），与既有的房侧放行在同一事务内，任一步失败整团零写入（既有的 809112 整团回滚保证不变）。

六、边界行为

团级 requirementConfirmed=true（已确认）→ 4 个端点的两个新字段恒为 null。
requirementConfirmed=false 但查不到 BATCH_REQUIREMENT_REOPENED 留痕（即管理员手动打回，而非定制师改需求触发的自动重开）→ 两个新字段恒为 null，前端渲染原有的「待管理员重新确认」文案。
requirementConfirmed=false 且有重开留痕，但重开后该团在团户已全部处理完（待审户数为 0）→ 两个新字段恒为 null。
重开留痕的 extra JSON 缺失/为空/解析失败 → 仅 requirementReopenResourceType 单独为 null，requirementReopenPendingHouseholds 不受影响。
（#8548，确认端点行为变更，非本次响应字段变化） 整团免车团（vehicleWaived=true）确认时，此前车侧释放集合恒为空，接送机需求永远放行不到；修复后释放 TRANSFER（接送机）需求，仍不释放 TRAVEL（行程用车，整团免车声明的管辖范围仅限于此）；同时不推进正式团级用车需求（groupVehicleRequirementId/Status/Version 三个既有字段在免车分支仍为 null，因为免车团本就没有需要推进的正式需求，此行为本次未变）。

六.5、枚举 / 数据字典

需求重开资源类别（`requirementReopenResourceType`）

所属字段: requirementReopenPendingHouseholds 的伴生字段，4 个端点通用 | 类型: String（取不到时为 null）

值	含义	说明
`HOTEL`	定制师改住宿需求触发的自动重开
`VEHICLE`	定制师改用车需求触发的自动重开
`null`	取不到类别，或未落入需要下发的场景	户数字段仍可能非空，参见六、边界行为

取值来源：团期状态时间线里最近一条 BATCH_REQUIREMENT_REOPENED 事件日志的 extra JSON 中 resourceType 键，由触发重开的那条业务逻辑写入；本次未新增写入路径，只新增读取与下发。

六.6、修改前后对比

字段级对比

字段	改前	改后
`requirementReopenPendingHouseholds`	不存在（4 个端点均无）	新增，`Integer`，语义见上，4 端点同源同算法
`requirementReopenResourceType`	不存在（4 个端点均无）	新增，`String`，语义见上

行为级对比

场景	改前	改后
`requirementConfirmed=false` 且是定制师改需求触发的自动重开、确实还有户在等审	4 个端点均只有 `requirementConfirmed=false`，前端一律渲染「待管理员重新确认」，无法与「管理员手动打回」区分	额外带出具体待审户数与资源类别，可渲染「N 户需求待审核」区分于打回场景
整团免车团确认（`POST .../requirement/confirm`）	车侧释放集合恒为空，免车后补交的接送机需求永远放行不到，团级需求闸永久卡在待确认，无任何报错或日志提示	释放 TRANSFER 需求（不释放 TRAVEL），响应既有字段 `transferDispatchedOrderIds`/`vehicleDispatchedCount` 对免车团可能非空

六.7、影响评估

是否破坏向后兼容: 否——4 个只读端点均为纯字段新增，既有字段类型/取值/含义均未变；#8548 修复不改变响应 VO 结构，只改变部分既有字段（transferDispatchedOrderIds/vehicleDispatchedCount）在特定场景下的实际取值。旧前端忽略新字段不受任何影响。
前端是否必须同步上线: 否（不上线不会报错或丢功能）；建议同步——上线后可以把「待管理员重新确认」与「N 户需求待审核」两种场景分开展示，减少运营/房务/车务误判为同一种阻塞。
前端 workaround 清理点: 若此前为区分「打回」与「重开待审」两种 requirementConfirmed=false 场景写过额外查询或猜测逻辑，现在可以直接用新字段替换。

七、不影响范围

仅影响: 上表列出的 4 个只读端点的响应字段；POST /v3/admin/order/group-batch/{groupBatchId}/requirement/confirm 端点在整团免车场景下的车侧释放行为。
零影响:
- 4 个只读端点的请求参数与既有校验规则
- POST .../requirement/confirm 的请求体、响应 VO 结构、非免车团的确认行为
- POST .../requirement/confirm 在免车团场景下对 TRAVEL 需求的处理（仍不放行，逐单放行入口不受影响）
- GET /v3/internal/group-batch/{id}/vehicle-coverage 内部 Feign 端点之外的其它 internal 接口
- PUT /admin/fleet/assignments/pickup-dropoff-config 等接送机配置端点

八、测试环境已验证

服务：hl-order-service-v3 @ ff6863754、hl-fleet-service @ 99fb369ba（deploy-status.sh 实测部署登记，测试网关 https://api.test.1814.love）；git merge-base --is-ancestor ddea7e710c ff6863754 与 ... 99fb369ba 均为真，确认本单所在提交已随两个服务的当前部署一并上线。

✓ GET /v3/admin/order/group-batch/2104839654727618562（业务 admin）：真实返回
  requirementConfirmed=false, requirementReopenPendingHouseholds=1, requirementReopenResourceType="VEHICLE"
✓ GET /v3/admin/house/group-batches/2104839654727618562（房务角色）：同一团返回同一取值，
  三端一致；附带既有字段 pendingReviewHouseholds=0，印证两套口径不对账
✓ GET /admin/fleet/group-dispatch/batches/2104839654727618562/overview（车务角色，roleId=5）：
  同一团返回同一取值，三端一致
✓ GET /v3/admin/house/group-batches?scope=ALL&pageSize=50（房务角色）：真实返回列表，
  命中已认领团（groupBatchId=2104838272570245121）为已确认状态，
  requirementReopenPendingHouseholds=null、requirementReopenResourceType=null，验证了 null 基线分支

注：H1 列表口本轮未独立捕获非空实例——T26-3963（本次用于交叉验证的团）未被房务认领，不出现在 H1 的可见集合里；H1 与其余三端共用同一个 GroupBatchRequirementReopenHintService 产出口，字段契约同源，此限制是列表口「仅显示已认领团」这一既有边界导致的取样限制，不是实现差异。

#8548 确认端点在整团免车分支释放 TRANSFER 需求的修复，本轮未做真实原子调用验证（该端点为写端点，会推进团级需求状态，测试服现存数据上误调用有污染业务状态的风险）；已按源码逐行核实：GroupBatchRequirementService.java 505-593 行（doConfirm 内核 javadoc 第三段与 569-572 行分支代码）、1161-1296 行（放行集合装配 javadoc 与 waivedVehicleSnapshot 方法 javadoc）。前端如需验证该行为，应在确认后核对响应里 transferDispatchedOrderIds 是否包含预期订单，而不是依赖某个新字段（该端点响应结构本次未变）。

十、相关文档

关联 Issue: wx/HL#8548、wx/HL#8549
关联 PR: wx/HL#8586

关联 / 联系人

链接

Issue: #8548、#8549
PR: #8586
Merge commit: ddea7e710c

联系人

后端负责人: @wx

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

hl-order-service-v3 / hl-fleet-service：团期需求重开待审提示接入 4 个只读端点，并修复整团免车团确认时接送机需求放行不到的问题

⚠️ 关键变化

二、变更接口清单

三、接口详情

1. A2 团期详情 GET /v3/admin/order/group-batch/{groupBatchId}

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. H1 房务团期看板列表 GET /v3/admin/house/group-batches

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. H2 房务团期看板详情 GET /v3/admin/house/group-batches/{groupBatchId}

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

4. fleet 团期配车总览 GET /admin/fleet/group-dispatch/batches/{groupBatchId}/overview

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

✅ 正确 / ❌ 错误 payload 对照

切换状态时的必要动作

五、数据库行为

六、边界行为

六.5、枚举 / 数据字典

需求重开资源类别（requirementReopenResourceType）

六.6、修改前后对比

字段级对比

行为级对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

链接

联系人

28 KiB

原始文件 Blame 文件历史

1. A2 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`

2. H1 房务团期看板列表 `GET /v3/admin/house/group-batches`

3. H2 房务团期看板详情 `GET /v3/admin/house/group-batches/{groupBatchId}`

4. fleet 团期配车总览 `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/overview`

需求重开资源类别（`requirementReopenResourceType`）