328 行
14 KiB
Markdown
328 行
14 KiB
Markdown
---
|
||
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
|