From 06a86d488d0ec5de00054e6d0a29621c7960534f Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 1 Sep 2026 15:11:03 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=206905=20=E5=9B=A2=E6=9C=9F?= =?UTF-8?q?=E7=9C=8B=E6=9D=BF=204=20=E6=8E=A5=E5=8F=A3=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=E8=A1=A5=E5=85=A8-=E9=80=90=E6=8E=A5=E5=8F=A3=E8=A1=A5?= =?UTF-8?q?=E8=AF=B7=E6=B1=82/=E5=93=8D=E5=BA=94/=E9=94=99=E8=AF=AF?= =?UTF-8?q?=E7=A4=BA=E4=BE=8B=E5=B9=B6=E8=A7=84=E8=8C=83=E5=8C=96=E6=A8=A1?= =?UTF-8?q?=E6=9D=BF=E6=A0=87=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...补全-GB-ADM-000-001-002-003-修改接口-管理后台.md | 38 +++++++++++++++---- 1 file changed, 30 insertions(+), 8 deletions(-) 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 54a3fa12..4f7a9d59 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 @@ -64,7 +64,7 @@ base: "dev-v3" | productType | Query | String | 否 | - | 产品类型筛选；不传=不限（向后兼容） | | keyword | Query | String | 否 | - | 产品名关键词（原有行为不变） | -#### 出参（新增字段） +#### 出参 `Result` | 字段 | 类型 | 说明 | |------|------|------| @@ -95,11 +95,15 @@ GET /v3/admin/order/group-batch/products?productType=&keyword= } ``` -#### 降级/错误 +#### 空数据 / 降级响应 - 无数据 → 空数组，不报错。 - 未登录 → 401（网关拦截）。 +#### 业务边界 + +- 未传筛选 = 不过滤，等价旧行为；regionText 为 null 时不阻断列表。 + ### 2. 团期分页列表 `GET /v3/admin/order/group-batch`（GB-ADM-001） **使用场景**: 管理后台看板"团期列表"页：分页 + 筛选（阶段桶/月份/关键词）。 @@ -112,7 +116,7 @@ GET /v3/admin/order/group-batch/products?productType=&keyword= | month | Query | String | 否 | yyyy-MM | 按出发日期所在自然月区间过滤 | | keyword | Query | String | 否 | - | 匹配团期编号/名称，服务端 trim+转义 % _ \\（防通配符扩匹配） | -#### 出参（新增字段，分页项） +#### 出参 `Result>` | 字段 | 类型 | 说明 | |------|------|------| @@ -148,16 +152,26 @@ GET /v3/admin/order/group-batch?pageNo=1&pageSize=5&opsStage=FORMED&month=2026-0 } ``` -#### 降级/错误 +#### 空数据 / 降级响应 - 无匹配 → records 空数组 total=0。 - 排序保持 create_time DESC（向后兼容，未做排序变更）。 +#### 业务边界 + +- opsStage 非法/未知 = 不过滤（保守向后兼容）；month 格式非法 → 业务 400。 + ### 3. 团期详情 `GET /v3/admin/order/group-batch/`（GB-ADM-002） **使用场景**: 看板点击团期看详情：实时金额 + 主报道人。 -#### 出参（新增/变更字段） +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 团期 ID（路径参数） | + +#### 出参 `Result` | 字段 | 类型 | 说明 | |------|------|------| @@ -191,10 +205,14 @@ GET /v3/admin/order/group-batch/ } ``` -#### 降级/错误 +#### 空数据 / 降级响应 - 团期不存在 → 业务 404。 +#### 业务边界 + +- PRIMARY 报道人未配置时两 reporter 字段为 null，不降级不报错。 + ### 4. 团期订单列表 `GET /v3/admin/order/group-batch//orders`（GB-ADM-003） **使用场景**: 看板展开订单列表：成本/tier/人数/房车需求/游客（含旅行内生日、无证件号）。 @@ -207,7 +225,7 @@ GET /v3/admin/order/group-batch/ | includeNeeds | Query | Boolean | 否 | 是否加载房车需求做派生聚合 | | includeCancelled | Query | Boolean | 否 | 是否包含已取消子订单 | -#### 出参（新增/变更字段，每子订单） +#### 出参 `Result>` | 字段 | 类型 | 说明 | |------|------|------| @@ -246,11 +264,15 @@ GET /v3/admin/order/group-batch//orders?includeTravelers=true&incl } ``` -#### 降级/错误 +#### 空数据 / 降级响应 - 无子订单 → 空数组。 - 证件号/游客手机号永不返回（数据安全边界）。 +#### 业务边界 + +- include* 参数不传 = 不加载对应数据（零开销，向后兼容）。 + --- ## 四、契约约束与正确调用方式