diff --git a/changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md b/changelogs-v2/2026-09/01_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md similarity index 73% rename from changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md rename to changelogs-v2/2026-09/01_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md index c5e5bce3..18367860 100644 --- a/changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md +++ b/changelogs-v2/2026-09/01_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md @@ -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` + | 桶键 | 来源 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`。