wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
10b46812d23a51304c00ee1537254b4a07c7265c
hl-api-changelog/changelogs-v2/2026-09/06_7143_团期看板VO补productId-修改接口-管理后台.md
T
Mimingguang a107bc9f18
changelog-filename-gate / validate (push) Failing after 2s
详情
chore(changelog): 回写 #7135/#7142/#7143/#7158/前端缺陷条前端交付状态
2026-09-06 16:33:44 +08:00

574 行
20 KiB
Markdown
原始文件 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。
---
schema: "hl-changelog/v2"
ticket: "7143"
title: "团期看板分页项/详情/看板 VO 补 productId（供新增子订单深链预填产品）"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "5d0344ad"
target_release: ""
verified_at: "2026-09-06"
status_note: ""
updated_at: "2026-09-06"
base: "dev-v3"
---
# 团期模块：看板 VO 补 productId
三个团期看板读接口响应新增 `productId` 字段，供前端「新增子订单」深链到订单创建向导时预填产品和班期 ID，锁定出发日期。前端逻辑：**仅 GROUP 产品创单时才在 payload 中带 productBatchId**；非 GROUP 产品忽略 productBatchId。
## ⚠️ 关键变化
- 新增 `productId` 是产品主键，用于深链向导 `/order-v2/new?productId={productId}&productBatchId={productBatchId}&departureDate={date}` 的预填参数。
- 向导跳转后，**仅 GROUP 产品**应将 productBatchId 放入订单创建 POST payload；其他产品类型忽略该参数。
- 前端缺陷单已发，说明旧建单向导漏传 productBatchId，新版本补全（见关联链接）。
---
## 二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 团期分页列表 | GET | `/v3/admin/order/group-batch` | 响应新增字段 | data.list[] 各项新增 productId |
| 2 | 团期详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 响应新增字段 | data 新增 productId |
| 3 | 团期看板列表 | GET | `/v3/admin/order/group-batch/board?productId=` | 响应新增字段 | data[] 各项新增 productId |
---
## 三、接口详情
### 1. 团期分页列表 `GET /v3/admin/order/group-batch`
**VO**: `GroupBatchPageItemRespVO`（响应位置：`data.list[]`）
#### 使用场景
加载团期分页列表时，每一行包含产品 ID，前端点击「新增子订单」时取该行的 productId / productBatchId / departureDate 拼接深链，跳转到订单创建向导。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| `productId` | Query | String | 否 | 正整数 ID | 按产品筛选 |
| `batchStatus` | Query | String | 否 | 枚举值 | 按团期状态码筛选（RECRUITING/RESOURCE_PREPARING/...） |
| `deadlineFrom` | Query | String | 否 | yyyy-MM-dd | 报名截止日起 |
| `deadlineTo` | Query | String | 否 | yyyy-MM-dd | 报名截止日止 |
| `opsStage` | Query | String | 否 | 枚举值 | 按运营阶段筛选（RECRUIT/FORMED/PENDING_TRIP/TRAVELLING/AUDITING/CHECKED/DISBANDED） |
| `month` | Query | String | 否 | yyyy-MM | 按出发月份筛选 |
| `keyword` | Query | String | 否 | - | 班期编号/班期名称模糊关键词 |
| `pageNo` | Query | Integer | 是 | ≥1 | 页码，从 1 开始 |
| `pageSize` | Query | Integer | 是 | ≤100 | 每页条数，默认 20 |
#### 出参 `Result<Page<GroupBatchPageItemRespVO>>`
| 字段 | 类型 | 说明 |
|------|------|------|
| `data.list[].groupBatchId` | String | 团期聚合主键 |
| `data.list[].productBatchId` | String | product 侧班期 ID |
| `data.list[].productId` | String | **【新增】** 产品 ID，供深链预填 |
| `data.list[].productName` | String | 产品名称 |
| `data.list[].batchNo` | String | 班期编号 |
| `data.list[].batchName` | String | 班期名称 |
| `data.list[].batchStatus` | String | 团期状态码 |
| `data.list[].batchStatusName` | String | 状态中文名 |
| `data.list[].minGroupPeople` | Integer | 最低成团人数 |
| `data.list[].maxRooms` | Integer | 房间容量 |
| `data.list[].maxParticipants` | Integer | 人数容量 |
| `data.list[].enrolledPeople` | Integer | 已报名人数 |
| `data.list[].enrolledRooms` | Integer | 已用房间数 |
| `data.list[].remainRooms` | Integer | 剩余房间数 |
| `data.list[].remainParticipants` | Integer | 剩余人数 |
| `data.list[].orderCount` | Integer | 子订单数 |
| `data.list[].enrollDeadline` | String | 报名截止日 |
| `data.list[].departDate` | String | 出发日期 |
| `data.list[].endDate` | String | 结束日期 |
| `data.list[].receivableAmount` | String | 整团应收合计 |
| `data.list[].receivedAmount` | String | 整团已收合计 |
| `data.list[].chips` | Object | 六芯片整团聚合态（hotel/vehicle/guide/photo/contract/insurance，各为字符串状态：全部完成为 `DONE`，存在未完成项为待办态；完整取值见六芯片文档 GB-ADM-090~095） |
#### 请求示例
```http
GET /v3/admin/order/group-batch?pageNo=1&pageSize=20
Authorization: Bearer <token>
```
无请求体。
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"total": 5,
"list": [
{
"groupBatchId": "2096412454643802114",
"productBatchId": "2052935476557328386",
"productId": "2044306857534636034",
"productName": "冻干粉发短信给",
"batchNo": "Q202610012052935476548939777",
"batchName": "10月1日长白山亲子团",
"batchStatus": "RECRUITING",
"batchStatusName": "招募中",
"minGroupPeople": 6,
"maxRooms": 4,
"maxParticipants": 10,
"enrolledPeople": 4,
"enrolledRooms": 2,
"remainRooms": 2,
"remainParticipants": 6,
"orderCount": 2,
"enrollDeadline": "2026-09-25",
"departDate": "2026-10-01",
"endDate": "2026-10-03",
"receivableAmount": "48000.00",
"receivedAmount": "36000.00",
"chips": {
"hotel": "DONE",
"vehicle": "DONE",
"guide": "DONE",
"photo": "DONE",
"contract": "DONE",
"insurance": "DONE"
}
}
]
}
}
```
#### 空数据 / 降级响应
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"total": 0,
"list": []
}
}
```
#### 错误响应
```json
{
"code": 589507,
"message": "无操作权限",
"success": false,
"data": null
}
```
#### 业务边界
- 沿用团期列表权限校验（团期管理员/运营/定制师等）；无权返回 589507。
- `productId` 与其他字段同时生效，始终非空（命中行/未命中行/孤儿行均返回）。
- 分页参数超界时返回空列表。
- 业务失败仍为 HTTP 200，需检查 code。
---
### 2. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
**VO**: `GroupBatchDetailRespVO`（响应位置：`data`）
#### 使用场景
打开团期详情页时，读取产品 ID，供「新增子订单」按钮拼接深链，跳转订单创建向导并预填产品及班期。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| `groupBatchId` | Path | String | 是 | 正整数 ID | 团期主键 |
#### 出参 `Result<GroupBatchDetailRespVO>`
| 字段 | 类型 | 说明 |
|------|------|------|
| `data.groupBatchId` | String | 团期聚合主键 |
| `data.productBatchId` | String | product 侧班期 ID |
| `data.productId` | String | **【新增】** 产品 ID，供深链预填 |
| `data.productName` | String | 产品名称 |
| `data.batchNo` | String | 班期编号 |
| `data.batchName` | String | 班期名称 |
| `data.batchLabel` | String/null | 班期标签快照 |
| `data.batchStatus` | String | 团期状态码 |
| `data.batchStatusName` | String | 状态中文名 |
| `data.minGroupPeople` | Integer | 最低成团人数 |
| `data.maxRooms` | Integer | 房间容量 |
| `data.maxParticipants` | Integer | 人数容量 |
| `data.enrolledPeople` | Integer | 已报名人数 |
| `data.enrolledRooms` | Integer | 已用房间数 |
| `data.remainRooms` | Integer | 剩余房间数 |
| `data.remainParticipants` | Integer | 剩余人数 |
| `data.hotelReady` | Boolean | 配房完成标志 |
| `data.vehicleReady` | Boolean | 配车完成标志 |
| `data.guideReady` | Boolean | 导游完成标志 |
| `data.photographerReady` | Boolean | 摄影完成标志 |
| `data.materialConfirmed` | Boolean | 物资确认标志 |
| `data.requirementConfirmed` | Boolean | 需求整体确认标志 |
| `data.departDate` | String | 出发日期 |
| `data.endDate` | String | 结束日期 |
| `data.enrollDeadline` | String | 报名截止日 |
| `data.totalReceivable` | String | 整团应收合计 |
| `data.totalReceived` | String | 整团已收合计 |
| `data.remark` | String/null | 备注 |
#### 请求示例
```http
GET /v3/admin/order/group-batch/2096412454643802114
Authorization: Bearer <token>
```
无请求体。
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"groupBatchId": "2096412454643802114",
"productBatchId": "2052935476557328386",
"productId": "2044306857534636034",
"productName": "冻干粉发短信给",
"batchNo": "Q202610012052935476548939777",
"batchName": "10月1日长白山亲子团",
"batchLabel": null,
"batchStatus": "RESOURCE_PREPARING",
"batchStatusName": "资源准备中",
"minGroupPeople": 6,
"maxRooms": 4,
"maxParticipants": 10,
"enrolledPeople": 10,
"enrolledRooms": 4,
"remainRooms": 0,
"remainParticipants": 0,
"hotelReady": false,
"vehicleReady": false,
"guideReady": false,
"photographerReady": false,
"materialConfirmed": false,
"requirementConfirmed": false,
"departDate": "2026-10-01",
"endDate": "2026-10-03",
"enrollDeadline": "2026-09-25",
"totalReceivable": "48000.00",
"totalReceived": "36000.00",
"remark": null
}
}
```
#### 空数据 / 降级响应
详情接口不存在空数据响应。
#### 错误响应
```json
{
"code": 589501,
"message": "团期不存在",
"success": false,
"data": null
}
```
业务失败错误码沿用 GroupBatchErrorCode（权限/不存在等）。
#### 业务边界
- 沿用团期详情权限校验；无权返回 589507。
- `productId` 与其他字段同时返回，始终非空。
- 团期不存在返回业务码 589501（HTTP 200）。
---
### 3. 团期看板列表 `GET /v3/admin/order/group-batch/board?productId=`
**VO**: `GroupBatchBoardItemRespVO`（响应位置：`data[]`）
#### 使用场景
打开团期看板时，按产品维度加载该产品下的所有班期（产品侧班期为基底，左连运营侧团期数据），每一行携带 productId，供「新增子订单」深链按行数据拼接预填参数。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| `productId` | Query | String | 是 | 正整数 ID | 按产品筛选（必填；缺参返回 400） |
#### 出参 `Result<List<GroupBatchBoardItemRespVO>>`
| 字段 | 类型 | 说明 |
|------|------|------|
| `data[].productBatchId` | String | product 侧班期 ID |
| `data[].productId` | String | **【新增】** 产品 ID（= 请求入参；命中/未命中/孤儿行均非空） |
| `data[].batchNo` | String | 班期编号 |
| `data[].batchName` | String | 班期名称 |
| `data[].departureDate` | String | 出发日期 |
| `data[].endDate` | String | 结束日期 |
| `data[].enrollmentDeadline` | String | 报名截止日 |
| `data[].maxRooms` | Integer | 房间容量 |
| `data[].maxParticipants` | Integer | 人数容量 |
| `data[].enrolledRooms` | Integer | 已报名房数 |
| `data[].enrolledPeople` | Integer | 已报名人数 |
| `data[].remainRooms` | Integer | 剩余房间数 |
| `data[].remainParticipants` | Integer | 剩余人数 |
| `data[].batchStatus` | String | 团期状态码 |
| `data[].batchStatusLabel` | String | 状态中文名 |
| `data[].hotelReady` | Boolean | 配房完成标志 |
| `data[].vehicleReady` | Boolean | 配车完成标志 |
| `data[].guideReady` | Boolean | 导游完成标志 |
| `data[].photographerReady` | Boolean | 摄影完成标志 |
| `data[].needsGuide` | Boolean | 是否需领队 |
| `data[].needsPhotographer` | Boolean | 是否需摄影 |
| `data[].orderCount` | Integer | 活跃子订单数 |
| `data[].groupBatchId` | String/null | 团期聚合主键（未成团时为 null） |
| `data[].productBatchRemoved` | Boolean | 是否孤儿行（product 侧已删除该班期） |
| `data[].contractSignedCount` | Integer | 合同已签子订单数 |
| `data[].insuranceInsuredCount` | Integer | 保险已出子订单数 |
#### 请求示例
```http
GET /v3/admin/order/group-batch/board?productId=2044306857534636034
Authorization: Bearer <token>
```
无请求体。
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": [
{
"productBatchId": "2052935476557328386",
"productId": "2044306857534636034",
"batchNo": "Q202610012052935476548939777",
"batchName": "10月1日长白山亲子团",
"departureDate": "2026-10-01",
"endDate": "2026-10-03",
"enrollmentDeadline": "2026-09-25",
"maxRooms": 4,
"maxParticipants": 10,
"enrolledRooms": 2,
"enrolledPeople": 4,
"remainRooms": 2,
"remainParticipants": 6,
"batchStatus": "RECRUITING",
"batchStatusLabel": "招募中",
"hotelReady": false,
"vehicleReady": false,
"guideReady": false,
"photographerReady": false,
"needsGuide": true,
"needsPhotographer": false,
"orderCount": 2,
"groupBatchId": "2096412454643802114",
"productBatchRemoved": false,
"contractSignedCount": 1,
"insuranceInsuredCount": 1
},
{
"productBatchId": "2052935476557328387",
"productId": "2044306857534636034",
"batchNo": "Q202610022052935476548939778",
"batchName": "10月2日长白山亲子团",
"departureDate": "2026-10-02",
"endDate": "2026-10-04",
"enrollmentDeadline": "2026-09-26",
"maxRooms": 4,
"maxParticipants": 10,
"enrolledRooms": 0,
"enrolledPeople": 0,
"remainRooms": 4,
"remainParticipants": 10,
"batchStatus": "RECRUITING",
"batchStatusLabel": "招募中",
"hotelReady": false,
"vehicleReady": false,
"guideReady": false,
"photographerReady": false,
"needsGuide": true,
"needsPhotographer": false,
"orderCount": 0,
"groupBatchId": null,
"productBatchRemoved": false,
"contractSignedCount": 0,
"insuranceInsuredCount": 0
}
]
}
```
#### 空数据 / 降级响应
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": []
}
```
#### 错误响应
缺参 productId：
```json
{
"code": 400,
"message": "productId 参数缺失",
"success": false,
"data": null
}
```
---
#### 业务边界
- `productId` 必填，缺参返回 HTTP 200 + code 400；不要用 GET 参数默认值。
- 返回结构按产品侧班期为基底（左连团期数据）：
- **命中行**（班期有对应团期）：团期状态/容量/ready 取订单侧值；batchStatus ≠ RECRUITING
- **未命中行**（班期无团期）：batchStatus 固定 RECRUITING；groupBatchId = null；容量取产品侧 maxRooms/maxParticipants
- **孤儿行**（团期但班期已删）：productBatchRemoved = true；仅 orderCount > 0 时出现
- `productId` 在命中行、未命中行、孤儿行中均等于请求入参，始终非空。
- 表合并按 productBatchId 左连 order_group_batch；无团期记录时新增一行（未命中）。
---
## 四、契约约束与正确调用方式
| 场景 | 正确做法 |
|------|---------|
| 新增子订单深链 | 按行数据拼接 `/order-v2/new?productId={productId}&productBatchId={productBatchId}&departureDate={departureDate}` |
| 向导内 GROUP 产品创单 | 检查产品类型，仅 GROUP 类型在 POST payload 中带 productBatchId；其他类型忽略 |
| 非 GROUP 产品创单 | 忽略 productBatchId 参数，后端根据 productId 与 departureDate 自行逻辑 |
| 孤儿行处理 | 若 productBatchRemoved = true，需向用户提示"班期已下架，不可创建子订单"或禁用按钮 |
| 未成团行处理 | groupBatchId = null 时无团期记录；前端可选择隐藏"团期信息"列或显示"待成团" |
---
## 五、数据库行为
| 班期状态 | productBatchId | groupBatchId | batchStatus | 数据来源 |
|---------|----------------|-------------|------------|---------|
| 命中（有团期） | 产品侧 | 订单侧 | 订单侧 | order_group_batch 存在 |
| 未命中（无团期） | 产品侧 | null | RECRUITING | 无 order_group_batch 行 |
| 孤儿（班期删）| 产品侧 | 订单侧 | 订单侧 | order_group_batch 存在但班期无 |
新增 productId 字段在 productBatchId 后（响应顺序一致）。
---
## 六、边界行为
- 业务失败可能仍为 HTTP 200，必须同时检查 `code`、`success` 和 `message`。
- 看板接口 `productId` 缺参返回 400（HTTP 200）；不要依赖前端参数校验。
- 分页/列表接口分页参数超界时返回空列表（无 5XX）。
- `productId` 在所有三个接口的所有行中均非空，无特殊情况返回 null。
- Long 型 ID 在 JSON 字符串化后，前端若需数值运算应保持字符串存储。
---
## 六.6、修改前后对比
### 字段级对比
| 字段 | 改前 | 改后 |
|------|------|------|
| `productId`（分页项） | 无此字段 | 新增；产品 ID |
| `productId`（详情） | 无此字段 | 新增；产品 ID |
| `productId`（看板项） | 无此字段 | 新增；产品 ID |
### 行为级对比
| 行为 | 改前 | 改后 |
|------|------|------|
| 新增子订单跳转 | 无法从响应直接拼深链参数 | 新增 productId，与 productBatchId/departureDate 配合直接拼链 |
| 向导内产品预填 | 依赖约定俗成或外部 context | 直接从深链 query string 传入 |
| GROUP 产品识别 | 向导内自行判别 | 向导根据产品类型自动识别是否需 productBatchId |
---
## 六.7、影响评估
- **是否破坏向后兼容**: 否。新增字段对旧客户端透明。
- **前端是否必须同步上线**: 否（从旧口径讲）；但为完整支持团期看板「新增子订单」功能，前端应同步接入新增 productId 于深链拼接（仅一处改动）。
- **前端 workaround 清理点**:
- 新增子订单按钮处，改用响应中的 productId 拼深链，而非硬编码产品 ID
- 向导内创建 GROUP 订单时，检查产品类型再决定是否传 productBatchId（无需前端重构，只需补一个类型判断）
---
## 七、不影响范围
- **仅影响**: 管理后台团期看板的「新增子订单」功能入口
- **零影响**:
- 团期创建、编辑、审批、资源配置等写接口
- 团期与订单间的关联关系和业务流程
- 产品侧班期相关接口和定义
---
## 八、测试环境已验证
- **单测**: 79 条测试用例绿✓（新增 productId 相关的 UT 已覆盖命中/未命中/孤儿行三路径）
- **ArchTest**: 45 条架构测试绿✓
- **测试服网关实测**: 单测 + CR 通过；测试服网关实测见管理者补充
实测产品: `productId=2044306857534636034`（冻干粉发短信给），班期 `2026-10-01`（productBatchId=2052935476557328386），团期主键 `groupBatchId=2096412454643802114`，团期名 `batchName=10月1日长白山亲子团`。
---
## 九、相关历史 PR（功能演进）
| PR | Issue | 说明 | 是否仍有效 |
|----|-------|------|------------|
| #7135 | - | GROUP 产品创单校验与重整（定义 productBatchId 入参） | ✅ 有效 |
| #7142 | - | 订单详情/列表/创单响应透出判团字段（groupBatchId/productBatchId/groupOrder）| ✅ 有效 |
| **本 PR #7157** | **#7143** | **团期看板 VO 补 productId（配合深链预填）** | ✅ 最新 |
---
## 十、相关文档
- 关联 Issue: [wx/HL#7143](https://git.1814.love:8443/wx/HL/issues/7143)
- 关联 PR: [wx/HL#7157](https://git.1814.love:8443/wx/HL/pulls/7157)
- 相关工单: #7142（订单判团字段）、#7135（GROUP 产品规范）
- 前端缺陷: 新建订单向导漏传 productBatchId（另发前端 changelog）
## 关联 / 联系人
### 链接
- **Issue**: [#7143](https://git.1814.love:8443/wx/HL/issues/7143)
- **PR**: [#7157](https://git.1814.love:8443/wx/HL/pulls/7157)
- **Merge commit**: [ce2809c15](https://git.1814.love:8443/wx/HL/commit/ce2809c15)
### 联系人
- **后端负责人**: @wx
在新工单中引用 查看 Git Blame 复制永久链接