---
schema: "hl-changelog/v2"
ticket: "7769"
title: "团期列表与看板统计条补距出团天数与成团户数门槛"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "a9148fc9d13dedbccd2ad4f2a17b452172838efd"
target_release: ""
verified_at: "2026-09-16"
status_note: "GB-ADM-001 出参新增 daysToDepart / minToForm，GB-ADM-009 出参新增 minToForm / maxRooms，均为纯新增字段，路径与入参不变，老调用响应除新增键外逐字不变。PR #7776 已合入 dev-v3（merge commit 4559f35d0）。；前端 hl-admin a9148fc9 已实现：PeriodRow 行内 daysToDepart 倒计时(>0 显/=0 今日出发/<0 不显,禁本地自算)+cap-std 并入 minToForm 成团段,统计条副标题两值同 >0 才显,checkpoint 全绿。"
updated_at: "2026-09-16"
base: "dev-v3"
---

# 团期列表与看板统计条补距出团天数与成团户数门槛（修改接口）

> **服务**: hl-order-service-v3
> **PR**: #7776
> **Issue**: #7769
> **日期**: 2026-09-16
> **影响范围**: 两个既有 GET 读接口的出参新增字段；无新端点、无路由变化、无 DDL、无新增错误码

---

## ⚠️ 关键变化

🔵 **纯新增出参字段，老调用不受影响。** 两个接口的路径、入参、`Result` 信封、既有字段的取值与顺序全部不变，只是各多返回两个键。

前端团期列表页此前做不出原型的「距出团 N 天」与统计条副标题「满 N 户成团 · 满 M 户满团」，根因就是接口不给这三个值，现已补齐。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 团期分页列表 | GET | `/v3/admin/order/group-batch` | 修改接口 | 出参新增 `daysToDepart`、`minToForm` |
| 2 | 团期看板统计条 | GET | `/v3/admin/order/group-batch/summary` | 修改接口 | 出参新增 `minToForm`、`maxRooms` |

---

## 三、接口详情

### 1. 团期分页列表 `GET /v3/admin/order/group-batch`

**VO**: `GroupBatchPageItemRespVO`

#### 使用场景

团期订单列表页逐行渲染。本次新增的两个字段供「距出团 N 天」倒计时与「满 N 户成团」成团标准展示。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| productId | query | string | 否 | 雪花 ID 字符串 | 按产品筛选；有值时走合并基底 |
| opsStage | query | string | 否 | 八桶 code | 运营阶段筛选 |
| scope | query | string | 否 | ONGOING/FINISHED/ALL | 班期范围 |
| pageNo | query | integer | 是 | ≥1 | 页码 |
| pageSize | query | integer | 是 | 1~100 | 每页条数 |

> 入参本次**无任何变化**，上表仅列与新增出参相关的常用项，完整入参见既有契约。

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| daysToDepart | integer | **新增**。距出发剩余天数 = 出发日 − 服务端当天；**负数表示出发日已过**，不截断为 0；出发日为空时为 null |
| minToForm | integer | **新增**。成团闸的最低成团**户数**门槛（户=订单=房）；0 或 null 表示未设，前端不显示成团标准 |

#### 请求示例

```http
GET /v3/admin/order/group-batch?pageNo=1&pageSize=10&productId=2056947670512971778&opsStage=FORMED&scope=ONGOING
Authorization: Bearer <admin token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "groupBatchId": "2096495107078328322",
        "batchNo": "Q202612202096494989117677570",
        "batchLabel": "12",
        "batchStatus": "RESOURCE_PREPARING",
        "opsStage": "FORMED",
        "departDate": "2026-12-20",
        "endDate": "2026-12-21",
        "daysToDepart": 95,
        "minGroupPeople": 0,
        "minToForm": 6,
        "maxRooms": 9,
        "enrolledRooms": 2,
        "remainRooms": 7
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  },
  "success": true
}
```

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

命中为空时 `records` 为空数组、`total` 为 0，两个新字段不出现在任何行上；不返回 null 列表。

```json
{ "code": 200, "message": "成功", "data": { "records": [], "total": 0, "page": 1, "pageSize": 10 }, "success": true }
```

#### 错误响应

```json
{ "code": 401, "message": "Token无效或已过期", "data": null, "success": false }
```

网关与业务错误一律 HTTP 200，判定看 body 的 `code`。

#### 业务边界

- `daysToDepart` 以**服务端当天**为基准，前端不要用本地时间自行计算，否则跨时区/跨零点会与列表不一致。
- 「出行中 / 已返团」由前端用 `daysToDepart` 配合 `endDate` 自行判定，后端不再另给中文态。
- `minToForm` 在 `productId` 有值时取产品域实时值，与团期详情 GB-ADM-002 的同名字段同源同值；`productId` 缺省或产品侧班期已删（孤儿行）时回落订单域建团快照，此时可能与详情的实时值不同。
- `minToForm` 与 `minGroupPeople` 是两回事：前者是**户数**门槛，后者是**人数**门槛，别混用。

