---
schema: "hl-changelog/v2"
ticket: "8548"
title: "团期需求重开待审提示接入 4 个只读端点，并修复整团免车团确认时接送机需求放行不到的问题"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "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）。"
updated_at: "2026-09-30"
base: "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`，此时文案不带类别 |

#### 请求示例

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

#### 响应示例

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

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

#### 空数据 / 降级响应

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

#### 错误响应

```json
{"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 完全一致 |

#### 请求示例

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

#### 响应示例

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

```json
{
  "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`。

#### 错误响应

```json
{"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 完全一致 |

#### 请求示例

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

#### 响应示例

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

```json
{
  "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` 不受影响。

#### 错误响应

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

```json
{"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 完全一致 |

#### 请求示例

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

#### 响应示例

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

```json
{
  "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 调用的产物，不可能分开失败。

#### 错误响应

```json
{"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](https://git.1814.love/wx/HL/issues/8548)、[wx/HL#8549](https://git.1814.love/wx/HL/issues/8549)
- 关联 PR: [wx/HL#8586](https://git.1814.love/wx/HL/pulls/8586)

## 关联 / 联系人

### 链接

- **Issue**: [#8548](https://git.1814.love/wx/HL/issues/8548)、[#8549](https://git.1814.love/wx/HL/issues/8549)
- **PR**: [#8586](https://git.1814.love/wx/HL/pulls/8586)
- **Merge commit**: [ddea7e710c](https://git.1814.love/wx/HL/commit/ddea7e710c)

### 联系人

- **后端负责人**: @wx