wx/hl-api-changelog

派生 0

文件

T

Mimingguang a6c9a3cb00

changelog-filename-gate / validate (push) Successful in 3s

详情

chore(changelog): #7245 前端实查判 not_required;#7210 复审返工增量并入待办保持 pending

2026-09-07 12:04:48 +08:00

13 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	7245	团期看板 batchName 去空格 + 不限容量 remain 统一为 null + board 库存同源	admin	jw(GIT)	修改接口	deployed	verified	not_required					PR #7256 已合入 dev-v3(732889527);2026-09-07 测试环境网关实测 AC-1/2/4/4b/5/6 全部通过。前端 mmg 已实查为 not_required:无任一读取点用后端 remainRooms/remainParticipants 判满员(PeriodRow 用 enrolledRooms>=maxRooms 自算,maxRooms=0/null 不显满团,与 null=不限一致);remainParticipants 读取点全按 !=null;前端无 batchName.trim();board enrolledRooms 仅显示。结构零变化,显示自动改善,无需改码。	2026-09-07	dev-v3

团期看板: 三处响应值口径修正（结构不变）

服务: hl-order-service-v3 ｜ PR: #7256 ｜ Issue: #7245 ｜ 合并提交: 732889527 影响范围: 管理后台团期看板分页 / board / 详情三个读端点的响应值

⚠️ 关键变化

remainRooms 与 remainParticipants 为 null 表示「不限」，前端不要按 === 0 判满员。

改前：容量字段为 0 时这两个值返 0，而同一列表里未建团行返 null，两类行语义打架，运营看到「剩余 0 人」会误判满员。改后：容量为 null 或 0 一律返 null；容量大于 0 时才返 max(0, 容量 − 已用)。

另有两处修正：班期名去除前后空格；board 未建团行的已用房数改与分页、产品侧同源。

接口路径、入参、响应结构均未变，前端无需改码。

一、背景

产品侧存量脏值（如 " 没，那你"，前导空格）经合并层实时透出成看板行标题。product 侧只在保存路径 trim、order 侧只在建团与刷新快照时 trim，存量列不会自愈。
remainParticipants 两路不一致：未建团行走 normalizeRemainingSlots（不限返 null），命中行走 calcRemain（max=0 返 0）。
board 未建团行的已用房数取订单侧计数器（不含线下占位 manual_order_count），而合并分页与产品侧取 occupiedRooms（含占位）——同一个班期两个剩余数。实测容量 8 / 占位 3 / 线上 0 时，产品侧与分页回「剩 5」，board 回「剩 8」。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	团期看板分页	GET	`/v3/admin/order/group-batch`	响应值修正	`batchName` 去空格；不限容量 remain 返 null
2	团期合并看板	GET	`/v3/admin/order/group-batch/board`	响应值修正	同上，另：未建团行已用房数改与分页同源
3	团期详情	GET	`/v3/admin/order/group-batch/:groupBatchId`	响应值修正	同 1

三、接口详情

1. 团期看板分页 `GET /v3/admin/order/group-batch`

VO: GroupBatchPageItemRespVO

使用场景

管理后台「团期订单」看板列表。传 productId 走合并基底（命中 / 未建团 / 孤儿三类行），不传走订单侧老路径。

入参

字段	位置	类型	必填	约束	说明
`productId`	Query	Long	❌	字符串传参	有值走合并基底
`scope`	Query	String	❌	`ONGOING`/`FINISHED`/`ALL`	缺省：有 productId 时 ONGOING，否则 ALL
`opsStage`	Query	String	❌	八桶之一	运营阶段筛选
`batchStatus`	Query	String	❌	团期九态	状态筛选
`month`	Query	String	❌	`yyyy-MM`	出发月
`keyword`	Query	String	❌	—	编号或名称模糊
`pageNo` / `pageSize`	Query	Integer	❌	默认 1 / 20，上限 100	分页

出参 `Result<PageResult<GroupBatchPageItemRespVO>>`

本次仅三个字段取值变化，结构不变：

字段	类型	说明
`batchName`	String	班期名，已去除前后空白；null 仍为 null
`remainRooms`	Integer	剩余房数。`maxRooms` 为 null 或 0 时返 null（不限），否则 `max(0, maxRooms − enrolledRooms)`
`remainParticipants`	Integer	剩余人数。口径同上，基于 `maxParticipants` 与 `enrolledPeople`

请求示例

