---
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）