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

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	6904	团期看板统计条 GB-ADM-009 + 团期导出 GB-ADM-008	admin	wx(GIT)	新增接口	deployed	verified	verified	mmg	c91163fc		2026-09-01	2026-09-01 部署测试服 dev-v3@9f689354e，/summary 与 /export 经测试网关实测 200 全通过；CSV BOM/CRLF/10 列、7 桶口径、589517 上限均核验。前端评估(2026-09-01)：团期看板 src/views/order-v2/batch 当前为纯本地 mock 阶段(无真实 group-batch 调用)，统计条/导出依赖真实看板页;且看板列表契约 #6905/GB-ADM-000~003 未推送进 changelog 仓(仅被本单与 #6903 引用,无契约本体)。决策：等后端推送看板列表契约后,统一接真看板再一并接统计条+导出+六芯片下钻(#6903)。跟踪见 hl-admin 任务 #104。	2026-09-01	dev-v3

团期看板：统计条（GB-ADM-009）+ 团期导出（GB-ADM-008）

存放目录: 二期（order-v3）→ changelogs-v2/2026-09/

服务: hl-order-service-v3 PR: #6917 Issue: #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 列）

---

三、接口详情

两个接口共用筛选口径与状态映射（#6902 GroupBatchStageBuckets 七桶 / GroupBatchStatus 八态），正文各自自包含。

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

请求示例

GET /v3/admin/order/group-batch/summary?month=2026-06&keyword=%E6%B5%8B%E8%AF%95
Authorization: Bearer ****
X-Admin-Id: 3301

响应示例

{
  "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
}

空数据 / 降级响应

{ "code": 200, "data": { "total": 0,
  "buckets": { "RECRUIT": 0, "FORMED": 0, "PENDING_TRIP": 0, "TRAVELLING": 0,
    "AUDITING": 0, "CHECKED": 0, "DISBANDED": 0 },
  "subOrderCount": 0 }, "success": true }

错误响应

{ "code": 589507, "message": "无操作权限", "success": false, "data": null }

业务边界

• 授权码 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

VO: text/csv（流式附件，非 JSON 信封）

使用场景

团期看板页「导出」按钮：按当前筛选口径整表导出 CSV 文件（浏览器附件下载）。

入参

字段	位置	类型	必填	约束	说明
Authorization	Header	String	✅	-	管理端登录令牌
X-Admin-Id	Header	Long	✅	网关注入	受信管理员 ID；客户端传值忽略
productId	Query	Long	❌	-	同 summary
month	Query	String	❌	yyyy-MM	同 summary；文件名 group-batch-{month}.csv
keyword	Query	String	❌	-	同 summary

无请求体。

出参 text/csv（附件流）

字段	类型	说明
Content-Type	String	text/csv; charset=utf-8
Content-Disposition	String	`attachment; filename=group-batch-{month
body	String	UTF-8 BOM 开头的 CSV 文本：CRLF 换行、固定 10 列（表头见下）

表头 10 列: 团期号、期号、日期、出团日、满团名额、已售、剩余、状态、子订单数、整团应收。

请求示例

GET /v3/admin/order/group-batch/export?month=2026-06
Authorization: Bearer ****
X-Admin-Id: 3301

响应示例

（响应体为原生 CSV 文本，非 JSON 信封；下表以 JSON 字符串形式呈现字节内容示例）

"团期号,期号,日期,出团日,满团名额,已售,剩余,状态,子订单数,整团应收\r\nQ2026...,测试期,2026-06-10,2026-06-10,10,7,3,资源准备,1,15900.00\r\n"

空数据 / 降级响应

0 命中仅输出表头 10 列（仍带 UTF-8 BOM 与 CRLF），HTTP 200。

错误响应

{ "code": 589517, "message": "导出数据超限", "success": false, "data": null }

业务边界

• 授权码 group-batch:export；未配置权限 → 589507。
• 命中行数 > 2000 → 589517（上限 2000 行），前端提示收窄筛选。
• 每次成功导出写入 group_batch_status_log 导出留痕（BATCH_EXPORT，data 类变更，记录操作管理员与导出档头内容）。
• 只读（READ_ONLY 事务）；0 命中仅表头（BOM/CRLF 保持）。
• 非法 month → 400 参数错误；未登录 → 401（网关拦截）。
• 期号含逗号/引号/换行 → CSV 引号转义（内部引号翻倍）；金额两位小数不加千分位；剩余=max_rooms-已售且下限 0。

---

四、契约约束与正确调用方式（接口类必写）

本节只写后端接受/拒绝请求的规则，不写 UI 渲染建议。

✅ 正确 / ❌ 错误调用对照

场景	说明
✅ 仅带 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 桶）

所属字段: GroupBatchSummaryVO.buckets | 类型: Map<String,Integer>

桶键	来源 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 层合并，接口不并）。

导出「状态」列中文名

所属字段: CSV 第 8 列 | 类型: String

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
• 关联 PR: wx/HL#6917（合并至 dev-v3 @9f689354e）
• 共享地基: #6902（七桶/聚合/权限）、#6915/#6916（契约修正）

十一、复审补充知会（2026-09-01）

复审轮对现行行为的口径确认，无新接口、无字段结构变更。

1. 排序口径不一致（暂行，待拍板）：001 看板列表按 create_time 倒序（既有行为未变），009 统计条 / 008 导出按 depart_date 升序——「导出件顺序 ≠ 列表页顺序」当前属预期；001 是否改 depart_date ASC 待 wx 确认（决策点③），确认后另行通知对齐。
2. 008 当前忽略 opsStage：本期 008 只收 productId/month/keyword，契约卡的 opsStage 筛选由返工 #6926 补上。#6926 上线后：桶筛选态点「导出表格」必须带上当前 opsStage，否则导出为全量（当前行为：传了也被静默忽略）。
3. 同随 #6926 上线：009 自校验日志修正（内部可观测性，前端无感）、month 非法值容错跳过（不再 500）。

关联 / 联系人

链接

• Issue: #6904
• PR: #6917
• Merge commit: 9f689354e

联系人

• 后端负责人: @wx（GIT）