docs(changelog): 团期核单详情对齐常规订单核单——reports/group 出参新增 21 字段（#8510）

聚合复核 GET /v3/admin/order/group-batch/{id}/settlement/reports/group 出参对齐常规订单核单财务总览：新增 11 金额字段 + 4 个 mirrorMatched + customers 客户合并列表 + 6 个人数汇总字段，数据从单订单换成全团在团子订单合并（排除已取消），待收尾款与 /finance 同源。管理后台目录 changelogs-v2/，关联 PR #8546。
2026-09-30 00:12:44 +08:00
@@ -0,0 +1,231 @@
+---
+frontend_owner: ""
+frontend_ref: ""
+verified_at: "2026-09-30"
+---
+
+# 团期核单详情对齐常规订单核单 —— 修改接口（管理后台）
+
+> Issue: https://git.1814.love/wx/HL/issues/8510
+> PR: https://git.1814.love/wx/HL/pulls/8546
+> Commit: https://git.1814.love/wx/HL/commit/306f9873d30a567331afed12b91c45af176418bf
+> 负责人：腰苏图
+
+---
+
+## 1. 接口背景
+
+团期核单（一团一核单）的「聚合复核」接口此前只返回团级汇总快照（订单总额/已收/欠收），与常规订单核单详情的财务总览结构不一致，缺线上/线下拆分、主报账人代收、客户合并信息、人数分档等字段，前端无法像常规订单核单一样渲染完整详情。
+
+本次把团期核单的财务总览**完全对齐常规订单核单**：字段平铺结构与常规订单 `SettlementFinancialOverviewRespVO` 一致，唯一区别是**数据来源从单个订单换成全团所有在团子订单合并**（排除已取消子订单）。
+
+---
+
+## 2. 变更清单
+
+| 类型 | 接口 | 说明 |
+|---|---|---|
+| 修改 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/reports/group` | 出参 `GroupSettlementRespVO` 新增 21 个字段（11 金额字段 + 4 mirrorMatched + customers 客户合并列表 + 6 人数汇总字段） |
+
+入参无变化；无字段删除、无类型变更、无枚举变更。纯**出参新增字段**，前端旧逻辑可继续按原字段渲染，新字段为增强。
+
+---
+
+## 3. 接口详情
+
+- **方法/路径**：`GET /v3/admin/order/group-batch/{groupBatchId}/settlement/reports/group`
+- **鉴权**：管理后台登录（与团期核单录入同权限）
+- **说明**：团期核单聚合复核详情。`finalized=false`（未结算）时同样实时装配财务总览，字段照常返回。
+
+---
+
+## 4. 入参
+
+无变化。路径参数 `groupBatchId`（团期 ID，Long）。
+
+---
+
+## 5. 出参
+
+在原有团级汇总字段基础上，**新增**以下字段（与常规订单核单财务总览同口径、同平铺风格）。所有金额为 `BigDecimal`，货币单位元；缺省时返回 `0`（不返回 null）。
+
+### 5.1 金额字段（11 个，全团在团子订单合并求和）
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `baseOrderAmount` | BigDecimal | 订单基础金额合计（Σ 各户 order_amount） |
+| `otherIncomeAmount` | BigDecimal | 有效增费合计（Σ 各户 surcharge_amount） |
+| `discountAmount` | BigDecimal | 有效优惠合计（Σ 各户 discount_amount） |
+| `adjustedReceivableAmount` | BigDecimal | 调整后应收 = Σ 各户 calcPayable = order + surcharge − discount |
+| `onlinePaidAmount` | BigDecimal | 成功线上支付合计（权威源，Σ 各户成功线上交易） |
+| `offlinePaidAmount` | BigDecimal | 有效线下收款合计（权威源，Σ 各户有效手工收款） |
+| `primaryReporterCollectedAmount` | BigDecimal | 各户主报账人（DRIVER_CASH 渠道）代收合计；仅展示，已包含在 `offlinePaidAmount` 内 |
+| `paidAmount` | BigDecimal | 已收合计（镜像口径 Σ 各户 paid_amount，与 outstanding 同源） |
+| `actualRefundedAmount` | BigDecimal | 实际退款合计（镜像口径 Σ 各户 refunded_amount） |
+| `netPaidAmount` | BigDecimal | 净已收 = paidAmount − actualRefundedAmount |
+| `outstandingAmount` | BigDecimal | **待收尾款** = Σ 各户 calcBalance（= calcPayable − refunded − paid，已取消恒 0、下限 0），与 `/finance` 应收台账同源 |
+
+### 5.2 镜像校验位（4 个）
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `surchargeMirrorMatched` | Boolean | 增费镜像是否匹配权威明细（数据质量信号，仅供内部核查） |
+| `discountMirrorMatched` | Boolean | 优惠镜像是否匹配权威明细 |
+| `paidMirrorMatched` | Boolean | 已收镜像是否匹配权威明细 |
+| `refundedMirrorMatched` | Boolean | 退款镜像是否匹配权威明细（**仅对拍已退完成 REFUNDED 口径**，在途退款不计，避免在途期间恒 false） |
+
+> 前端一般不需要展示这 4 个字段，它们是给后端/排查用的数据质量信号。
+
+### 5.3 客户合并信息 `customers`
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `customers` | `List<GroupSettlementCustomerItemVO>` | 全团在团子订单的客户信息，一户一行 |
+
+**GroupSettlementCustomerItemVO**（一户一行）：
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `orderId` | String | 子订单 ID（Long 序列化为字符串，防 JS 精度丢失） |
+| `orderNo` | String | 子订单号 |
+| `teamNo` | String | 子订单团内编号（如有） |
+| `customerName` | String | 联系人姓名（**明文**，与团期财务列表现状一致） |
+| `customerPhone` | String | 联系人手机号（**已脱敏**，如 `138****5678`） |
+| `travelerCount` | Integer | 该户人数（含婴儿） |
+
+### 5.4 人数汇总（6 个，含婴儿统一口径）
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `householdCount` | Integer | 在团户数（排除已取消子订单） |
+| `travelerCount` | Integer | 总人数 = adult + child + youngChild + **baby** |
+| `adultCount` | Integer | 成人数 |
+| `childCount` | Integer | 儿童数 |
+| `youngChildCount` | Integer | 幼儿数 |
+| `babyCount` | Integer | 婴儿数 |
+
+---
+
+## 6. 枚举 / 数据字典
+
+无新增枚举。本接口不复用订单状态枚举，全部为金额/客户/人数字段。
+
+---
+
+## 7. 错误码
+
+无新增错误码。复用团期域既有错误码（如团期不存在返回对应业务错误）。
+
+---
+
+## 8. 示例
+
+### 8.1 典型（已结算团，finalized=true）
+
+```json
+{
+  "code": 0,
+  "data": {
+    "groupBatchId": "123",
+    "finalized": true,
+    "baseOrderAmount": 12800.00,
+    "otherIncomeAmount": 600.00,
+    "discountAmount": 300.00,
+    "adjustedReceivableAmount": 13100.00,
+    "onlinePaidAmount": 8000.00,
+    "offlinePaidAmount": 2600.00,
+    "primaryReporterCollectedAmount": 1200.00,
+    "paidAmount": 10600.00,
+    "actualRefundedAmount": 0.00,
+    "netPaidAmount": 10600.00,
+    "outstandingAmount": 2500.00,
+    "surchargeMirrorMatched": true,
+    "discountMirrorMatched": true,
+    "paidMirrorMatched": true,
+    "refundedMirrorMatched": true,
+    "householdCount": 2,
+    "travelerCount": 6,
+    "adultCount": 4,
+    "childCount": 1,
+    "youngChildCount": 0,
+    "babyCount": 1,
+    "customers": [
+      {
+        "orderId": "9001",
+        "orderNo": "HL20260901001",
+        "teamNo": "A1",
+        "customerName": "张三",
+        "customerPhone": "138****5678",
+        "travelerCount": 3
+      },
+      {
+        "orderId": "9002",
+        "orderNo": "HL20260901002",
+        "teamNo": "A2",
+        "customerName": "李四",
+        "customerPhone": "139****1234",
+        "travelerCount": 3
+      }
+    ]
+  }
+}
+```
+
+### 8.2 边界（未结算团，finalized=false，字段照常返回）
+
+未结算（团期未 finalize）时，财务总览字段仍**实时装配**返回（金额字段/客户列表/人数照常），`finalized=false`，无快照段。前端可直接用同一套字段渲染，无需区分。
+
+### 8.3 异常（团期不存在）
+
+```json
+{
+  "code": 5xxxxx,
+  "msg": "团期不存在"
+}
+```
+
+---
+
+## 9. 业务边界
+
+- **数据范围**：金额与客户合并**只统计在团子订单**，**排除已取消（CANCELLED）子订单**。已取消订单的金额不计入任何合计。
+- **待收尾款口径**：`outstandingAmount` 与 `/finance` 应收台账 `totalPendingBalance` 同源（都是 Σ calcBalance，含实退、下限 0），两端数值可对拍一致。
+- **主报账人代收**：`primaryReporterCollectedAmount` 仅展示用，其金额已包含在 `offlinePaidAmount` 中，**不要重复加总**。
+- **手机号**：`customerPhone` 已脱敏；`customerName` 明文（管理后台财务查看权限内，与团期财务列表现状一致）。
+
+---
+
+## 10. 修改前后对比（修改类）
+
+| 维度 | 修改前 | 修改后 |
+|---|---|---|
+| 出参结构 | 仅团级汇总快照（订单总额/已收/欠收等粗粒度） | 新增 21 字段：11 金额 + 4 mirrorMatched + customers + 6 人数，与常规订单核单财务总览同结构 |
+| 线上/线下拆分 | 无 | 有（onlinePaidAmount / offlinePaidAmount / primaryReporterCollectedAmount） |
+| 待收尾款 | 无（前端需自行用「应收−已付」硬减，未扣实退口径错误） | 有（outstandingAmount，与 /finance 同源，口径正确） |
+| 客户信息 | 无 | 有（customers 一户一行，含脱敏手机号） |
+| 人数 | 无 | 有（含婴儿 6 个分档汇总） |
+
+---
+
+## 11. 影响评估 / 回滚（修改类）
+
+- **兼容性**：纯出参新增字段，前端按原字段渲染不受影响；新字段为增强，可渐进接入。
+- **性能**：单团装配固定 9 次查询封顶（无 N+1），空团短路；金额内存聚合，性能可控。
+- **回滚**：回退本次 merge commit 即可恢复原出参；新字段无持久化、无 DDL，回滚无数据迁移成本。
+
+---
+
+## 12. 注意事项
+
+1. 新字段**实时装配**，不读快照表；`finalized=false` 时也照常返回。
+2. `paidAmount` / `actualRefundedAmount` 是 order_main 镜像口径（用于与 outstanding 同源自洽），线上/线下拆分走权威源——两者求和理论上应等于 `netPaidAmount` 相关口径，差异会体现在 `paidMirrorMatched` 校验位。
+3. 本 PR 是团期核单详情对齐的 **PR-1（财务总览 + 客户合并 + 人数口径）**；后续 **PR-2** 还会补多 tab 明细（step1 住宿/step2 门票/step3 车辆/导游/摄影/餐食/其他收入/其他支出/返还），届时另行推 changelog。
+
+---
+
+## 13. 关联 / 联系人
+
+- Issue: https://git.1814.love/wx/HL/issues/8510
+- PR: https://git.1814.love/wx/HL/pulls/8546
+- Commit: https://git.1814.love/wx/HL/commit/306f9873d30a567331afed12b91c45af176418bf
+- 负责人：腰苏图