### 2. 团期看板统计条 `GET /v3/admin/order/group-batch/summary`

**VO**: `GroupBatchSummaryVO`

#### 使用场景

团期列表页顶部「班期总览」统计卡。本次新增两个字段供副标题「成团标准：满 N 户成团 · 满 M 户满团」。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| productId | query | string | 否 | 雪花 ID 字符串 | 按产品筛选；决定两个新字段是否有值 |
| month | query | string | 否 | yyyy-MM | 出团月份 |
| keyword | query | string | 否 | — | 编号/名称模糊 |
| scope | query | string | 否 | ONGOING/FINISHED/ALL | 班期范围 |

> 入参本次**无任何变化**。

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| minToForm | integer | **新增**。最低成团户数门槛；仅 `productId` 有值且命中行门槛取值唯一时给值，否则 null |
| maxRooms | integer | **新增**。房间容量（满团标准）；取值规则同 `minToForm` |

#### 请求示例

```http
GET /v3/admin/order/group-batch/summary?productId=2056947670512971778&scope=ONGOING
Authorization: Bearer <admin token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "total": 11,
    "buckets": { "RECRUIT": 5, "FORMED": 2, "PENDING_TRIP": 0, "TRAVELLING": 0, "TRIP_FINISHED": 0, "AUDITING": 0, "CHECKED": 0, "DISBANDED": 4 },
    "subOrderCount": 3,
    "minToForm": 6,
    "maxRooms": 9
  },
  "success": true
}
```

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

不带 `productId`（跨产品）时门槛不唯一，两个字段均返回 null，八桶与计数照常返回。

```json
{ "code": 200, "message": "成功", "data": { "total": 0, "buckets": { "RECRUIT": 0, "FORMED": 0, "PENDING_TRIP": 0, "TRAVELLING": 0, "TRIP_FINISHED": 0, "AUDITING": 0, "CHECKED": 0, "DISBANDED": 0 }, "subOrderCount": 0, "minToForm": null, "maxRooms": null }, "success": true }
```

#### 错误响应

```json
{ "code": 401, "message": "Token无效或已过期", "data": null, "success": false }
```

#### 业务边界

- 同一产品各班期理论上可配不同门槛，命中行取值**不唯一时返回 null**，后端不取第一条冒充全体；前端据此不显示副标题。
- 该字段是产品级常量的投影，不参与八桶计数，也不影响 `total` / `subOrderCount`。

---

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

- 两个接口均为 GET 只读，路径与入参不变，**前端可按需增量接入，不接也不会坏**。
- `daysToDepart` 是整数且可为负，前端渲染「距出团 N 天」前先判 `> 0`；`= 0` 是当天出发；`< 0` 表示已过出发日。
- 成团标准优先用 `minToForm`（户），不要用 `minGroupPeople`（人）去拼「满 N 户成团」。
- 统计条副标题只在 `minToForm` 与 `maxRooms` 同时非 null 时展示。

---

## 六、边界行为

- 出发日为空的团期：`daysToDepart` 为 null，不是 0。
- 容量为 0/null 按「不限」语义：`remainRooms` / `remainParticipants` 仍按既有规则返回 null，本次未改。
- 合并基底（`productId` 有值）下，行的出发日以产品域权威值为准，`daysToDepart` 按该权威出发日计算，不用建团快照日期。

---

## 六.6、修改前后对比

| 接口 | 改前 | 改后 |
|---|---|---|
| GB-ADM-001 | 无距出团天数；无户数门槛，只有人数门槛 `minGroupPeople` | 新增 `daysToDepart`、`minToForm`，其余字段逐字不变 |
| GB-ADM-009 | 只有 `total` / `buckets` / `subOrderCount` | 新增 `minToForm`、`maxRooms`，其余字段逐字不变 |

老调用不读新键时，两个接口的响应与改前**逐字一致**。

---

## 六.7、影响评估

- **前端**：纯增量，不接入无影响；接入后可做出原型的倒计时与成团标准。
- **后端**：`minToForm` 复用合并基底已批量拉回的产品班期数据，**不产生逐行 Feign 调用**；单页 100 条时的远程调用次数与改前一致。
- **数据**：无表变更、无 Flyway、无写链路。
- **兼容性**：无字段删除或改名，无枚举值变化，无错误码新增。

---

## 七、不影响范围

- 团期详情 GB-ADM-002、子订单列表 GB-ADM-003、六芯片明细 GB-ADM-090~095 均未改动。
- 列表入参、分页语义、排序、权限码、网关路由均未变化。
- 小程序端接口零影响。

---

## 八、测试环境已验证

**部署**：dev-v3 @ `791506985`（PR #7776 合并提交 `4559f35d0` 已在其中），2026-09-16 11:47:47~11:49:18 滚动部署双实例（8186/8086）成功，task `e68e54cd`，exit_code=0。

