diff --git a/changelogs-v2/2026-09/07_7189_团期看板产品全班期基底与scope范围筛选-修改接口-管理后台.md b/changelogs-v2/2026-09/07_7189_团期看板产品全班期基底与scope范围筛选-修改接口-管理后台.md index 1132fb4e..5b08045d 100644 --- a/changelogs-v2/2026-09/07_7189_团期看板产品全班期基底与scope范围筛选-修改接口-管理后台.md +++ b/changelogs-v2/2026-09/07_7189_团期看板产品全班期基底与scope范围筛选-修改接口-管理后台.md @@ -49,7 +49,7 @@ wx 2026-09-06 看测试服「团期订单」看板：产品「冻干粉发短信 | 接口 | 结果 | |---|---| -| 分页 `scope=ALL` | 8 行出发日升序；10-01 行 `groupBatchId` 非空 `batchLabel="7"`；其余 7 行 `groupBatchId=null` `batchStatus=RECRUITING` `chips` 六项 TODO | +| 分页 `scope=ALL` | 8 行出发日升序；10-01 行 `groupBatchId` 非空 `batchLabel="7"`；其余 7 行 `groupBatchId=null` `batchStatus=RECRUITING` `chips` 六项 `TODO` | | 分页默认（=ONGOING） | 2 行（10-01、12-01）；`scope=FINISHED` 6 行 | | summary 默认 | `RECRUIT=1 FORMED=1 其余 0 total=2`；`scope=ALL` → `total=8 RECRUIT=7 FORMED=1` | | products | 该产品 `batchCount=8` | @@ -109,7 +109,7 @@ wx 2026-09-06 看测试服「团期订单」看板：产品「冻干粉发短信 | data.records[].departDate / endDate / enrollDeadline | String(yyyy-MM-dd) | 命中行 / 未建团行 product 实时；孤儿行快照 | | data.records[].maxRooms / enrolledRooms / remainRooms | Integer | 未建团行：`enrolledRooms` = product 占房数（含线下占位），`remainRooms` = maxRooms − 占房（不限房 null） | | data.records[].orderCount / receivableAmount / receivedAmount | Integer / String | 未建团行 0 / "0.00" / "0.00" | -| data.records[].chips | Object | hotel / vehicle / guide / photographer / insurance / contract 六项；**子订单为 0 的行六项固定 TODO（不再为 null）** | +| data.records[].chips | Object | hotel / vehicle / guide / photographer / insurance / contract 六项；**子订单为 0 的行六项固定 `TODO`（不再为 null）** | | 其余字段 | — | 不变 | #### 请求示例 @@ -321,7 +321,7 @@ Authorization: Bearer ### 3. 团期看板导出 `GET /v3/admin/order/group-batch/export` -**VO**: CSV 附件（查询参数 productId / scope / month / keyword / opsStage，无请求 VO） +**VO**: `无请求 VO（查询参数 productId / scope / month / keyword / opsStage） → CSV 文件流 text/csv` #### 使用场景 @@ -334,9 +334,13 @@ Authorization: Bearer | scope | query | String | 否 | ONGOING / FINISHED / ALL | **新增**。缺省规则同 GB-ADM-001；按 product 实时返团日过滤 | | productId / month / keyword / opsStage | query | — | 否 | 不变 | 不变 | -#### 出参 +#### 出参 `CSV 文件流` -CSV 字节流（BOM + 表头），**不含未建团行**（只导有团期的行）；行数 = 同 scope 下 GB-ADM-001 中 `groupBatchId` 非空的行数（例外：产品侧班期已删且 0 活跃单的残留团期会出现在导出、不出现在列表）。 +| 字段 | 类型 | 说明 | +|------|------|------| +| （响应体） | text/csv | BOM + 表头 `团期号,期号,日期,出团日,满团名额,已售,剩余,状态,子订单数,整团应收`，列与改前一致 | +| 行集 | — | **不含未建团行**（只导有团期的行）；行数 = 同 scope 下 GB-ADM-001 中 `groupBatchId` 非空的行数（例外：产品侧班期已删且 0 活跃单的残留团期会出现在导出、不出现在列表） | +| 日期列 | — | 行内「日期 / 出团日」仍是订单快照；`scope` 的未结束判定用 product 实时返团日（AC-14 实测：改期后行进入导出，日期列仍显快照） | #### 请求示例 @@ -348,7 +352,16 @@ Authorization: Bearer #### 响应示例 -实测：`scope=ALL` 表头 + 1 行（10-01 团期）；默认 ONGOING 1 行；`scope=FINISHED` 0 行。 +文件流（Content-Type: text/csv; Content-Disposition: attachment），JSON 仅示意： + +```json +{ + "code": 200, + "message": "文件流（text/csv），实际响应体为下方 CSV" +} +``` + +实测（2026-09-07）：`scope=ALL` 表头 + 1 行（10-01 团期）；默认 ONGOING 1 行；`scope=FINISHED` 0 行。 ```text 团期号,期号,日期,出团日,满团名额,已售,剩余,状态,子订单数,整团应收 @@ -357,11 +370,20 @@ Q202610012052935476548939777,没，那你,2026-10-01~2026-10-03,2026-10-01,8,4,4 #### 空数据 / 降级响应 -无命中只返回表头一行。 +无命中只返回表头一行；命中 > 2000 行返回 `589517`。 + +```json +{ + "code": 589517, + "message": "导出行数超过上限，请缩小筛选范围", + "data": null, + "success": false +} +``` #### 错误响应 -`productId` 有值且 `scope≠ALL` 时会调产品域取实时返团日，产品域不可用返回 589515（改前导出不依赖产品域）；超过 2000 行 589517。 +`productId` 有值且 `scope≠ALL` 时会调产品域取实时返团日，产品域不可用返回 589515（改前导出不依赖产品域）。 ```json { @@ -394,7 +416,13 @@ Q202610012052935476548939777,没，那你,2026-10-01~2026-10-03,2026-10-01,8,4,4 #### 出参 `Result>` -字段不变；行为变化：产品班期全部删除时不再提前返回空，仍有活跃子订单的孤儿行照常输出（`productBatchRemoved=true`）。 +| 字段 | 类型 | 说明 | +|------|------|------| +| data[] | Array | 行集：命中 / 未建团 / 孤儿三类行，出发日升序；本单结构不变 | +| data[].groupBatchId | String(Long) | 未建团行 null（不变） | +| data[].productBatchRemoved | Boolean | 孤儿行 true；**行为变化**：产品班期全部删除时不再提前返回空，仍有活跃子订单的孤儿行照常输出 | +| data[].batchLabel / batchName / batchNo / departureDate / endDate | String | 命中 / 未建团行 product 实时，孤儿行快照（不变） | +| 其余字段 | — | 不变 | #### 请求示例 @@ -448,9 +476,27 @@ Authorization: Bearer 产品无班期且无团期 → `data=[]`。 +```json +{ + "code": 200, + "message": "成功", + "data": [], + "success": true +} +``` + #### 错误响应 -`589515` 产品域不可用；`589507` 无权限。 +```json +{ + "code": 589515, + "message": "获取团期产品列表失败，请稍后重试", + "data": null, + "success": false +} +``` + +另：`589507` 无操作权限。 #### 业务边界 @@ -466,7 +512,9 @@ Authorization: Bearer #### 入参 -无。 +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| （无） | — | — | — | — | 无查询参数，返回当前账号可见的全部团期产品 | #### 出参 `Result>` @@ -517,9 +565,25 @@ Authorization: Bearer 无团期产品 → `data=[]`；产品无班期 → `batchCount=0`。 +```json +{ + "code": 200, + "message": "成功", + "data": [], + "success": true +} +``` + #### 错误响应 -`589515` 产品域不可用。 +```json +{ + "code": 589515, + "message": "获取团期产品列表失败，请稍后重试", + "data": null, + "success": false +} +``` #### 业务边界 @@ -544,7 +608,7 @@ Authorization: Bearer | ❌ 只给列表传 scope、统计条不传 | 统计条会按默认 ONGOING，与列表对不上账 | | ❌ 用列表 total 当页签期数 | 默认 ONGOING 不含已结束期；徽标用 `batchCount` | | ❌ 对 `groupBatchId=null` 的行调详情 / 子订单 / 团期操作 | 后端 589500 团期不存在 | -| ❌ 把 `chips` 为 TODO 的未建团行当「待办」 | 未建团行没有子订单，六项 TODO 只是零户占位 | +| ❌ 把 `chips` 为 `TODO` 的未建团行当「待办」 | 未建团行没有子订单，六项 `TODO` 只是零户占位 | ### 切换状态时的必要动作 @@ -593,7 +657,7 @@ Authorization: Bearer | GB-ADM-001 / 009 / 008 / board `scope` | 无 | 新增（缺省按 productId：有 → ONGOING，无 → ALL；board → ALL） | | GB-ADM-001 `records[].productBatchStatus / productBatchStatusLabel / productBatchRemoved` | 无 | 新增 | | GB-ADM-001 `records[].groupBatchId` | 恒非空 | 未建团行 null | -| GB-ADM-001 `records[].chips`（0 子订单行） | null | 六项 TODO | +| GB-ADM-001 `records[].chips`（0 子订单行） | null | 六项 `TODO` | | GB-ADM-001 `records[].batchNo / batchName / 日期`（命中行） | 订单快照 | product 实时 | | GB-ADM-000 `data[].batchCount` | 订单侧团期数 | product 侧未删班期数 | | product `GET /internal/product/group/all` `batchCount`、`/group/{productId}/detail` `batches[].occupiedRooms / manualOrderCount` | 无 | 新增（内部接口，前端不直接调） |