286 行
12 KiB
Markdown
286 行
12 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7770"
|
||
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 入参新增 departFrom / departTo / sortBy / sortOrder，均为可选；不传时行集与行序与改前逐条一致。出参不变。PR #7777 已合入 dev-v3（合并提交 791506985），已部署 TEST 并逐条取证。；前端 hl-admin a9148fc9 已实现：筛选条出团日期 daterange+排序 select 组合值拆分透传(空不落参),四参仅 001 透传 009 不带,显式排序月组跟随 records 首见序,checkpoint 全绿。"
|
||
updated_at: "2026-09-16"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 团期列表补出团日期区间筛选与排序参数（修改接口）
|
||
|
||
> **服务**: hl-order-service-v3
|
||
> **PR**: #7777
|
||
> **Issue**: #7770
|
||
> **日期**: 2026-09-16
|
||
> **影响范围**: 一个既有 GET 读接口的入参新增；出参不变、无新端点、无路由变化、无 DDL、无新增错误码
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
🔵 **纯新增可选入参，不传时行为与改前逐条一致。** 团期列表此前只能按整月（`month`）筛出团日，搜索框里输日期搜不到；排序也写死。本次补上日期区间与排序两组参数。
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| 1 | 团期分页列表 | GET | `/v3/admin/order/group-batch` | 修改接口 | 入参新增 `departFrom`、`departTo`、`sortBy`、`sortOrder` |
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 团期分页列表 `GET /v3/admin/order/group-batch`
|
||
|
||
**VO**: `GroupBatchListReqVO`
|
||
|
||
#### 使用场景
|
||
|
||
团期订单列表页的「期号 / 日期」搜索与列表排序。日期区间用于按出团日精确筛选，排序用于按出发日或报名截止日重排。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| departFrom | query | string | 否 | yyyy-MM-dd | **新增**。出团日区间起，含当日；非法串忽略该条件并记 warn，不报错 |
|
||
| departTo | query | string | 否 | yyyy-MM-dd | **新增**。出团日区间止，含当日；口径同上 |
|
||
| sortBy | query | string | 否 | departDate / enrollDeadline / createTime | **新增**。排序字段白名单，大小写不敏感；非白名单值回落默认排序并记 warn |
|
||
| sortOrder | query | string | 否 | asc / desc | **新增**。排序方向，大小写不敏感；缺省或非法值回落 asc |
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| records | array | 出参结构本次**无变化**，逐字段沿用既有契约 |
|
||
| total | integer | 命中总数，语义不变 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch?pageNo=1&pageSize=10&productId=2056947670512971778&departFrom=2026-12-01&departTo=2026-12-31&sortBy=departDate&sortOrder=asc
|
||
Authorization: Bearer <admin token>
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"groupBatchId": "2096495107078328322",
|
||
"batchNo": "Q202612202096494989117677570",
|
||
"batchLabel": "12",
|
||
"departDate": "2026-12-20",
|
||
"endDate": "2026-12-21",
|
||
"batchStatus": "RESOURCE_PREPARING",
|
||
"opsStage": "FORMED"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"pageSize": 10
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
区间与其他条件的交集为空时返回空列表，不报错。
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "records": [], "total": 0, "page": 1, "pageSize": 10 }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{ "code": 401, "message": "Token无效或已过期", "data": null, "success": false }
|
||
```
|
||
|
||
非法日期串与非白名单排序字段**不会**产生错误响应，均按降级处理返回 200。
|
||
|
||
#### 业务边界
|
||
|
||
- `departFrom` / `departTo` 与 `month` 是两个独立条件，同时传取**交集**，互不覆盖。
|
||
- 与 `scope` 同传是**叠加**（AND）：`scope=ONGOING` 仍会把返团日已过的行剔掉，区间不会把它们捞回来。
|
||
- 无出发日的行落不进任何区间，与 `month` 同口径。
|
||
- 排序字段走枚举白名单，参数字符串不进 `ORDER BY`；排序结果按主键做次级排序，避免同值行跨页跳动。
|
||
- **期号 `batchLabel` 不在白名单**：它是字符串列，按字典序会把「第 10 期」排到「第 9 期」前；同产品内按 `departDate` 升序与期号升序等价。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
- 四个参数全部可选，**不传即完全保持改前行为**，前端可增量接入。
|
||
- 想按日期搜索请用 `departFrom` / `departTo`，不要指望 `keyword`——它只模糊匹配班期编号与名称。
|
||
- 要整月仍可继续用 `month`；与区间同传时请自行确认两者取交集后的预期。
|
||
- 排序只认白名单三个值，传别的不会报错但会被忽略，前端不要据此做「排序失败」提示。
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 非法日期串（如 `2026-13-45`、`abc`）：忽略该条件、记 warn、返回 200，行集等同于不传。
|
||
- `sortOrder` 传非 asc/desc：回落 asc 并记 warn。
|
||
- `sortBy` 传注入串：不命中白名单，回落默认排序，字符串不进 SQL。
|
||
- 合并基底（`productId` 有值，内存分页）与 DB 基底（`productId` 缺省）两条路径的筛选与排序语义一致；未指定排序时分别保持既有的出发日升序与建团时间倒序。
|
||
|
||
---
|
||
|
||
## 六.6、修改前后对比
|
||
|
||
| 能力 | 改前 | 改后 |
|
||
|---|---|---|
|
||
| 按出团日筛选 | 只有 `month`，整月粒度 | 增加 `departFrom` / `departTo` 任意区间，与 `month` 取交集 |
|
||
| 排序 | 写死（合并基底出发日升序 / DB 基底建团时间倒序） | 可传 `sortBy` + `sortOrder`，白名单三字段，未传时与改前一致 |
|
||
| 出参 | — | **无变化** |
|
||
|
||
---
|
||
|
||
## 六.7、影响评估
|
||
|
||
- **前端**：纯增量可选入参，不传无影响。
|
||
- **后端**：新增条件走既有 Wrapper 的 `geIfPresent` / `leIfPresent`，未引入新查询路径；排序由实体方法引用生成列名，无注入面。
|
||
- **数据**：无表变更、无 Flyway、无写链路。
|
||
- **兼容性**：无字段删除或改名，出参与错误码零变化。
|
||
|
||
---
|
||
|
||
## 七、不影响范围
|
||
|
||
- 出参结构、分页语义、权限码、网关路由均未变化。
|
||
- 团期详情 GB-ADM-002、统计条 GB-ADM-009、子订单列表 GB-ADM-003 未改动。
|
||
- 既有入参 `deadlineFrom` / `deadlineTo` 的解析行为保持原样（非法值仍按既有方式处理），本次未一并调整。
|
||
- 小程序端接口零影响。
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
**部署**：dev-v3 @ `791506985`（本 PR #7777 的合并提交），2026-09-16 11:47:47~11:49:18 滚动部署双实例成功，task `e68e54cd`，exit_code=0。
|
||
|
||
**验证环境**：`https://api.test.1814.love:9443`（真实网关，admin token）+ TEST MySQL 直连对照。
|
||
|
||
> 对照口径说明：`order_group_batch` 裸表 198 行，其中 `deleted_at IS NULL` 为 **132** 行，与接口 `scope=ALL` 的 `total=132` 一致，故下列 SQL 对照均带软删过滤。
|
||
|
||
### AC-1 `departFrom` / `departTo` 单独传，行集与 SQL COUNT 一致
|
||
|
||
| 区间 | 接口 total | `SELECT COUNT(*) … WHERE depart_date BETWEEN ? AND ? AND deleted_at IS NULL` | 结果 |
|
||
|---|---|---|---|
|
||
| 2026-12-01 ~ 2026-12-31 | 18 | 18 | ✅ |
|
||
| 2026-12-10 ~ 2026-12-20 | 7 | 7 | ✅ |
|
||
| 2027-03-01 ~ 2027-03-31 | 0 | 0 | ✅ |
|
||
|
||
返回的 18 个 `groupBatchId` 全部存在于表中且未软删，`departDate` 全落在区间内（2026-12-01 ~ 2026-12-27）。
|
||
|
||
### AC-2 与 `month` 取交集
|
||
|
||
| 组合 | 接口 total | SQL | 结果 |
|
||
|---|---|---|---|
|
||
| `month=2026-12` ∩ `[2026-12-10, 2026-12-20]` | 7 | 7 | ✅ 交集非空 |
|
||
| `month=2026-12` ∩ `[2027-01-01, 2027-01-31]` | 0 | 0 | ✅ 交集为空 |
|
||
|
||
（`month=2026-12` 单独为 18 行，区间单独为 7 行，交集 7 行——确为取交集而非互相覆盖。）
|
||
|
||
### AC-3 与 `scope` 叠加（AND）
|
||
|
||
区间 `[2026-09-01, 2027-01-31]` 跨越今天：
|
||
|
||
| scope | total |
|
||
|---|---|
|
||
| ALL | 128 |
|
||
| ONGOING | 122 |
|
||
| FINISHED | 6 |
|
||
|
||
`ONGOING(122) + FINISHED(6) = 128 = ALL(128)` ✅；且仅 `scope=ONGOING` 不带区间为 126 行，加区间后降为 122 行，证明区间是在 scope 之上**再过滤**而非覆盖 ✅
|
||
|
||
### AC-4 非法日期串被忽略，返回 200 且行集等同于不传
|
||
|
||
| departFrom | code | total | 与不传（132）一致 |
|
||
|---|---|---|---|
|
||
| `2026-13-45` | 200 | 132 | ✅ |
|
||
| `abc` | 200 | 132 | ✅ |
|
||
| `2026/12/01` | 200 | 132 | ✅ |
|
||
|
||
均未抛 400，服务端记 warn 后忽略该条件 ✅
|
||
|
||
### AC-5 `sortBy` 白名单升降序
|
||
|
||
| sortBy | asc | desc |
|
||
|---|---|---|
|
||
| `departDate` | ✅ 30/30 非空且升序（首 2026-09-05） | ✅ 降序（首 2027-04-15） |
|
||
| `enrollDeadline` | ✅ 30/30 非空且升序（首 2026-09-04） | ✅ 降序（首 2027-04-14） |
|
||
| `createTime` | ✅ 见下 | ✅ 见下 |
|
||
|
||
`createTime` 不在响应字段中，故翻页取满全部 **132** 行 `groupBatchId` 后回表查 `create_time` 验证：asc/desc 两侧回表命中 132/132、各自严格单调，**行集相同且互为逆序**，首尾对称（`2026-08-18 18:56:01` ↔ `2026-09-16 10:21:35`）✅
|
||
|
||
### AC-6 非白名单 / 注入串回落默认排序，且不进 SQL
|
||
|
||
对 `sortBy=depart_date; DROP TABLE order_group_batch` 连打 5 次，同时以部署面板 SSE 日志流抓取 order-v3 primary 日志（该段 444 行，含 18 条 `Preparing:` SQL）。
|
||
|
||
服务端打出回落 WARN：
|
||
|
||
```
|
||
WARN c.h.o.groupbatch.helper.GroupBatchListSortResolver [traceId=210663af876044f8]
|
||
- 团期列表排序字段不在白名单，回落默认排序: sortBy=depart_date; DROP TABLE order_group_batch
|
||
```
|
||
|
||
对应的团期列表 SQL 的排序子句为：
|
||
|
||
```
|
||
==> Preparing: SELECT group_batch_id,product_batch_id,product_id,… FROM order_group_batch
|
||
WHERE deleted_at IS NULL ORDER BY create_time DESC LIMIT ?
|
||
```
|
||
|
||
**注入串未出现在任何 `Preparing:` 行中**（含 `DROP TABLE` 的日志行共 3 行，全部是上述 `GroupBatchListSortResolver` 的 WARN 日志，其中含 `Preparing:` 的 0 行、含 `ORDER BY` 的 0 行）。全流 `ORDER BY` 子句枚举均为合法列（`create_time` / `traveler_id` / `flow_id` / `day_number` / `received_at` 等），无一含注入串 ✅
|
||
|
||
`batchLabel`（非白名单）与 `1=1 OR` 同样回落默认排序、返回 200、total 132；注入串发出后 `order_group_batch` 仍为 198 行，表未受影响 ✅
|
||
|
||
### AC-7 老调用兼容：不传任何新参数时行集与顺序逐条一致
|
||
|
||
对部署前后同一组请求比对 `total` 与 `groupBatchId` 序列：
|
||
|
||
| 用例 | total（前→后） | 行序逐条一致 |
|
||
|---|---|---|
|
||
| GB001 productId+opsStage+scope | 2 → 2 ✅ | ✅ |
|
||
| GB001 productId only | 11 → 11 ✅ | ✅ |
|
||
| GB001 DB 基底 | 132 → 132 ✅ | ✅ |
|
||
| GB001 DB 基底 scope=ALL | 132 → 132 ✅ | ✅ |
|
||
| GB001 DB 基底 第 2 页 | 132 → 132 ✅ | ✅ |
|
||
|
||
**5/5 行集与行序与改动前逐条一致 ✅**
|
||
|
||
### AC-8 / AC-9 单测与全量
|
||
|
||
- 单测：`GroupBatchListSortResolverTest` 7 例（含注入串不命中白名单且比较器为 null）、`GroupBatchMergedRowsServiceTest` +5 例（两端含、与 month 交集、交集为空、与 scope 叠加、无出发日排除）、`GroupBatchQueryServiceTest` +2 例（区间透传 Mapper、非法日期串忽略不抛）。均为 JUnit5 + Mockito，未用 `@SpringBootTest`。
|
||
- 全量：合并前在含 #7776 的最新 dev-v3 基底上重跑 Half A（`com.hulalv.order.**`）：**Tests run: 7524, Failures: 0, Errors: 0, Skipped: 0, BUILD SUCCESS**，514 个测试类，0 次 OOM。例数自洽：7510（基底）+ 14（本单新增）= 7524。Half B（其余包）3888 / 0 / 0 / 7。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 差异来源：`需求分析/测试发现问题.md` 模块 1
|
||
- 原型出处：`需求分析/2026-09-11-团期模块需求分析.md` §1.2
|
||
|
||
## 关联 / 联系人
|
||
|
||
- 后端：wx
|
||
- 前端：mmg
|