文件
hl-api-changelog/changelogs-v2/2026-09/06_7188_团期看板列表详情透出第N期batchLabel-修改接口-管理后台.md
T
Mimingguang d2ed4973f7
changelog-filename-gate / validate (push) Failing after 2s
chore(changelog): 回写批次A(#7188/#7189/#7190/#7250)与 #7291 前端交付验证
五条均 frontend_status verified、owner mmg、verified_at 2026-09-08;批次A 四项 frontend_ref=2eb27845,#7291 frontend_ref=41f0bacc(均 hl-admin v2.1 可达)。
2026-09-08 08:02:04 +08:00

459 行
19 KiB
Markdown
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的,可以安全地忽略该警告。 使用 Escape 按钮显示他们。
---
schema: "hl-changelog/v2"
ticket: "7188"
title: "团期看板/列表/详情透出「第N期」班期序号 batchLabel"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "2eb27845"
target_release: ""
verified_at: "2026-09-08"
updated_at: "2026-09-08"
base: "dev-v3"
status_note: "前端已交付并验证(commit 2eb27845, 汇总工单项1):PeriodRow 行标题/BatchHero 详情头/detail toolbar 三处 batchLabel 数字字符串纯拼接为「第{batchLabel}期 {名称}」,null 兜底只显名称,禁算术/排序;新增 spec 锁三处拼接与 null 兜底。"
---
# 团期模块:看板 / 列表 / 详情透出「第N期」班期序号
## ⚠️ 关键变化
- 三个团期接口新增 / 修正字段 **`batchLabel`**(String,班期序号,如 `"7"`):product 侧按同产品全部班期**出发日期升序位置 = 下标 + 1** 实时重算(不信存储列,删班期后自愈;同日期同排序值按 batchId 兜底),经内部接口透传到 order-v3。
- **前端行标题改为「第{batchLabel}期 {batchName}」**(hl-ui `src/views/order-v2/batch/components/PeriodRow.vue:164-171` `title` computed 目前只显 `batchName`),`batchLabel` 为空时退回只显 `batchName`——存量团期在下一次该班期下单前分页/详情里是 null,必须兜底。
- 班期名口径:product 保存与 order 快照两侧 **trim**;新增/编辑班期名为空白 → 回退班期编号 `batchNo`;编辑不传 `batchName` → 保留旧名。现场「 没,那你」(前导空格)这类脏名下单后自愈。
- 分页项(GB-ADM-001)本单取快照值;#7189 合入后分页改以产品全班期为基底、`batchLabel` 取 product 实时值,**字段名不变**。
---
## 一、背景
### 现象
wx 2026-09-06 看测试服「团期订单」看板:行标题显示班期名「没,那你」,期望「第7期 没,那你」(该班期是产品「冻干粉发短信给」按出发日的第 7 期)。序号只存在于 product 管理端班期列表,Feign 契约与团期三个响应 VO 都没有,`order_group_batch.batch_label` 列从未被写入。
### 调用链
1. hl-ui `src/stores/orderV2Batch.js:93-97` `getGroupBatchPage()` → `GET /v3/admin/order/group-batch`(GB-ADM-001)→ `records[].batchLabel`(快照)
2. 看板合并层 `GET /v3/admin/order/group-batch/board` → order-v3 Feign `GET /internal/product/group/{productId}/detail` → product `GroupTourBatchService.getBatchCalendarByProductId` 逐项 `batchLabel = 位置 + 1` → 命中/未建团行实时值、孤儿行快照
3. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`(GB-ADM-002)→ `batchLabel` 快照
4. 快照写入:GROUP 创单建团时 `GroupBatchService.buildGroupBatchDO` 从 `GET /internal/product/batch/{batchId}/info` 的 `batchLabel` 写 `batch_label`;此后每次该班期下单 `refreshSnapshot` 同步刷新序号 / 班期名 / 产品名 / 出发日 / 返团日 / 报名截止日六列
### 地面真相(测试服 dev-v3 a5eacefd,2026-09-06 21:2x,产品 2044306857534636034,班期 2026-10-01 productBatchId=2052935476557328386,团期 2096412454643802114)
| 接口 | 结果 |
|---|---|
| board | 7 行按出发日升序 `batchLabel` = "1"(06-04) "2"(07-03) "3"(07-10) "4"(07-17) "5"(07-24) "6"(07-31) "7"(10-01);06-04 期存储列是 "6" 却回 "1",10-01 期回 "7" ✓ 按位置实时重算 |
| 分页 / 详情(刷新前) | `batchLabel` 字段存在、值 null(存量团期) |
| 分页 / 详情(在该班期新下一单后,测完已取消) | 详情 `batchLabel="7"`、分页项 `batchLabel="7"`、`batchName="没,那你"`(前导空格已 trim) |
---
## 二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 团期看板分页(GB-ADM-001) | GET | `/v3/admin/order/group-batch` | 响应新增字段 | `records[].batchLabel`(快照;存量团期下单前为 null) |
| 2 | 团期看板合并层列表 | GET | `/v3/admin/order/group-batch/board` | 响应新增字段 | 每项 `batchLabel`:命中/未建团行取 product 实时值,孤儿行取快照 |
| 3 | 团期详情(GB-ADM-002) | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 响应字段语义修正 | 既有字段 `batchLabel` 由恒 null 改为班期序号快照 |
---
## 三、接口详情
### 1. 团期看板分页 `GET /v3/admin/order/group-batch`
**VO**: `GroupBatchListReqVO → Result<PageResult<GroupBatchPageItemRespVO>>`
#### 使用场景
团期看板列表;行标题用 `batchLabel` + `batchName` 拼「第N期 名称」。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productId | query | Long(字符串) | 否 | 雪花 ID | 按产品筛选 |
| opsStage | query | String | 否 | RECRUIT / FORMED / PENDING_TRIP / TRAVELLING / TRIP_FINISHED / AUDITING / CHECKED / DISBANDED | 桶筛选(不变) |
| month | query | String | 否 | yyyy-MM | 出发月份 |
| keyword | query | String | 否 | 已转义 | 班期编号 / 名称模糊 |
| batchStatus | query | String | 否 | 团期状态码 | 可选 |
| deadlineFrom / deadlineTo | query | String | 否 | yyyy-MM-dd | 报名截止日区间 |
| pageNo | query | Integer | 否 | 默认 1 | 页码 |
| pageSize | query | Integer | 否 | 默认 20,最大 100 | 每页条数 |
#### 出参 `Result<PageResult<GroupBatchPageItemRespVO>>`
| 字段 | 类型 | 说明 |
|------|------|------|
| data.records[] | Array | 团期行(分页容器 `records / total / page / pageSize`) |
| data.records[].batchLabel | String | **新增**。班期序号快照(`order_group_batch.batch_label`):建团写入、每次该班期下单刷新;存量团期在下一次下单前为 null;#7189 起改取 product 实时值 |
| data.records[].batchName | String | 班期名(快照,下单刷新时已 trim) |
| data.records[].batchNo | String | 班期编号 |
| 其余字段 | — | 不变(groupBatchId / productBatchId / productId / productName / batchStatus / batchStatusName / minGroupPeople / maxRooms / maxParticipants / enrolledPeople / enrolledRooms / remainRooms / remainParticipants / orderCount / enrollDeadline / departDate / endDate / receivableAmount / receivedAmount / chips) |
#### 请求示例
```http
GET /v3/admin/order/group-batch?productId=2044306857534636034&pageNo=1&pageSize=50 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <token>
```
#### 响应示例
在该班期下单刷新快照后实测(2026-09-06 21:2x,非相关字段略):
```json
{
"code": 200,
"message": "成功",
"data": {
"records": [
{
"groupBatchId": "2096412454643802114",
"productBatchId": "2052935476557328386",
"productId": "2044306857534636034",
"batchNo": "Q202610012052935476548939777",
"batchName": "没,那你",
"batchLabel": "7",
"batchStatus": "RESOURCE_PREPARING",
"batchStatusName": "资源准备中",
"departDate": "2026-10-01",
"endDate": "2026-10-03"
}
],
"total": 1,
"page": 1,
"pageSize": 50
},
"success": true
}
```
#### 空数据 / 降级响应
存量团期在下一次该班期下单前 `batchLabel` 为 null(不是缺字段),前端退回只显 `batchName`;无命中团期时 `records` 为空数组。
```json
{
"code": 200,
"message": "成功",
"data": {
"records": [
{ "groupBatchId": "2096412454643802114", "batchName": "没,那你", "batchLabel": null }
],
"total": 1,
"page": 1,
"pageSize": 50
},
"success": true
}
```
#### 错误响应
```json
{
"code": 589507,
"message": "无操作权限(非团期管理员 / 非本定制师名下)",
"data": null,
"success": false
}
```
HTTP 始终 200,按 `code` 判断。
#### 业务边界
- 权限 `group-batch:view`
- `batchLabel` 是数字字符串(`"7"`),后端不拼「第N期」文案,前端拼
- 序号会随 product 侧增删班期漂移,快照只在下单时刷新;需要绝对实时以 board / #7189 后的分页为准
### 2. 团期看板合并层列表 `GET /v3/admin/order/group-batch/board`
**VO**: `Result<List<GroupBatchBoardItemRespVO>>`(查询参数 productId,无请求 VO)
#### 使用场景
以产品全部班期为基底的看板(命中 / 未建团 / 孤儿三类行);hl-ui 当前未调用,#7189 后分页也走同一合并基底。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productId | query | Long(字符串) | 是 | 雪花 ID | 产品 ID |
#### 出参 `Result<List<GroupBatchBoardItemRespVO>>`
| 字段 | 类型 | 说明 |
|------|------|------|
| data[].batchLabel | String | **新增**。命中行 / 未建团行 = product 实时序号;孤儿行(product 已删该班期)= 快照,可能 null |
| data[].productBatchId / productId / batchNo / batchName | String | 不变 |
| data[].departureDate / endDate / enrollmentDeadline | String(yyyy-MM-dd) | 不变(product 实时) |
| data[].groupBatchId | String(Long) | 未建团行为 null(不变) |
| 其余字段 | — | 不变(maxRooms / maxParticipants / enrolledRooms / enrolledPeople / remainRooms / remainParticipants / batchStatus / batchStatusLabel / hotelReady / vehicleReady / guideReady / photographerReady / needsGuide / needsPhotographer / orderCount / productBatchRemoved / contractSignedCount / insuranceInsuredCount) |
#### 请求示例
```http
GET /v3/admin/order/group-batch/board?productId=2044306857534636034 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <token>
```
#### 响应示例
实测(2026-09-06 21:2x,只列序号相关字段,共 7 行):
```json
{
"code": 200,
"message": "成功",
"data": [
{ "productBatchId": "2045498872326717442", "departureDate": "2026-06-04", "batchName": "fadege", "batchLabel": "1", "groupBatchId": null },
{ "productBatchId": "2045401225930690562", "departureDate": "2026-07-03", "batchLabel": "2", "groupBatchId": null },
{ "productBatchId": "2045401225960050689", "departureDate": "2026-07-10", "batchLabel": "3", "groupBatchId": null },
{ "productBatchId": "2045401225964244993", "departureDate": "2026-07-17", "batchLabel": "4", "groupBatchId": null },
{ "productBatchId": "2045401225972633601", "departureDate": "2026-07-24", "batchLabel": "5", "groupBatchId": null },
{ "productBatchId": "2045401225976827906", "departureDate": "2026-07-31", "batchLabel": "6", "groupBatchId": null },
{ "productBatchId": "2052935476557328386", "departureDate": "2026-10-01", "batchName": " 没,那你", "batchLabel": "7", "groupBatchId": "2096412454643802114" }
],
"success": true
}
```
#### 空数据 / 降级响应
产品无班期时 `data` 为空数组;孤儿行 `batchLabel` 可能为 null。
```json
{
"code": 200,
"message": "成功",
"data": [],
"success": true
}
```
#### 错误响应
```json
{
"code": 589515,
"message": "获取团期产品列表失败,请稍后重试",
"data": null,
"success": false
}
```
另:`589507` 无操作权限。
#### 业务边界
- 序号按 product 当前全部未删班期的出发日升序位置计算(同日期按 sortOrder、再按 batchId);软删的班期不占位
- 未建团行的 `batchName` 取 product 侧当前值(可能未 trim,如示例第 7 行前导空格),命中行分页/详情取快照(已 trim)
### 3. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
**VO**: `Result<GroupBatchDetailRespVO>`(路径参数,无请求 VO)
#### 使用场景
团期详情页头部;`batchLabel` 语义修正为班期序号快照。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| groupBatchId | path | Long(字符串) | 是 | 团期主订单 ID | 不是 productBatchId |
#### 出参 `Result<GroupBatchDetailRespVO>`
| 字段 | 类型 | 说明 |
|------|------|------|
| data.batchLabel | String | **语义修正**:改前恒 null(列从未写入,文案「班期标签快照 example=主推」);改后 = 班期序号快照(建团写入、下单刷新),文案「班期序号(第N期)快照 example=7」 |
| data.batchName | String | 班期名快照(下单刷新时已 trim) |
| 其余字段 | — | 不变 |
#### 请求示例
```http
GET /v3/admin/order/group-batch/2096412454643802114 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <token>
```
#### 响应示例
刷新快照后实测(非相关字段略):
```json
{
"code": 200,
"message": "成功",
"data": {
"groupBatchId": "2096412454643802114",
"productBatchId": "2052935476557328386",
"batchNo": "Q202610012052935476548939777",
"batchName": "没,那你",
"batchLabel": "7",
"batchStatus": "RESOURCE_PREPARING",
"departDate": "2026-10-01",
"endDate": "2026-10-03"
},
"success": true
}
```
#### 空数据 / 降级响应
存量团期下单刷新前 `batchLabel` 为 null;前端退回只显 `batchName`。
```json
{
"code": 200,
"message": "成功",
"data": { "groupBatchId": "2096412454643802114", "batchName": "没,那你", "batchLabel": null },
"success": true
}
```
#### 错误响应
```json
{
"code": 589500,
"message": "团期不存在",
"data": null,
"success": false
}
```
#### 业务边界
- 同 GB-ADM-001:数字字符串、快照语义、null 兜底
---
## 四、契约约束与正确调用方式
> 三个接口均为只读 GET;本节写的是**前端消费 `batchLabel` 的规则**。
### ✅ 正确 / ❌ 错误 payload 对照
| 场景 | payload / 处理 |
|------|---------|
| ✅ 行标题 | `row.batchLabel ? \`第${row.batchLabel}期 ${row.batchName}\` : row.batchName` |
| ✅ 徽标 / 导出用序号 | 直接用 `batchLabel` 字符串,不要自己按行下标算 |
| ❌ 把 `batchLabel` 当数字做算术或排序键 | 它是字符串,且随 product 增删班期漂移;排序用 `departDate` |
| ❌ 不兜底 null | 存量团期分页/详情在下单刷新前为 null,会渲染成「第undefined期」 |
### 切换状态时的必要动作
无写接口。序号变化来自 product 侧班期增删/改期,看板刷新即可。
---
## 五、数据库行为
无表变更、无 Flyway。`order_group_batch.batch_label VARCHAR(64)` 列早已存在,本单开始写入:
| 时点 | 写入 |
|------|------|
| GROUP 首单建团 | `batch_label` = product `GET /internal/product/batch/{batchId}/info` 的 `batchLabel`;`batch_name` trim |
| 该班期每次下单 | `refreshSnapshot` 非 null 且变化才更新:`product_name / batch_name / batch_label / depart_date / end_date / enroll_deadline` |
product 侧 `group_tour_batch.batch_label` 存储列不再作为读源(脏值如 06-04 期存 "6" 不影响输出);`batch_name` 保存时 trim,空白回退 `batch_no`。
---
## 六、边界行为
- 未登录 → 网关 401;无权限 → `589507`
- 团期不存在 → `589500`;board 拉产品失败 → `589515`
- product 定位不到该班期(理论不会)→ `batchLabel` null 并记 WARN,不报错
- 产品下只有一期 → `batchLabel="1"`
- 下单时 product 回传日期串非法 → 刷新跳过该列并记 WARN,不影响下单
## 六.5、枚举 / 数据字典
无新增枚举;`batchLabel` 为自由数字字符串。
## 六.6、修改前后对比
### 字段级对比
| 字段 | 修改前 | 修改后 |
|------|--------|--------|
| GB-ADM-001 `records[].batchLabel` | 无 | 新增(快照) |
| board `data[].batchLabel` | 无 | 新增(实时 / 孤儿行快照) |
| GB-ADM-002 `data.batchLabel` | 存在但恒 null | 班期序号快照 |
| product `GET /internal/product/batch/{batchId}/info` `batchLabel` | 无 | 新增(内部接口,前端不直接调) |
### 行为级对比
| 场景 | 修改前 | 修改后 |
|------|--------|--------|
| 看板行标题 | 只有班期名 | 「第7期 没,那你」(前端拼) |
| 班期名带前后空格 | 原样落库、原样显示 | 保存 / 快照两侧 trim |
| 新增或编辑班期名为空白 | 新增回退 batchNo,编辑可能落 null | 两条路径都回退 `batchNo` |
| 编辑不传 batchName | 保留旧名 | 保留旧名(不变) |
## 六.7、影响评估
- 向后兼容:只加字段 / 修正语义,老前端不改不报错
- 前端是否必须同步上线:否;但不改则标题仍无序号
- 数据:无表变更;存量 `batch_label` 不回填,随下单自愈
---
## 七、不影响范围
- **仅影响**: 团期看板行标题、团期详情头部、board 合并层
- **零影响**:
- 创单 / 报价接口契约(`POST /v3/admin/order` 入参出参不变)
- product 管理端班期列表(已是同一序号口径)
- 芯片、桶、状态机
- 小程序
---
## 八、测试环境已验证
真实接口输出(测试服 api.test.1814.love,2026-09-06 21:2x,登录后切 ADMIN 角色):
```
GET /v3/admin/order/group-batch/board?productId=2044306857534636034 → 200, 7 行 batchLabel 1..7 按出发日升序,10-01 期 "7" ✓
GET /v3/admin/order/group-batch?productId=2044306857534636034&pageSize=50 → 200, 存量行 batchLabel 字段存在=null ✓
GET /v3/admin/order/group-batch/2096412454643802114 → 200, batchLabel 字段存在=null ✓
POST /v3/admin/order(该班期新下一单,测完取消) → 200, 触发 refreshSnapshot ✓
GET /v3/admin/order/group-batch/2096412454643802114 → batchLabel="7", batchName="没,那你" ✓
GET /v3/admin/order/group-batch?productId=2044306857534636034&pageSize=50 → 该行 batchLabel="7" ✓
```
验证产品: `productId=2044306857534636034`(冻干粉发短信给),班期 `productBatchId=2052935476557328386`(2026-10-01),团期 `groupBatchId=2096412454643802114`。单测:product `GroupTourBatchServiceTest` 3/0、`GroupTourBatchMapperTest` 2/0(ORDER BY 三键,变异验证)、`GroupBatchLabelResolverTest` 6/0、`InternalProductServiceTest` 7/0、`ProductPricingServiceTest` 97/0;order `GroupBatchServiceTest` 73/0、`GroupBatchConverterTest` 37/0、`BatchInfoVODeserializationTest` 4/0、ArchTest 41/0;合入后 dev-v3 HEAD 全量 product-v2 1550/0、order-v3 8726/0。部署:Deploy Panel 21:19-21:22 product-v2 与 order-v3 双实例滚动完成,分支 dev-v3。
---
## 十、相关文档
- 关联 Issue: [wx/HL#7188](https://git.1814.love:8443/wx/HL/issues/7188)
- 关联 PR: [wx/HL#7209](https://git.1814.love:8443/wx/HL/pulls/7209)
- 同现场: #7189(看板以产品全班期为基底 + 班期范围筛选,分页 batchLabel 改实时值)、#7190(「出行完毕」状态与八桶)、#7204(导/摄芯片零指派口径)
- 前端缺陷 changelog: `06_frontend_团期看板展开行子订单列表恒空-前端缺陷-管理后台.md`
## 关联 / 联系人
### 链接
- **Issue**: [#7188](https://git.1814.love:8443/wx/HL/issues/7188)
- **PR**: [#7209](https://git.1814.love:8443/wx/HL/pulls/7209)
- **Merge commit**: [a5eacefd](https://git.1814.love:8443/wx/HL/commit/a5eacefdb270b2f783db95afc790c9d0eb65a8da)
### 联系人
- **后端负责人**: @wx