From c9efecebc5e5bdcb2df1dd1397e12aa7ea048aa4 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Tue, 1 Sep 2026 12:24:34 +0800 Subject: [PATCH] =?UTF-8?q?chore(6904):=20=E5=9B=A2=E6=9C=9F=E7=9C=8B?= =?UTF-8?q?=E6=9D=BF=E7=BB=9F=E8=AE=A1=E6=9D=A1=E4=B8=8E=E5=AF=BC=E5=87=BA?= =?UTF-8?q?=20GB-ADM-009/008=20=E5=8F=98=E6=9B=B4=E5=BD=92=E6=A1=A3=20(dev?= =?UTF-8?q?-v3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...计条与导出-GB-ADM-009-008-新增接口-管理后台.md | 290 ++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md diff --git a/changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md b/changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md new file mode 100644 index 00000000..c5e5bce3 --- /dev/null +++ b/changelogs-v2/2026-09/02_6904_团期看板统计条与导出-GB-ADM-009-008-新增接口-管理后台.md @@ -0,0 +1,290 @@ +--- +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` + +| 字段 | 类型 | 说明 | +|------|------|------| +| total | Integer | 七桶计数之和（接口自校验桶和，恒等于各桶值加总） | +| buckets | Map | 七键恒全：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）