changelog(6905): 团期看板 4 接口对齐补全 GB-ADM-000/001/002/003（管理后台/修改接口）

2026-09-01 14:56:52 +08:00
@@ -0,0 +1,364 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6905"
+title: "团期看板 4 接口对齐补全 GB-ADM-000/001/002/003"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: "regionText 待上游 product-v2 补齐后由前端组另行验收（本单不验收前端展示）"
+target_release: ""
+verified_at: "2026-09-01"
+status_note: "regionText 由上游 product-v2 提供后透传，当前测试环境返回 null 属预期；001 排序保持 create_time DESC 未变（depart_date ASC 变更待 wx 确认）"
+updated_at: "2026-09-01"
+base: "dev-v3"
+---
+
+# 团期看板 4 接口对齐补全 GB-ADM-000/001/002/003
+
+> **服务**: hl-order-service-v3
+> **PR**: #6923（网关拦截 PUT 无法 API 合并，采用等价 squash 推送落地 dev-v3，PR 已 closed 留痕）
+> **Issue**: #6905
+> **日期**: 2026-09-01
+> **影响范围**: 管理后台团期看板 4 个查询接口（产品列表/团期分页/团期详情/团期订单列表）
+
+---
+
+## ⚠️ 关键变化
+
+- 本单**只做查询接口的字段/筛选/性能对齐**，未新建任何表/列，未新增写操作。
+- 运营阶段映射为团期八态（opsStage 桶+八态并集），本单**不新增 ops_stage 字段/表**。
+- **证件号与游客手机号永不返回**（编译期字段裁剪 + 运行期实测零返回），前端不得依赖。
+- contactPhone 一期**全量掩码**（保前 3 后 4，如 138****0001）。
+- 001 排序**保持 create_time DESC**（将 depart_date 升序的变更留待 wx 确认，PR 与进度中已注明）。
+- regionText 由上游 product-v2 提供（order 侧仅透传），当前上游未提供时返回 null，**产品域交接后由前端组验收展示**。
+
+---
+
+## 一、背景
+
+团期看板已实现 4 个查询接口（GB-ADM-000/001/002/003，见 #6902 共享件），本单按验收清单补齐全量字段、真实来源取值、批量聚合与筛选参数，消除 N+1。依赖 #6902（已合并 dev-v3）。
+
+## 变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 产品团期看板(000) | GET | `/v3/admin/order/group-batch/products` | 新增响应字段+入参 | batchCount/regionText + productType 筛选 |
+| 2 | 团期分页列表(001) | GET | `/v3/admin/order/group-batch` | 新增筛选+响应字段 | opsStage/month/keyword + chips/金额/orderCount |
+| 3 | 团期详情(002) | GET | `/v3/admin/order/group-batch/<groupBatchId>` | 金额实时聚合+reporter | totalReceivable/totalReceived 实时、primaryReporter 批量 |
+| 4 | 团期订单列表(003) | GET | `/v3/admin/order/group-batch/<groupBatchId>/orders` | 新增批量派生字段 | 成本/tier/人数/房车需求/掩码手机/游客(证件零返回) |
+
+## 三、接口详情
+
+### 1. 产品团期看板 `GET /v3/admin/order/group-batch/products`（GB-ADM-000）
+
+**使用场景**: 管理后台看板"产品列表"页：按产品展示其团期批量数。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productType | Query | String | 否 | - | 产品类型筛选；不传=不限（向后兼容） |
+| keyword | Query | String | 否 | - | 产品名关键词（原有行为不变） |
+
+#### 出参（新增字段）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| batchCount | Integer | 该产品下活跃团期数（一次性 in 投影 product_id 后内存分组计数，无逐产品 count） |
+| regionText | String | 产品地域文本（上游 product-v2 提供后透传；当前上游未提供时 null） |
+
+#### 请求示例
+
+GET /v3/admin/order/group-batch/products?productType=&keyword=
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": []
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 401,
+  "message": "未登录或登录已过期",
+  "data": null
+}
+```
+
+#### 降级/错误
+
+- 无数据 → 空数组，不报错。
+- 未登录 → 401（网关拦截）。
+
+### 2. 团期分页列表 `GET /v3/admin/order/group-batch`（GB-ADM-001）
+
+**使用场景**: 管理后台看板"团期列表"页：分页 + 筛选（阶段桶/月份/关键词）。
+
+#### 入参（新增，均可选）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| opsStage | Query | String | 否 | RECRUIT/FORMED/PENDING_TRIP/TRAVELLING/AUDITING/CHECKED/DISBANDED | 七桶折叠；FORMED=RRESOURCE_PREPARING+MATERIAL_PREPARING 复合桶；未知/空=不过滤 |
+| month | Query | String | 否 | yyyy-MM | 按出发日期所在自然月区间过滤 |
+| keyword | Query | String | 否 | - | 匹配团期编号/名称，服务端 trim+转义 % _ \\（防通配符扩匹配） |
+
+#### 出参（新增字段，分页项）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| receivableAmount | BigDecimal | 应收（批量 sum 实时聚合，非快照） |
+| receivedAmount | BigDecimal | 实收（批量 sum 实时聚合，非快照） |
+| chips | Object | 六芯片键：hotel/vehicle/guide/photo/contract/insurance（#6902 GroupBatchChipResolver 聚合） |
+| orderCount | Integer | 该团期子订单数（批量 in 投影计数，无 N+1） |
+
+#### 请求示例
+
+GET /v3/admin/order/group-batch?pageNo=1&pageSize=5&opsStage=FORMED&month=2026-09&keyword=x
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [],
+    "total": 0
+  }
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 401,
+  "message": "未登录或登录已过期",
+  "data": null
+}
+```
+
+#### 降级/错误
+
+- 无匹配 → records 空数组 total=0。
+- 排序保持 create_time DESC（向后兼容，未做排序变更）。
+
+### 3. 团期详情 `GET /v3/admin/order/group-batch/<groupBatchId>`（GB-ADM-002）
+
+**使用场景**: 看板点击团期看详情：实时金额 + 主报道人。
+
+#### 出参（新增/变更字段）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| totalReceivable | BigDecimal | 应收实时聚合（sumBatchAmountsByProductBatchIds），非恒 0 |
+| totalReceived | BigDecimal | 实收实时聚合，非恒 0 |
+| primaryReporterId/primaryReporterName | Long/String | order_batch_staff 中 reporter_rank=PRIMARY 的首个；无 PRIMARY 配置时 null |
+| secondaryReporterId/Name | Long/String | 副报道人（可 null） |
+| advanceAmount | BigDecimal | 预付款（原字段，语义不变） |
+
+#### 请求示例
+
+GET /v3/admin/order/group-batch/<groupBatchId>
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": null
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 404,
+  "message": "团期不存在或已被删除",
+  "data": null
+}
+```
+
+#### 降级/错误
+
+- 团期不存在 → 业务 404。
+
+### 4. 团期订单列表 `GET /v3/admin/order/group-batch/<groupBatchId>/orders`（GB-ADM-003）
+
+**使用场景**: 看板展开订单列表：成本/tier/人数/房车需求/游客（含旅行内生日、无证件号）。
+
+#### 入参（新增，均可选）
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| includeTravelers | Query | Boolean | 否 | 是否加载游客数组（不传=不加载，零开销） |
+| includeNeeds | Query | Boolean | 否 | 是否加载房车需求做派生聚合 |
+| includeCancelled | Query | Boolean | 否 | 是否包含已取消子订单 |
+
+#### 出参（新增/变更字段，每子订单）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| estimatedCost | BigDecimal | 估算成本（无成本数据可 null） |
+| tierCode/tierName | String | tier 组合（成人A/儿童C/幼童Y/婴儿B，如 2A1C→"2成人1儿童"；全零→null，映射表待 wx 确认） |
+| participantCount | Integer | 人数聚合（adult+child+youngChild+baby） |
+| youngChildCount/babyCount | Integer | 幼童/婴儿数 |
+| roomCount | Integer | 房数=逐晚需求 segment 房间数最大值；无需求行缺省 ceil(人数/2) |
+| roomType | String | 最大房数晚的 roomCategory "、" 连接；无 → null |
+| specialNeeds | String | 需求 special_tags "；" 连接 → 需求行 remark → 缺需求行 customer_remark |
+| contactPhone | String | **全量掩码**（保前 3 后 4） |
+| travelerInfoComplete | Boolean | 游客信息完整（校验服务批量聚合） |
+| travelers | Array | name/type/age/birthdayInTrip；**不含 idNo/phone（编译期字段裁剪 + 运行期零返回）** |
+
+#### 请求示例
+
+GET /v3/admin/order/group-batch/<groupBatchId>/orders?includeTravelers=true&includeNeeds=true&includeCancelled=true
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": []
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 401,
+  "message": "未登录或登录已过期",
+  "data": null
+}
+```
+
+#### 降级/错误
+
+- 无子订单 → 空数组。
+- 证件号/游客手机号永不返回（数据安全边界）。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- 全部新增参数可选；不传 = 旧行为（向后兼容）。
+- `opsStage=FORMED` 代表"资源筹备中+物料筹备中"两态并集（复合桶），不是单一状态值。
+- 金额一律 BigDecimal 字符串（ToStringSerializer 序列化），前端按字符串处理，避免精度丢失。
+- 001 keyword 的 `%_` 会被转义为字面匹配；需要模糊查询请用 `%` 以外的普通字符。
+- 003 的证件号/手机号**不存在于任何响应**，前端不得引用（编译期保证）。
+
+## 五、数据库行为
+
+- 本单**零写操作、零表/列变更、零迁移**；全部为查询层字段/聚合/筛选对齐。
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 资源不存在 → 业务 404
+- 下游（order-stats/requirement）异常降级 → 金额/需求字段 null，不 500 不阻断页面
+- 老数据无新列 → 新增字段 null，不异常
+- 身份证号/手机号 → 永不返回（安全边界）
+
+## 六.5、枚举 / 数据字典
+
+### opsStage（GroupBatchStageBuckets 七桶）
+
+| 值 | 中文 | 折叠状态 |
+|----|------|----------|
+| RECRUIT | 招募中 | (created) |
+| FORMED | 已成团（复合桶） | RESOURCE_PREPARING + MATERIAL_PREPARING |
+| PENDING_TRIP | 待出行 | - |
+| TRAVELLING | 出行中 | - |
+| AUDITING | 待审核 | - |
+| CHECKED | 已审核 | - |
+| DISBANDED | 已解散 | - |
+
+### tierCode 组合（成人A/儿童C/幼童Y/婴儿B）
+
+| 值 | 说明 |
+|----|------|
+| 2A1C | 2 成人 1 儿童（tierName="2成人1儿童"） |
+| 全零 | null（不输出） |
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 接口 | 字段 | 改前 | 改后 |
+|------|------|------|------|
+| 000 | batchCount | 无 | 批量 in 投影计数 |
+| 001 | receivableAmount/receivedAmount | 无（或空） | 实时聚合(2943.00/3270.00 测试实证) |
+| 001 | chips/orderCount | 无 | 六芯片聚合/批量计数 |
+| 002 | totalReceivable/totalReceived | 实体快照 | sumBatchAmounts 实时聚合(非恒 0) |
+| 002 | primaryReporter | 无 | reporter_rank=PRIMARY 批量取值 |
+| 003 | estimatedCost/tier/人数 | 无 | 批量派生 |
+| 003 | contactPhone | 原文 | 全量掩码 |
+| 003 | travelers | 无 | name/type/age/birthdayInTrip（无证件号） |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否（全部新增可选字段/参数）
+- **前端是否必须同步上线**: 否
+- **前端 workaround 清理点**: 无
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台团期看板 4 个查询接口（响应新增字段 + 筛选参数）
+- **零影响**:
+  - C 端 / MP 端接口
+  - 下单/支付/退款链路
+  - 数据库表结构（零迁移）
+  - #6902/#6903/#6904 已合并接口（本单未改其文件，仅顺带合并 dev-v3 时解决 GroupBatchMapper 尾部冲突取并集）
+
+## 验证证据
+
+网关: `https://api.test.1814.love:9443`（`/v3/admin/**` → hl-order-service-v3，dev-v3 @ 47aaff0be，双实例 8086/8186 UP，BUILD SUCCESS 24.6s）
+
+- `GET /v3/admin/order/group-batch?pageNo=1&pageSize=5` → 200 records=5 total=14，receivableAmount=2943.00 receivedAmount=3270.00，chips=hotel/vehicle/guide/photo/contract/insurance，orderCount=1 ✓
+- 筛选实证: base_total=14 → keyword=0 / opsStage(FORMED)=13 / month(2026-09)=12 ✓
+- `GET /v3/admin/order/group-batch/products` → 200 list=6，batchCount>0 产品 4/6（3/3/3/5），regionText=null（上游未提供，预期）✓
+- `GET /v3/admin/order/group-batch/<groupBatchId>` → 200 keys(34)，totalReceivable=2943.00 totalReceived=3270.00（非恒 0）✓，primaryReporterId/Name 字段在位（无 PRIMARY 配置时 null）✓
+- `GET /v3/admin/order/group-batch/<groupBatchId>/orders?includeTravelers=true&includeNeeds=true&includeCancelled=true` → 200 orders=1，tierCode=2A tierName=2成人，roomCount=1，specialNeeds=脚本造单·…，contactPhone=138****0001（掩码）✓，travelerInfoComplete=true ✓，travelers len=2 keys=age,birthdayInTrip,name,type（无 idNo/phone）✓，样本: name=张伟 type=ADULT age=41 birthdayInTrip=false ✓
+
+本地: 定向单测 19+15+27+8+3 全绿；模块全量 7832 用例仅 3 个 refund 401 用例失败且为 dev-v3 基线固有（git stash 对照同结果），与本单无关。
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| #6902 | #6902 | 共享件（chip/stats/buckets） | ✅ 依赖 |
+| #6917 | #6904 | 看板统计条+导出（顺带合并冲突并集） | ✅ 有效 |
+| **#6923** | **#6905** | 本单 4 接口对齐（squash 等价落地 47aaff0be，PR 因网关禁 PUT 已 closed 留痕） | ✅ 最新 |
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#6905](https://git.1814.love:8443/wx/HL/issues/6905)
+- 关联 PR: [wx/HL#6923](https://git.1814.love:8443/wx/HL/pulls/6923)
+- 合并落点: [wx/HL commit 47aaff0be](https://git.1814.love:8443/wx/HL/commit/47aaff0be)（dev-v3）
+- 后续计划: regionText 上游 product-v2 补齐 + 前端展示验收（另行交接）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#6905](https://git.1814.love:8443/wx/HL/issues/6905)
+- **PR**: [#6923](https://git.1814.love:8443/wx/HL/pulls/6923)（closed；网关拦截 PUT，采用等价 squash 推送落地）
+- **Merge commit**: [47aaff0be](https://git.1814.love:8443/wx/HL/commit/47aaff0be)（dev-v3 落点）
+
+### 联系人
+
+- **后端负责人**: @wx