GET /v3/admin/order/group-batch?productId=2044306857534636034&scope=ALL&pageSize=50

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "total": 8,
    "records": [
      {
        "productBatchId": "2052935476557328386",
        "batchName": "没，那你",
        "maxRooms": 80,
        "enrolledRooms": 55,
        "remainRooms": 25,
        "maxParticipants": 0,
        "remainParticipants": null
      }
    ]
  }
}

空数据 / 降级响应

无匹配班期时 records 为空数组、total 为 0，不报错。

错误响应

无权限：

{
  "code": 589507,
  "message": "无权限操作该团期",
  "success": false,
  "data": null
}

业务边界

只读接口，不产生任何写入
remainRooms / remainParticipants 为 null 表示不限，不是「剩 0」
命中行容量读订单侧快照，未建团行读产品侧实时值——改产品容量不会立刻影响命中行
行集、排序、分页与其余字段值均不变

2. 团期合并看板 `GET /v3/admin/order/group-batch/board`

VO: GroupBatchBoardItemRespVO

使用场景

按产品维度展示全部班期（含未建团班期）的合并看板。

入参

字段	位置	类型	必填	约束	说明
`productId`	Query	Long	✅	字符串传参	产品 ID
`scope`	Query	String	❌	缺省 `ALL`	范围筛选

出参 `Result<List<GroupBatchBoardItemRespVO>>`

字段	类型	说明
`batchName`	String	已去除前后空白
`remainRooms` / `remainParticipants`	Integer	不限时返 null，口径同接口 1
`enrolledRooms`	Integer	未建团行改取产品侧 `occupiedRooms`（含线下占位），与分页及产品侧同源；命中行与孤儿行仍为订单侧计数
`enrolledPeople`	Integer	未建团行改取产品侧 `enrolledCount`，同上

请求示例

GET /v3/admin/order/group-batch/board?productId=2044306857534636034

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    {
      "productBatchId": "2045498872326717443",
      "groupBatchId": null,
      "batchName": "冻干粉发短信给",
      "maxRooms": 11,
      "enrolledRooms": 9,
      "remainRooms": 2
    }
  ]
}

空数据 / 降级响应

产品下无班期时返回空数组。

错误响应

产品域不可用：

{
  "code": 589515,
  "message": "拉取产品信息失败",
  "success": false,
  "data": null
}

业务边界

只读接口
未建团行的已用量含线下占位，与产品侧 schedule/list 剩余库存一致
命中行的权威源仍是订单侧计数器，不受产品侧占位影响

3. 团期详情 `GET /v3/admin/order/group-batch/:groupBatchId`

VO: GroupBatchDetailRespVO

使用场景

团期详情页头部信息。

入参

字段	位置	类型	必填	约束	说明
`groupBatchId`	Path	Long	✅	—	团期主订单 ID（不是 productBatchId）

出参 `Result<GroupBatchDetailRespVO>`

字段	类型	说明
`batchName`	String	快照值，已去除前后空白
`remainRooms` / `remainParticipants`	Integer	不限时返 null，口径同接口 1

请求示例

GET /v3/admin/order/group-batch/2096779382436651009

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "batchName": "#7196复验班期",
    "maxRooms": 9,
    "remainRooms": 9,
    "maxParticipants": 0,
    "remainParticipants": null
  }
}

空数据 / 降级响应

无空数据形态；团期不存在返 589500。

错误响应

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

业务边界

只读接口
容量读订单侧快照，产品侧改容量需等下次该班期下单刷新才反映

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

remainRooms / remainParticipants 为 null 一律解释为「不限」，不要按 === 0 或 != null 判满员；判满员应看 maxXxx > 0 && remainXxx === 0。
batchName 已由服务端去空格，前端不必再 trim；null 仍为 null（未转空串）。
board 与分页的剩余数现已同源，两处显示不一致即为缺陷，可直接报。
命中行与未建团行的容量来源不同（订单侧快照 vs 产品侧实时），验证时不要混用样本。

五、数据库行为

三个接口均为只读，不产生任何写入。本次无表变更、无 Flyway、无 H2 schema 变更，不回填存量数据。

产品侧 group_tour_batch.batch_name 的存量脏值未回填，由读端 trim 兜住。

六、边界行为

容量为 null 或 0 → remain 返 null
容量大于 0 且已用超额 → remain 返 0（不返负数）
batchName 为 null → 保持 null
batchName 为纯空白 → 转空串
未建团行含线下占位 → 已用量计入
无权限 → 589507；产品域不可用 → 589515；团期不存在 → 589500

六.5、枚举 / 数据字典

本次无新增枚举。

六.6、修改前后对比

