wx/hl-api-changelog

派生 0

文件

T

Mimingguang 652b07758a

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

详情

chore(changelog): 回写 #7769/#7770 团期列表增量 frontend_status=verified(hl-admin a9148fc9)

2026-09-16 14:47:30 +08:00

14 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	7769	团期列表与看板统计条补距出团天数与成团户数门槛	admin	wx(GIT)	修改接口	deployed	not_required	verified	mmg	a9148fc9d13dedbccd2ad4f2a17b452172838efd		2026-09-16	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 全绿。	2026-09-16	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 表示未设，前端不显示成团标准

请求示例

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

响应示例

{
  "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 列表。

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

错误响应

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

请求示例

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

响应示例

{
  "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，八桶与计数照常返回。

{ "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 }

错误响应

{ "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

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

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

⚠️ 关键变化

二、变更接口清单

三、接口详情

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

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

六、边界行为

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

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

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

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

AC-4 老调用兼容

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

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

十、相关文档

关联 / 联系人

14 KiB

原始文件 Blame 文件历史

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

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

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

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

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