changelog(6926): 导出补 opsStage 筛选 + 统计条自校验死代码修正（修改接口） Refs #6926

2026-09-04 11:26:36 +08:00
@@ -0,0 +1,173 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6926"
+title: "导出补 opsStage 筛选 + 统计条自校验死代码修正（修改接口）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-04"
+status_note: "2026-09-04 测试服部署 dev-v3@0c497649b；导出三态与 summary 非法 month/opsStage 忽略经网关 200 全通过"
+updated_at: "2026-09-04"
+base: "dev-v3"
+generated: "2026-09-04T10:34:46+08:00"
+---
+
+# 团期看板：导出补 opsStage 筛选（GB-ADM-008）+ 统计条自校验死代码修正（GB-ADM-009）
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3
+> **PR**: #7061（squash 合并 dev-v3@0c497649b）
+> **Issue**: [#6926](https://git.1814.love:8443/wx/HL/issues/6926)
+> **日期**: 2026-09-04
+> **影响范围**: 管理后台团期看板——导出端点新增可选 opsStage 筛选；统计条自校验死代码修正（使未知状态行排除可观测）
+
+---
+
+## ⚠️ 关键变化
+
+**修改接口，向后兼容、无破坏**：① GB-ADM-008 导出新增可选查询参数 `opsStage`（七桶筛选，`FORMED` 展开为 `RESOURCE_PREPARING+MATERIAL_PREPARING` 两态 in 过滤，与 productId/month/keyword 叠加取交集；非法值忽略不报错）；② GB-ADM-009 统计条自校验条件 `bucketSum != counted`（永假死代码）改为 `rows.size() != counted`（未知 `batch_status` 行排除后真实触发 ERROR 日志）；③ 两端点 month 非法值（如 `2026-13`）跳过月份筛选不 500（与 GB-ADM-001 `parseMonthRange` 同口径）；④ `buildCsv` 补 capacity_delta 拟议注释。
+
+---
+
+## 一、背景（选填）
+
+PR #6917（#6904 统计条+导出）复审确认两处要修：008 契约卡查询参数含 `opsStage`（同 GB-ADM-001），实现未接收——前端在桶筛选态点导出时参数被 Spring 静默忽略，导出未按桶过滤的全量数据且无报错；009 的 total 自校验 `bucketSum != counted` 永假（counted 只在桶 merge 成功的同一分支自增，与桶和定义相等），契约要求的不一致记 ERROR 永不触发，未知状态行在 summary 路径被静默丢弃（export 路径已有 ERROR）。另顺手对齐两小口径（month 容错、capacity_delta 注释）。
+
+---
+
+## 变更接口
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | GB-ADM-008 团期导出 | GET | `/v3/admin/order/group-batch/export` | 修改接口 | 新增可选 `opsStage` 筛选参数 + month 容错 |
+| 2 | GB-ADM-009 团期统计条 | GET | `/v3/admin/order/group-batch/summary` | 修改接口（行为修正） | 自校验死代码修正（参数/响应不变）；month 容错 |
+
+---
+
+## 接口详情
+
+### 1. GB-ADM-008 团期导出 `GET /v3/admin/order/group-batch/export`（修改接口）
+
+**请求参数**（★=本期新增，其余不变）
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| Authorization / X-Admin-Id | Header | String/Long | ✓ | 网关注入，客户端传值忽略 |
+| productId | Query | Long | | 产品 ID，缺省不限（既有） |
+| month | Query | String | | 出团月份 yyyy-MM（既有；本期改容错：非法值跳过筛选不 500，与 001 同口径） |
+| keyword | Query | String | | 团期编号/名称模糊关键词（既有） |
+| ★ opsStage | Query | String | | 七桶筛选（RECRUIT/FORMED/PENDING_TRIP/TRAVELLING/AUDITING/CHECKED/DISBANDED），FORMED 展开为两态 in 过滤；与 productId/month/keyword 叠加取交集；非法值忽略不报错 |
+
+**响应**: 不变（`text/csv` 文件流，固定 10 列，UTF-8 BOM + CRLF，单次上限 2000 行）。
+
+**错误码**: 不变（589507 无 `group-batch:export`、589517 超 2000 行）。
+
+**内部实现**：opsStage → `GroupBatchStageBuckets.statusCodesOf()`（唯一解析口，001 的 `resolveOpsStatuses` 委托同源）→ `selectBoardRows(..., opsStatuses, ...)` 的 `inIfPresent(GroupBatchDO::getBatchStatus, opsStatuses)`。
+
+### 2. GB-ADM-009 团期统计条 `GET /v3/admin/order/group-batch/summary`（行为修正）
+
+**请求参数**: 不变（productId/month/keyword；**不接受** opsStage——契约原文要求忽略该参数）。
+
+**响应**: 不变（`GroupBatchSummaryVO`：total + 7 桶 + subOrderCount）。
+
+**行为修正**: 未知 batch_status 行排除后，`rows.size() != counted` 时记 ERROR 日志（原先 `bucketSum != counted` 永假不触发），total 仍以桶和为准。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+### ✅ 正确 / ❌ 错误调用对照
+
+| 场景 | 说明 |
+|------|------|
+| ✅ export?opsStage=FORMED | 两态 in 过滤（RESOURCE_PREPARING+MATERIAL_PREPARING），与 productId/month/keyword 取交集 |
+| ✅ export?opsStage=非法值（如 NOT_BUCKET） | 忽略该筛选，不报错，等价不传 |
+| ✅ export?month=2026-13 | 跳过月份筛选不 500（2026-13 非法） |
+| ✅ summary 带 opsStage | 忽略（009 契约不接受），响应与不带一致 |
+| ❌ 导出命中 > 2000 行 | 589517 |
+| ❌ 无 group-batch:export 授权 | 589507 |
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+无表变更、无列变更。唯一写操作：导出成功后逐团期写 `group_batch_status_log` BATCH_EXPORT 留痕（REQUIRES_NEW 独立写事务，导出失败不写留痕），与 #6904 一致。
+
+---
+
+## 六、边界行为
+
+- 非法 opsStage（含未知桶）→ warn 日志「未知的 opsStage 筛选值，忽略该筛选」，返回 null 跳过筛选（与 001 口径一致）。
+- 非法 month → warn「非法的 month 参数，忽略月份筛选」，跳过月份条件（summary 与 export 均不 500）。
+- summary 遇未知 batch_status 行 → 不进入任何桶，total=桶和，ERROR「团期看板统计条口径不一致: rows=N bucketSum=M」真正触发。
+- 空结果：export 仅表头（BOM/CRLF 保持），summary 七桶全 0。
+- 导出「状态」列对未知状态原样透出（不报错）。
+
+---
+
+## 七、不影响范围（显式声明）
+
+- 未改 CSV 列结构与列序（仍固定 10 列）。
+- 未建表/未改表/未加列。
+- 009 响应结构不变（7 桶 + total + subOrderCount）。
+- 未触碰 #6905（GB-ADM-000~003 看板列表/详情）任何接口与文件。
+- 网关路由不动（/v3/admin/** 通配已覆盖），无配置中心变更。
+
+---
+
+## 验证证据
+
+**JUnit 定向测试**（dev-v3@0c497649b 合并后，分支内）：
+
+```
+mvn -pl hl-order-service-v3 -am test -Dtest=GroupBatchBoardStatsServiceTest,GroupBatchStageBucketsTest,GroupBatchBoardStatsControllerTest,GroupBatchMapperEscapeLikeTest -DfailIfNoTests=false
+Tests run: 34, Failures: 0, Errors: 0（含 opsStage 展开/非法忽略/month 容错/ERROR 日志触发 4 新断言）
+```
+
+**全量**: `mvn -pl hl-order-service-v3 -am test` 7897 用例，仅基线 6 失败（3 refund 401-envelope + 3 adjustment 日期敏感，与 dev-v3 基线一致，非本单引入）。
+
+**网关实测**（部署 dev-v3@0c497649b 后，经 api.test.1814.love:9443）：
+
+```
+GET /v3/admin/order/group-batch/export?month=2026-06              → 200 text/csv 附件（group-batch-2026-06.csv） ✓
+GET /v3/admin/order/group-batch/export?month=2026-06&opsStage=FORMED → 200 text/csv ✓
+GET /v3/admin/order/group-batch/export?month=2026-06&opsStage=NOT_BUCKET → 200 text/csv（非法忽略）✓
+GET /v3/admin/order/group-batch/summary?month=2026-13             → 200 code=200 total=14（容错跳过，非 500）✓
+GET /v3/admin/order/group-batch/summary?opsStage=FORMED           → 200 code=200（忽略，与不带一致 total=14）✓
+```
+
+---
+
+## 九、相关历史 PR
+
+- PR #6917（#6904 统计条+导出）——本单为其实施复审返工。
+- PR #7061——本单（squash 合并 dev-v3@0c497649b）。
+
+---
+
+## 十、相关文档
+
+- 契约卡 GB-ADM-008 / GB-ADM-009（#6902 地基，#6904 契约）。
+- `changelogs-v2/2026-09/01_6904_...`（新增接口原始文档）。
+- `changelogs-v2/2026-09/01_6905_...`（看板列表 4 接口，与本单互不覆盖）。
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#6926](https://git.1814.love:8443/wx/HL/issues/6926)
+- **PR**: [#7061](https://git.1814.love:8443/wx/HL/pulls/7061)
+- **Merge commit**: [0c497649b](https://git.1814.love:8443/wx/HL/commit/0c497649b)
+
+### 联系人
+
+- **后端负责人**: @wx