项	变更前	变更后
`batchName`	原样透出，可带前后空格	trim 后输出，null 仍 null
容量为 0 时 `remainRooms`	返 `0`（前端显示「剩余 0」误判满员）	返 null（不限）
容量为 0 时 `remainParticipants`	命中行返 `0`、未建团行返 `null`（两路打架）	三类行统一返 null
board 未建团行 `enrolledRooms`	订单侧计数，不含线下占位	产品侧 `occupiedRooms`，含线下占位
board 与分页剩余数	同班期可能不同（实测 8 vs 5）	一致
路径 / 入参 / 响应结构	—	均未变

六.7、影响评估

维度	评估
兼容性	结构零变化，仅三个字段取值修正；前端无需改码
前端	行标题与「剩余」列显示自动改善；若曾用 `remainXxx === 0` 判满员，不限行不再误判
数据	无 DDL、无迁移、无回填；纯读端派生
性能	无额外查询，未建团行改用入参里已有的产品侧字段，零新增 IO
回滚	还原 Converter 即可，无数据侧残留
风险	低。改动集中在单个静态 Converter，13 例单测 + 6 组网关用例覆盖

七、不影响范围

零影响：三个接口的路径、入参、响应结构、行集、排序、分页
零影响：导出 CSV（GB-ADM-008，读订单快照）
零影响：建团与刷新时的快照写入路径
零影响：product-v2、normalizeRemainingSlots、Feign 契约的 remainingSlots MAX_VALUE 语义
零影响：GroupBatchMergedRowsService（含 matchesKeyword，用 contains，带空格不影响搜索）

八、测试环境已验证

✅ 2026-09-07 于测试环境网关实测，真实鉴权（管理端 admin），部署本单特性分支后验收再合入 dev-v3。

#	用例	结果
AC-1	分页 `batchName` 无前后空白	✅ 8 行全通过；目标脏值行 `2052935476557328386` → `"没，那你"`
AC-2	容量 0/null 的行 remain 均为 null	✅ 违例 0（其中容量 0/null 的行 1 行构成有效样本）
AC-4	board 同样成立	✅ 8 行，带空白 0、违例 0
AC-4b	board 与分页库存同源	✅ 8 行 `remainRooms` 全部一致。样本：未建团行 `2045498872326717443` 已用 9 / 剩 2（含线下占位），改前 board 会回 `0/11`
AC-5	详情端点	✅ `batchName` 无空白；同一行 `maxRooms=9→remainRooms=9`（有限容量正常算）、`maxParticipants=0→remainParticipants=null`（不限）
AC-6	缺省 productId 老路径回归	✅ 22 行，容量 0/null 的 21 行 remain 均为 null，batchName 无空白

本地单测：GroupBatchConverterTest 新增 13 例（trim 四组、max=0 三组、未建团行含线下占位取 occupiedRooms、命中行仍用订单侧计数）；全量 8728 例 0 failures（余 7 个 error 为 Testcontainers 依赖 Docker，纯 dev-v3 同样失败）。

九、相关历史 PR

#7256 本次变更
前序：#7188（batchLabel 与保存路径 trim）、#7189（合并基底引入，暴露两路 remain 不一致）

十、相关文档

团期需求文档：docs/group/（dev-v3 分支）

关联 / 联系人

Issue: #7245 ｜ PR: #7256（合并提交 732889527）
服务: hl-order-service-v3
后端: jw ｜前端: 无需改码，仅需知悉「null = 不限」

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

团期看板: 三处响应值口径修正（结构不变）

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

1. 团期看板分页 GET /v3/admin/order/group-batch

使用场景

入参

出参 Result<PageResult<GroupBatchPageItemRespVO>>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 团期合并看板 GET /v3/admin/order/group-batch/board

使用场景

入参

出参 Result<List<GroupBatchBoardItemRespVO>>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 团期详情 GET /v3/admin/order/group-batch/:groupBatchId

使用场景

入参

出参 Result<GroupBatchDetailRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.5、枚举 / 数据字典

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

九、相关历史 PR

十、相关文档

关联 / 联系人

13 KiB

原始文件 Blame 文件历史

1. 团期看板分页 `GET /v3/admin/order/group-batch`

出参 `Result<PageResult<GroupBatchPageItemRespVO>>`

2. 团期合并看板 `GET /v3/admin/order/group-batch/board`

出参 `Result<List<GroupBatchBoardItemRespVO>>`

3. 团期详情 `GET /v3/admin/order/group-batch/:groupBatchId`

出参 `Result<GroupBatchDetailRespVO>`