**验证环境**：`https://api.test.1814.love:9443`（真实网关，admin token）。部署前已先采集同请求的「改动前」基线用于逐字对比。

### AC-1 `daysToDepart` = departDate − 服务端当天（基准日 2026-09-16）

| 情形 | batchNo | departDate | daysToDepart | 期望 | 结果 |
|---|---|---|---|---|---|
| 出发日未到 | Q202610262100047410968346625 | 2026-10-26 | 40 | 40 | ✅ |
| 出发日已过 | Q202610152099543532271267841 | 2026-09-14 | **−2** | −2 | ✅ 负数未截断为 0 |
| 出发日=当天 | Q202609162099715421815926785 | 2026-09-16 | 0 | 0 | ✅ |
| departDate 为空 | — | — | — | null | ⚠️ **TEST 环境无此数据**（`order_group_batch` 共 198 行，`depart_date IS NULL` 为 0 行），未能实测；该分支由单测 `GroupBatchConverterTest.Issue7769ListRespFields` 覆盖 |

### AC-2 GB-ADM-001 与 GB-ADM-002 的 `minToForm` 逐字相等

团期 `groupBatchId=2096495107078328322`：列表 `minToForm=6`，详情 `minToForm=6`，**逐字相等 ✅**。

### AC-3 GB-ADM-009 的 `minToForm` / `maxRooms`

| 请求 | minToForm | maxRooms | 说明 |
|---|---|---|---|
| `productId=2043696114145644545` | 0 | null | 命中 37 行的 `minToForm` 取值集合为 `{0}`（唯一）故给值；`maxRooms` 取值集合为 `{0, 10}`（**不唯一**）故按契约返回 null |
| `productId=2056947670512971778` | null | null | 该产品门槛高度分散（`min_to_form` 7 种取值），两者均不唯一 |
| 不带 `productId` | null | null | 跨产品，符合契约 |

三次实测与「取值唯一才给值、否则 null」的契约**完全一致 ✅**。

### AC-4 老调用兼容

对部署前后同一组 7 个请求逐字对比（剔除新增键后做 JSON 全量比较）：

| 用例 | 除新增键外一致 | 新增键 |
|---|---|---|
| GB001 productId+opsStage+scope | ✅ | daysToDepart, minToForm |
| GB001 productId only | ✅ | daysToDepart, minToForm |
| GB001 DB 基底 | ✅ | daysToDepart, minToForm |
| GB001 DB 基底 scope=ALL | ✅ | daysToDepart, minToForm |
| GB001 DB 基底 第 2 页 | ✅ | daysToDepart, minToForm |
| GB009 带 productId | ✅ | maxRooms, minToForm |
| GB009 不带 productId | ✅ | maxRooms, minToForm |

**7/7 全部逐字一致 ✅**，新增键恰为本次声明的字段，无其他差异。

### AC-5 单页 100 条不产生逐行产品域 Feign

对 `pageSize=100&productId=2056947670512971778&scope=ALL` 连打 5 次，同时以部署面板 SSE 日志流抓取 order-v3 primary 实例日志。该请求段共 276 行日志，确含 6 条 `Preparing:` SQL 与 5 条 `Total:` 结果行（证明调用确被记录，非空日志）：

```
==> Preparing: SELECT group_batch_id,product_batch_id,enrolled_people,enrolled_rooms
    FROM order_group_batch WHERE deleted_at IS NULL AND (product_batch_id IN (?,?,?,?,?,?,?,?,?,?))
==> Preparing: SELECT product_batch_id,adult_count,child_count,young_child_count,baby_count
    FROM order_main WHERE deleted_at IS NULL AND (product_batch_id IN (?,?,?,?,?,?,?,?,?,?) AND order_status <> ?)
```

全部走 `product_batch_id IN (?,?,…)` **批量 IN 查询**；`feign` / `ProductFeign` / `batch-stats` / `group-tour-batch` / `product-service` / `RestTemplate` / `WebClient` 七个关键词在整段日志中**出现次数均为 0**。单页 100 条仅产生 6 条 SQL，远低于「逐行调用应 ≥100」的阈值 ✅

### AC-6 / AC-7 单测与全量

- 边界单测：`GroupBatchConverterTest.Issue7769ListRespFields` 新增 11 例，覆盖 `departDate` 为空、出发日已过、跨产品门槛为 null；`GroupBatchBoardStatsServiceTest` 新增 3 例。均为 JUnit5 + Mockito，未用 `@SpringBootTest`。
- 全量：`hl-order-service-v3` Half A（`com.hulalv.order.**`）**Tests run: 7510, Failures: 0, Errors: 0, Skipped: 0, BUILD SUCCESS**；Half B（其余包）3888 / 0 / 0 / 7。

---

## 十、相关文档

- 差异来源：`需求分析/测试发现问题.md` 模块 1
- 原型出处：`需求分析/2026-09-11-团期模块需求分析.md` §1.2、§2.2.1、§2.2.4

## 关联 / 联系人

- 后端：wx
- 前端：mmg