From 71cc52c1a333d182a4874cad7e76f790ebb24db6 Mon Sep 17 00:00:00 2001 From: wx Date: Fri, 4 Sep 2026 11:26:36 +0800 Subject: [PATCH] =?UTF-8?q?changelog(6926):=20=E5=AF=BC=E5=87=BA=E8=A1=A5?= =?UTF-8?q?=20opsStage=20=E7=AD=9B=E9=80=89=20+=20=E7=BB=9F=E8=AE=A1?= =?UTF-8?q?=E6=9D=A1=E8=87=AA=E6=A0=A1=E9=AA=8C=E6=AD=BB=E4=BB=A3=E7=A0=81?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=EF=BC=88=E4=BF=AE=E6=94=B9=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=EF=BC=89=20Refs=20#6926?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...自校验死代码修正（修改接口）-修改接口-管理后台.md | 173 ++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 changelogs-v2/2026-09/04_6926_导出补-opsStage-筛选-+-统计条自校验死代码修正（修改接口）-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/04_6926_导出补-opsStage-筛选-+-统计条自校验死代码修正（修改接口）-修改接口-管理后台.md b/changelogs-v2/2026-09/04_6926_导出补-opsStage-筛选-+-统计条自校验死代码修正（修改接口）-修改接口-管理后台.md new file mode 100644 index 00000000..922d193e --- /dev/null +++ b/changelogs-v2/2026-09/04_6926_导出补-opsStage-筛选-+-统计条自校验死代码修正（修改接口）-修改接口-管理后台.md @@ -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