diff --git a/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md b/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md index 9a3ad4af..ad71b764 100644 --- a/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/01_6905_团期看板-4-接口对齐补全-GB-ADM-000-001-002-003-修改接口-管理后台.md @@ -42,7 +42,7 @@ base: "dev-v3" 团期看板已实现 4 个查询接口（GB-ADM-000/001/002/003，见 #6902 共享件），本单按验收清单补齐全量字段、真实来源取值、批量聚合与筛选参数，消除 N+1。依赖 #6902（已合并 dev-v3）。 -## 变更接口清单 +## 二、变更接口清单 | # | 接口 | 方法 | 路径 | 变更类型 | 说明 | |---|------|------|------|----------|------| @@ -53,9 +53,13 @@ base: "dev-v3" ## 三、接口详情 -### 1. 产品团期看板 `GET /v3/admin/order/group-batch/products`（GB-ADM-000） +### 1. 产品团期看板 `GET /v3/admin/order/group-batch/products` -**使用场景**: 管理后台看板"产品列表"页：按产品展示其团期批量数。 +**VO**: `GroupBatchProductItemRespVO` + +#### 使用场景 + +管理后台看板"产品列表"页：按产品展示其团期批量数。 #### 入参 @@ -73,7 +77,9 @@ base: "dev-v3" #### 请求示例 +```http GET /v3/admin/order/group-batch/products?productType=&keyword= +``` #### 响应示例 @@ -112,9 +118,13 @@ GET /v3/admin/order/group-batch/products?productType=&keyword= - 未传筛选 = 不过滤，等价旧行为；regionText 为 null 时不阻断列表。 -### 2. 团期分页列表 `GET /v3/admin/order/group-batch`（GB-ADM-001） +### 2. 团期分页列表 `GET /v3/admin/order/group-batch` -**使用场景**: 管理后台看板"团期列表"页：分页 + 筛选（阶段桶/月份/关键词）。 +**VO**: `GroupBatchPageItemRespVO` + +#### 使用场景 + +管理后台看板"团期列表"页：分页 + 筛选（阶段桶/月份/关键词）。 #### 入参（新增，均可选） @@ -135,7 +145,9 @@ GET /v3/admin/order/group-batch/products?productType=&keyword= #### 请求示例 +```http GET /v3/admin/order/group-batch?pageNo=1&pageSize=5&opsStage=FORMED&month=2026-09&keyword=x +``` #### 响应示例 @@ -180,15 +192,19 @@ GET /v3/admin/order/group-batch?pageNo=1&pageSize=5&opsStage=FORMED&month=2026-0 - opsStage 非法/未知 = 不过滤（保守向后兼容）；month 格式非法 → 业务 400。 -### 3. 团期详情 `GET /v3/admin/order/group-batch/`（GB-ADM-002） +### 3. 团期详情 `GET /v3/admin/order/group-batch/` -**使用场景**: 看板点击团期看详情：实时金额 + 主报道人。 +**VO**: `GroupBatchDetailRespVO` + +#### 使用场景 + +看板点击团期看详情：实时金额 + 主报道人。 #### 入参 -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| groupBatchId | Path | Long | ✅ | 团期 ID（路径参数） | +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | - | 团期 ID（路径参数） | #### 出参 `Result` @@ -202,7 +218,9 @@ GET /v3/admin/order/group-batch?pageNo=1&pageSize=5&opsStage=FORMED&month=2026-0 #### 请求示例 +```http GET /v3/admin/order/group-batch/ +``` #### 响应示例 @@ -240,17 +258,21 @@ GET /v3/admin/order/group-batch/ - PRIMARY 报道人未配置时两 reporter 字段为 null，不降级不报错。 -### 4. 团期订单列表 `GET /v3/admin/order/group-batch//orders`（GB-ADM-003） +### 4. 团期订单列表 `GET /v3/admin/order/group-batch//orders` -**使用场景**: 看板展开订单列表：成本/tier/人数/房车需求/游客（含旅行内生日、无证件号）。 +**VO**: `GroupBatchOrderItemRespVO` + +#### 使用场景 + +看板展开订单列表：成本/tier/人数/房车需求/游客（含旅行内生日、无证件号）。 #### 入参（新增，均可选） -| 字段 | 位置 | 类型 | 必填 | 说明 | -|------|------|------|------|------| -| includeTravelers | Query | Boolean | 否 | 是否加载游客数组（不传=不加载，零开销） | -| includeNeeds | Query | Boolean | 否 | 是否加载房车需求做派生聚合 | -| includeCancelled | Query | Boolean | 否 | 是否包含已取消子订单 | +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| includeTravelers | Query | Boolean | 否 | - | 是否加载游客数组（不传=不加载，零开销） | +| includeNeeds | Query | Boolean | 否 | - | 是否加载房车需求做派生聚合 | +| includeCancelled | Query | Boolean | 否 | - | 是否包含已取消子订单 | #### 出参 `Result>` @@ -269,7 +291,9 @@ GET /v3/admin/order/group-batch/ #### 请求示例 +```http GET /v3/admin/order/group-batch//orders?includeTravelers=true&includeNeeds=true&includeCancelled=true +``` #### 响应示例 @@ -381,7 +405,7 @@ GET /v3/admin/order/group-batch//orders?includeTravelers=true&incl - 数据库表结构（零迁移） - #6902/#6903/#6904 已合并接口（本单未改其文件，仅顺带合并 dev-v3 时解决 GroupBatchMapper 尾部冲突取并集） -## 验证证据 +## 八、测试环境已验证 网关: `https://api.test.1814.love:9443`（`/v3/admin/**` → hl-order-service-v3，dev-v3 @ 47aaff0be，双实例 8086/8186 UP，BUILD SUCCESS 24.6s）