wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

chore(6904): changelog 文件名归档 01 前缀 (2026-09-01)
changelog-filename-gate / validate (push) Successful in 2s
详情

浏览代码
这个提交包含在：
API Changelog Bot
2026-09-01 13:26:58 +08:00
父节点 c9efecebc5
当前提交 a031039140
共修改 1 个文件，包含 69 行新增和 29 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md → changelogs-v2/2026-09/01_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md
+69 -29
查看文件
@@ -12,7 +12,7 @@ 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 上限均已核验"
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"
---
@@ -22,6 +22,7 @@ base: "dev-v3"
> **存放目录**: 二期（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 导出
@@ -30,13 +31,13 @@ base: "dev-v3"
## ⚠️ 关键变化
**新增能力，无破坏性变化**：团期看板新增两个只读端点——统计条（`/summary`）汇总七大状态桶与跨团期活跃子订单数；导出（`/export`）按看板筛选条件整表导出 CSV（UTF-8 BOM、CRLF、固定 10 列）。与 #6905 交付的列表/详情（GB-ADM-000~003）同地基（#6902），本单不触碰 #6905 任何接口与文件。
**新增能力，无破坏性变化**：团期看板新增两个只读端点——统计条（`/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 在接口层保持独立桶，前端展示可折叠合并。
管理后台团期看板页顶部需要一条统计条（七桶计数 + 活跃子订单数），并把当前筛选下的团期整表导出为 CSV。口径与看板列表（GB-ADM-000/001/002/003）完全一致：同筛选（productId 精确、month 落出团月、keyword 模糊 OR）、同状态源（`order_group_batch.batch_status` 八态）、同聚合（跨命中团期统计活跃子订单）。FORMED 为 RESOURCE_PREPARING+MATERIAL_PREPARING 复合桶；AUDITING/CHECKED 在接口层保持独立桶，前端展示可折叠合并。
---
@@ -51,6 +52,8 @@ base: "dev-v3"
## 三、接口详情
两个接口共用筛选口径与状态映射（#6902 `GroupBatchStageBuckets` 七桶 / `GroupBatchStatus` 八态），正文各自自包含。
### 1. GB-ADM-009 团期看板统计条 `GET /v3/admin/order/group-batch/summary`
**VO**: `GroupBatchSummaryVO`
@@ -82,7 +85,7 @@ base: "dev-v3"
#### 请求示例
```http
GET /v3/admin/order/group-batch/summary?month=2026-06&keyword=测试
GET /v3/admin/order/group-batch/summary?month=2026-06&keyword=%E6%B5%8B%E8%AF%95
Authorization: Bearer ****
X-Admin-Id: 3301
```
@@ -104,10 +107,25 @@ X-Admin-Id: 3301
}
```
#### 空数据 / 降级响应
```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 事务）：无锁、无幂等、不改变任何状态。
- 只读（READ_ONLY 事务），无锁、无幂等、不改变任何状态。
- 非法 month（非 `yyyy-MM`）→ 400 参数错误（框架级）。
- 空数据时七键仍全返回（各桶 0），total=0、subOrderCount=0，不 500 不降级。
@@ -115,11 +133,11 @@ X-Admin-Id: 3301
### 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`）。
**VO**: `text/csv`（流式附件，非 JSON 信封）
#### 使用场景
团期看板页「导出」按钮：按当前筛选口径整表导出 CSV。
团期看板页「导出」按钮：按当前筛选口径整表导出 CSV 文件（浏览器附件下载）。
#### 入参
@@ -128,44 +146,62 @@ X-Admin-Id: 3301
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
| X-Admin-Id | Header | Long | ✅ | 网关注入 | 受信管理员 ID；客户端传值忽略 |
| productId | Query | Long | ❌ | - | 同 summary |
| month | Query | String | ❌ | `yyyy-MM` | 同 summary |
| month | Query | String | ❌ | `yyyy-MM` | 同 summary；文件名 `group-batch-{month}.csv` |
| keyword | Query | String | ❌ | - | 同 summary |
无请求体。
#### 输出格式（固定 10 列，UTF-8 BOM，CRLF 换行）
#### 出参 `text/csv`（附件流）
| # | 列 | 说明 |
|---|----|------|
| 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，两位小数，不加千分位） |
| 字段 | 类型 | 说明 |
|------|------|------|
| 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 列**: 团期号、期号、日期、出团日、满团名额、已售、剩余、状态、子订单数、整团应收。
```text
团期号,期号,日期,出团日,满团名额,已售,剩余,状态,子订单数,整团应收
#### 请求示例
```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 行，避免大表拖垮导出链路），前端提示收窄筛选。
- 命中行数 > 2000 → 589517（上限 2000 行），前端提示收窄筛选。
- 每次成功导出写入 `group_batch_status_log` 导出留痕（BATCH_EXPORT，data 类变更，记录操作管理员与导出档头内容）。
- 只读（READ_ONLY 事务）。0 命中仅输出表头 10 列（携带 BOM/CRLF）。
- 只读（READ_ONLY 事务）；0 命中仅表头（BOM/CRLF 保持）。
- 非法 month → 400 参数错误；未登录 → 401（网关拦截）。
- 期号含逗号/引号/换行 → CSV 引号转义（内部引号翻倍）；金额两位小数不加千分位；剩余=max_rooms-已售且下限 0。
---
## 四、契约约束与正确调用方式（接口类必写）
> 本节只写后端接受/拒绝请求的规则，不写 UI 渲染建议。
### ✅ 正确 / ❌ 错误调用对照
| 场景 | 说明 |
@@ -178,7 +214,7 @@ X-Admin-Id: 3301
### 切换状态时的必要动作
无状态切换——两端点均只读 GET、无请求体；导出需用户在导出前先具备 `group-batch:export` 授权点（看板查看仅需 `group-batch:list`）。
无状态切换——两端点均只读 GET、无请求体；导出需前端先具备 `group-batch:export` 授权点（看板查看仅需 `group-batch:list`）。
---
@@ -205,6 +241,8 @@ X-Admin-Id: 3301
### buckets 键（7 桶）
**所属字段**: `GroupBatchSummaryVO.buckets` | **类型**: `Map<String,Integer>`
| 桶键 | 来源 batch_status | 说明 |
|------|------------------|------|
| RECRUIT | RECRUITING | 招募中 |
@@ -219,6 +257,8 @@ X-Admin-Id: 3301
### 导出「状态」列中文名
**所属字段**: CSV 第 8 列 | **类型**: `String`
| batch_status | 中文 |
|--------------|------|
| RECRUITING | 招募中 |
@@ -253,8 +293,8 @@ X-Admin-Id: 3301
```
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 命中仅表头） ✓
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`。