hl-api-changelog/changelogs-v2/2026-09/29_8510_团期核单详情对齐常规订单核单-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, base, updated_at, status_note

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	base	updated_at	status_note
hl-changelog/v2	8510	团期核单聚合复核 reports/group 出参新增 21 字段，对齐常规订单核单财务总览	admin	yst(GIT)	修改接口	required	not_required	implemented	hl-admin	8f1c982b831ae11b0bd9783f812ca0ecf4dcb90d	v2.1	2026-09-30	dev-v3	2026-09-30	团期核单「聚合复核」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: wx/HL#8510 PR: wx/HL#8546 Commit: 306f9873d3 负责人：腰苏图

---

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）

{
  "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 异常（团期不存在）

{
  "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: wx/HL#8510
• PR: wx/HL#8546
• Commit: 306f9873d3
• 负责人：腰苏图