---
schema: "hl-changelog/v2"
ticket: "8510"
title: "团期核单聚合复核 reports/group 出参新增 21 字段，对齐常规订单核单财务总览"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "required"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "hl-admin"
frontend_ref: "8f1c982b831ae11b0bd9783f812ca0ecf4dcb90d"
target_release: "v2.1"
verified_at: "2026-09-30"
base: "dev-v3"
updated_at: "2026-09-30"
status_note: "团期核单「聚合复核」GET /v3/admin/order/group-batch/{groupBatchId}/settlement/reports/group 出参 GroupSettlementRespVO 新增 21 个字段（11 金额字段 + 4 个 mirrorMatched + customers 客户合并列表 + 6 个人数汇总字段），结构与常规订单核单财务总览完全对齐，唯一区别是数据从单订单换成全团在团子订单合并（排除已取消）。关键：待收尾款 outstandingAmount 与 /finance 应收台账同源，前端不要再自行用「应收−已付」硬减；primaryReporterCollectedAmount 已含在 offlinePaidAmount 内勿重复加总。后端已合并待部署，部署后行为验证。前端可按 §5 字段表接入团期核单详情财务总览区（与常规订单核单同一套渲染）。前端已交付:收款总览(实时)11 金额+客户与人数 6 档+customers 一户一行,未部署 key 缺失整块隐藏;2026-09-30 拍板改独立详情页 /finance/settlement/group/:id(骨架对齐常规核单详情两步流程,核单录入 AuditTab+聚合复核 finalize/confirm),行弹层与 GroupSettlementPanel 已删。"
---

# 团期核单详情对齐常规订单核单 —— 修改接口（管理后台）

> 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
- 负责人：腰苏图