wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
92fb65fe68be426ffb0cad72841a11aa58972ee6
hl-api-changelog/changelogs-v2/2026-09/29_8510_团期核单详情对齐常规订单核单-修改接口-管理后台.md
T
Mimingguang 92fb65fe68
changelog-filename-gate / validate (push) Failing after 1s
详情
docs(changelog): #8510 团期核单 21 字段回写 implemented(hl-admin@a997595a)
2026-09-30 13:51:42 +08:00

11 KiB
原始文件 Blame 文件历史

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 a997595a118cd8aff50e3e316abf8c5eb067413e 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 字段表接入团期核单详情财务总览区（与常规订单核单同一套渲染）。前端已交付:GroupSettlementPanel 收款总览(实时)+客户与人数 6 档+customers 一户一行,未部署 key 缺失整块隐藏。

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

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. 关联 / 联系人

在新工单中引用 查看 Git Blame 复制永久链接