chore(6904): 团期看板统计条与导出 GB-ADM-009/008 变更归档 (dev-v3)

changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md

@@ -0,0 +1,290 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6904"
+title: "团期看板统计条 GB-ADM-009 + 团期导出 GB-ADM-008"
+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-01"
+status_note: "2026-09-01 部署测试服 dev-v3@9f689354e，summary/export 两端点网关实测 200 全通过；CSV BOM/CRLF/10 列、7 桶口径、589517 上限均已核验"
+updated_at: "2026-09-01"
+base: "dev-v3"
+---
+
+# 团期看板：统计条（GB-ADM-009）+ 团期导出（GB-ADM-008）
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3
+> **Issue**: [#6904](https://git.1814.love:8443/wx/HL/issues/6904)
+> **日期**: 2026-09-01
+> **影响范围**: 管理后台团期看板顶部统计条（7 桶计数 + 活跃子订单数）与整表 CSV 导出
+
+---
+
+## ⚠️ 关键变化
+
+**新增能力，无破坏性变化**：团期看板新增两个只读端点——统计条（`/summary`）汇总七大状态桶与跨团期活跃子订单数；导出（`/export`）按看板筛选条件整表导出 CSV（UTF-8 BOM、CRLF、固定 10 列）。与 #6905 交付的列表/详情（GB-ADM-000~003）同地基（#6902），本单不触碰 #6905 任何接口与文件。
+
+---
+
+## 一、背景（选填）
+
+管理后台团期看板页顶部需要一条统计条（七桶计数 + 活跃子订单数），并支持把当前筛选下的团期整表导出为 CSV。口径与看板列表（GB-ADM-000/001/002/003）完全一致：同筛选（productId 精确、month 落出团月、keyword 模糊 OR）、同状态源（`order_group_batch.batch_status` 八态）、同聚合（跨命中团期统计活跃子订单）。FORMED 为 RESOURCE_PREPARING+MATERIAL_PREPARING 复合桶；AUDITING/CHECKED 在接口层保持独立桶，前端展示可折叠合并。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | GB-ADM-009 团期看板统计条 | GET | `/v3/admin/order/group-batch/summary` | 新增接口 | 七桶计数 + total + subOrderCount |
+| 2 | GB-ADM-008 团期导出 | GET | `/v3/admin/order/group-batch/export` | 新增接口 | 看板整表 CSV 导出（10 列） |
+
+---
+
+## 三、接口详情
+
+### 1. GB-ADM-009 团期看板统计条 `GET /v3/admin/order/group-batch/summary`
+
+**VO**: `GroupBatchSummaryVO`
+
+#### 使用场景
+
+团期看板页顶部统计条：返回当前筛选口径下七大状态桶计数、桶合计与跨团期活跃子订单数（任一桶非零即有数据）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值一律忽略（不校验客户端值） |
+| productId | Query | Long | ❌ | - | 精确匹配团期所属产品 |
+| month | Query | String | ❌ | `yyyy-MM` | 出团月筛选：`depart_date >= 月初 && < 次月`；空/缺省 = 全部 |
+| keyword | Query | String | ❌ | - | 团期号/团期名模糊 OR（trim 后；`%` `_` `\` 转义，与 GB-ADM-001 同义） |
+
+无请求体。
+
+#### 出参 `Result<GroupBatchSummaryVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| total | Integer | 七桶计数之和（接口自校验桶和，恒等于各桶值加总） |
+| buckets | Map<String,Integer> | 七键恒全：RECRUIT/FORMED/PENDING_TRIP/TRAVELLING/AUDITING/CHECKED/DISBANDED；FORMED=RESOURCE_PREPARING+MATERIAL_PREPARING 复合 |
+| subOrderCount | Integer | 跨全部命中团期的活跃子订单数（order_status != CANCELLED 且未软删；1 团期 1 房） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/summary?month=2026-06&keyword=测试
+Authorization: Bearer ****
+X-Admin-Id: 3301
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "data": {
+    "total": 14,
+    "buckets": {
+      "RECRUIT": 0, "FORMED": 13, "PENDING_TRIP": 0, "TRAVELLING": 0,
+      "AUDITING": 0, "CHECKED": 0, "DISBANDED": 1
+    },
+    "subOrderCount": 1
+  },
+  "success": true
+}
+```
+
+#### 业务边界
+
+- 授权码 `group-batch:list`；未配置权限 → 589507。
+- 只读（READ_ONLY 事务）：无锁、无幂等、不改变任何状态。
+- 非法 month（非 `yyyy-MM`）→ 400 参数错误（框架级）。
+- 空数据时七键仍全返回（各桶 0），total=0、subOrderCount=0，不 500 不降级。
+
+---
+
+### 2. GB-ADM-008 团期导出 `GET /v3/admin/order/group-batch/export`
+
+**输出**: `text/csv; charset=utf-8`，附 `Content-Disposition`（文件名 `group-batch-{month}.csv` / 无 month 时 `group-batch-all.csv`）。
+
+#### 使用场景
+
+团期看板页「导出」按钮：按当前筛选口径整表导出 CSV。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
+| productId | Query | Long | ❌ | - | 同 summary |
+| month | Query | String | ❌ | `yyyy-MM` | 同 summary |
+| keyword | Query | String | ❌ | - | 同 summary |
+
+无请求体。
+
+#### 输出格式（固定 10 列，UTF-8 BOM，CRLF 换行）
+
+| # | 列 | 说明 |
+|---|----|------|
+| 1 | 团期号 | `batch_no` |
+| 2 | 期号 | `batch_name`（含逗号/引号/换行时按 CSV 规则加引号） |
+| 3 | 日期 | 出团日期 `yyyy-MM-dd`（按 depart_date 升序，同 asc 稳定排序） |
+| 4 | 出团日 | 与 3 列重复展示的日期字段（固定列宽占位） |
+| 5 | 满团名额 | `max_rooms` |
+| 6 | 已售 | 当前已售房数 |
+| 7 | 剩余 | `max_rooms - 已售`，下限 0 |
+| 8 | 状态 | `batch_status` 中文名（未知态原样透出） |
+| 9 | 子订单数 | 该团期活跃子订单数 |
+| 10 | 整团应收 | 该团期应收合计（BigDecimal，两位小数，不加千分位） |
+
+#### 响应示例（表头行）
+
+```text
+团期号,期号,日期,出团日,满团名额,已售,剩余,状态,子订单数,整团应收
+```
+
+#### 业务边界
+
+- 授权码 `group-batch:export`；未配置权限 → 589507。
+- 命中行数 > 2000 → 589517 导出数据超限（上限 2000 行，避免大表拖垮导出链路），前端提示收窄筛选。
+- 每次成功导出写入 `group_batch_status_log` 导出留痕（BATCH_EXPORT，data 类变更，记录操作管理员与导出档头内容）。
+- 只读（READ_ONLY 事务）。0 命中仅输出表头 10 列（携带 BOM/CRLF）。
+- 非法 month → 400 参数错误；未登录 → 401（网关拦截）。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+### ✅ 正确 / ❌ 错误调用对照
+
+| 场景 | 说明 |
+|------|------|
+| ✅ 仅带 Authorization 调 summary/export | 全量口径：7 桶恒全、export 全表（受 2000 行上限约束） |
+| ✅ productId+month+keyword 组合筛选 | 与 GB-ADM-001 同义：productId 精确 / month 落出团月 / keyword trim 后模糊 OR（`%` `_` `\` 转义） |
+| ❌ 未配置 `group-batch:list` / `group-batch:export` | 589507 无操作权限（两个授权点独立） |
+| ❌ 命中 > 2000 行导出 | 589517 导出数据超限 |
+| ❌ 客户端自行传 X-Admin-Id | 以网关注入值为准，客户端值一律忽略 |
+
+### 切换状态时的必要动作
+
+无状态切换——两端点均只读 GET、无请求体；导出需用户在导出前先具备 `group-batch:export` 授权点（看板查看仅需 `group-batch:list`）。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+两端点主体为只读（READ_ONLY 事务）：聚合 `countActiveByProductBatchIds`（活跃子订单）、`sumBatchAmountsByProductBatchIds`（整团应收，共享 #6902 地基），无表变更、无字段变更。唯一写操作：成功导出后向 `group_batch_status_log` 追加一条 BATCH_EXPORT 留痕记录（`REQUIRES_NEW` 独立事务，导出失败不写留痕）。
+
+---
+
+## 六、边界行为
+
+- 未登录/无有效 token → 401（网关拦截，两端点不允许匿名访问）。
+- 未配置对应授权点 → 589507。（`/summary` 用 `group-batch:list`，`/export` 用 `group-batch:export`）
+- 导出命中 > 2000 行 → 589517；前端应引导收窄 month/productId/keyword。
+- 非法 month 格式 → 400 参数错误（框架级）。
+- 空数据：summary 七键全 0；export 仅表头 10 列（BOM/CRLF 保持），不 500 不降级。
+- 状态未知/历史脏数据：`safeStatus` 原样透出（导出的状态列不报错）。
+- 剩余列恒 `max_rooms - 已售` 且下限 0；金额列两位小数、不加千分位。
+- 期号含 `,` `"` `\r` `\n` → CSV 引号转义（内部引号翻倍）。
+
+---
+
+## 六.5、枚举 / 数据字典（接口类必写）
+
+### buckets 键（7 桶）
+
+| 桶键 | 来源 batch_status | 说明 |
+|------|------------------|------|
+| RECRUIT | RECRUITING | 招募中 |
+| FORMED | RESOURCE_PREPARING + MATERIAL_PREPARING | 复合桶（成团准备） |
+| PENDING_TRIP | PENDING_DEPARTURE | 待出发 |
+| TRAVELLING | TRAVELLING | 出游中 |
+| AUDITING | REVIEWING | 审核 |
+| CHECKED | SETTLED | 结算 |
+| DISBANDED | CANCELLED | 流团/取消 |
+
+> 说明：FORMED 复合桶、AUDITING/CHECKED 独立桶为接口层口径；前端展示可将 AUDITING+CHECKED 折叠为「返团核账」类目（display 层合并，接口不并）。
+
+### 导出「状态」列中文名
+
+| batch_status | 中文 |
+|--------------|------|
+| RECRUITING | 招募中 |
+| RESOURCE_PREPARING | 资源准备 |
+| MATERIAL_PREPARING | 物料准备 |
+| PENDING_DEPARTURE | 待出发 |
+| TRAVELLING | 出游中 |
+| REVIEWING | 审核中 |
+| SETTLED | 已结算 |
+| CANCELLED | 已流团 |
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: 团期看板统计条（GB-ADM-009）与导出（GB-ADM-008）两个新增端点。
+- **零影响**:
+  - #6905 交付的看板列表/详情/条件接口（GB-ADM-000~003）与文件（本单未改动）
+  - 共享地基 #6902 的 `OrderService`/`GroupBatchStageBuckets`（本单仅新增导出留痕方法与本枚举项，未改既有方法与接口）
+  - 一期（v2）所有接口；数据库结构、网关路由、权限点（复用既有 `group-batch:list`/`group-batch:export`）
+
+---
+
+## 八、测试环境已验证
+
+**JUnit 定向测试**: `GroupBatchBoardStatsServiceTest`（11 用例）+ `GroupBatchBoardStatsControllerTest`（6 用例）+ `GroupBatchMapperEscapeLikeTest`（3 用例）全绿；覆盖七桶折叠、total 自校验、subOrderCount、筛选转义、CSV 格式、589507/589517、留痕写入。
+
+**全模块** `mvn -pl hl-order-service-v3 -am test`（2026-09-01，分支合并至 dev-v3 后）：Tests run 7872 / Failures 3 / Errors 0 / Skipped 7——3 个失败均为 refund 模块**既有**切片用例（旧契约期望 200+code401 信封，当前拦截器直返 401），已在独立基线 worktree（dev-v3 不含本次改动）复现，与本次 9 个文件变更无关。
+
+真实接口网关验证（2026-09-01 部署 dev-v3@9f689354e 后实测）：
+
+```
+GET /v3/admin/order/group-batch/summary                    → 200 code=200  buckets={RECRUIT:0,FORMED:13,PENDING_TRIP:0,TRAVELLING:0,AUDITING:0,CHECKED:0,DISBANDED:1} total=14 subOrderCount=1 ✓
+GET /v3/admin/order/group-batch/summary?month=2026-06&keyword=测试 → 200 code=200 ✓
+GET /v3/admin/order/group-batch/export                     → 200  size=1739  BOM ✓ CRLF ✓ 10 列 ✓
+GET /v3/admin/order/group-batch/export?month=2026-06       → 200  size=98  （0 命中仅表头） ✓
+```
+
+验证通道: 统一网关 `https://api.test.1814.love:9443`，管理员登录 token + 网关注入 `X-Admin-Id`。
+
+---
+
+## 九、相关历史 PR（纠错 / 功能演进时必写）
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| #6917 | #6904 | 团期看板统计条 + 导出交付（本单） | ✅ 最新 |
+| #6914 | #6902 | 共享地基（七桶枚举/聚合/权限/错误码） | ✅ 有效 |
+| #6916 | #6915 | 共享地基 statusText 契约修正 | ✅ 有效 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#6904](https://git.1814.love:8443/wx/HL/issues/6904)
+- 关联 PR: [wx/HL#6917](https://git.1814.love:8443/wx/HL/pulls/6917)（合并至 dev-v3 @9f689354e）
+- 共享地基: #6902（七桶/聚合/权限）、#6915/#6916（契约修正）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#6904](https://git.1814.love:8443/wx/HL/issues/6904)
+- **PR**: #6917
+- **Merge commit**: 9f689354e
+
+### 联系人
+
+- **后端负责人**: @wx（GIT）