Mimingguang
2f6a989fcf
changelog-filename-gate / validate (push) Failing after 2s
11 条有业务交付改判 verified(#6397/6903/6904/6905/6950/6979/6986/7013/7029/7036/7066,owner=mmg+对应业务 commit ref+交付日 verified_at); 6 条实证零改动改判 not_required(#6014/6016/6140/6938/6842/7087,仅翻 frontend_status 不填 owner/ref)。 #5935 挂起待后端补字段,保持 pending 不动。sync-log 均已记账。
339 行
15 KiB
Markdown
339 行
15 KiB
Markdown
---
|
||
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: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "c91163fc"
|
||
target_release: ""
|
||
verified_at: "2026-09-01"
|
||
status_note: "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。"
|
||
updated_at: "2026-09-01"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 团期看板：统计条（GB-ADM-009）+ 团期导出（GB-ADM-008）
|
||
|
||
> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
|
||
>
|
||
> **服务**: hl-order-service-v3
|
||
> **PR**: #6917
|
||
> **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 列） |
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
两个接口共用筛选口径与状态映射（#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 房） |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/summary?month=2026-06&keyword=%E6%B5%8B%E8%AF%95
|
||
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
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
```json
|
||
{ "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 }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{ "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|all}.csv` |
|
||
| body | String | UTF-8 BOM 开头的 CSV 文本：CRLF 换行、固定 10 列（表头见下） |
|
||
|
||
**表头 10 列**: 团期号、期号、日期、出团日、满团名额、已售、剩余、状态、子订单数、整团应收。
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/export?month=2026-06
|
||
Authorization: Bearer ****
|
||
X-Admin-Id: 3301
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
（响应体为原生 CSV 文本，非 JSON 信封；下表以 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。
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{ "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](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（契约修正）
|
||
|
||
## 十一、复审补充知会（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](https://git.1814.love:8443/wx/HL/issues/6904)
|
||
- **PR**: #6917
|
||
- **Merge commit**: 9f689354e
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx（GIT）
|