hl-api-changelog/changelogs-v2/2026-09/04_7066_团期子订单列表补应收总额-修改接口-管理后台.md

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

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7066	团期子订单列表补应收总额 totalPrice	admin	jw(GIT)	修改接口	deployed	verified	verified	mmg	8980e197		2026-09-04	PR #7068 已合入 dev-v3（合并提交 e1ad8550b）；2026-09-04 部署测试环境，网关实测 8 组用例全部通过（含取消单归 0）。#7097 复审收敛：应收字段名 totalAmount 未上线即收敛为 totalPrice（#7113 合入 dev-v3 合并提交 11b677198），前端以 totalPrice 为准	2026-09-04	dev-v3

团期子订单: 出参新增应收总额 totalPrice

服务: hl-order-service-v3 PR: #7068 ｜ Issue: #7066 ｜ 合并提交: e1ad8550b 影响范围: 管理后台「团期详情 → 子订单」页签

---

⚠️ 关键变化

前端不要再用 paidAmount + balanceAmount 反推应收总额，改读新增的 totalPrice。

字段名收敛说明（#7097）：本单初版字段名 totalAmount，与 #6929 已在 003 接口下发的 totalPrice 构成同义双字段；复审 #7097 在未上线前收敛为 totalPrice，totalAmount 已移除。本 changelog 全文按收敛后字段名 totalPrice 表述，字段语义与两位小数格式不变。

旧反推在两种场景下偏大：

1. balanceAmount 被钳在 ≥0（OrderAmountUtil.calcBalance 末行），超付或退款后已付大于应收时反推值偏大
2. 已取消子订单 calcBalance 直接返 0，反推得到的是已付而非应收

这不是理论风险：2026-09-04 测试环境实测，现存子订单 paidAmount=3270.00、balanceAmount=0.00， 而真实应收 totalPrice=2943.00——旧算法多显示 327.00。

---

一、背景

团期详情「子订单」页签每张卡片显示「已付 / 应收总额」，但列表接口出参此前没有应收总额字段， 前端只能自行反推。本次补齐该字段，口径与订单域既有展示口径统一。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	团期下子订单列表	GET	/v3/admin/order/group-batch/:groupBatchId/orders	出参新增字段	新增 totalPrice 应收总额

---

三、接口详情

1. 团期下子订单列表 GET /v3/admin/order/group-batch/:groupBatchId/orders

VO: GroupBatchOrderItemRespVO

使用场景

团期详情「子订单」页签加载时调用，渲染每户卡片。卡片右下角「已付 ¥X / ¥Y」中的 Y 即本次新增的 totalPrice。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	—	运营团期 ID（订单侧 order_group_batch 主键）
includeTravelers	Query	Boolean	❌	缺省 false	附出行人明细，证件号一律不返回
includeNeeds	Query	Boolean	❌	缺省 false	附房数 / 房型 / 特殊需求
includeCancelled	Query	Boolean	❌	缺省 false	是否含已取消子订单，缺省只返活跃集

出参 Result<List<GroupBatchOrderItemRespVO>>

本次仅新增一个字段，其余 28 个字段不变：

字段	类型	说明
totalPrice	String	本次新增。应收总额 = orderAmount + 增项 − 优惠；已取消子订单归 0。2 位小数，字符串输出
paidAmount	String	已支付金额（未变）
balanceAmount	String	待支付尾款，钳在 ≥0（未变）

三个金额字段均带 @JsonSerialize(ToStringSerializer)，JSON 里是字符串，前端直接解析为数字会有精度风险，应按字符串处理或用高精度解析。

请求示例

GET /v3/admin/order/group-batch/2089713777065832450/orders

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": [
    {
      "orderId": 2094597053924487170,
      "customerName": "6915验收造单01",
      "orderStatus": "CUSTOMIZING",
      "orderStatusName": "定制中",
      "adultCount": 2,
      "childCount": 0,
      "participantCount": 2,
      "contactPhone": "138****0001",
      "paidAmount": "3270.00",
      "balanceAmount": "0.00",
      "totalPrice": "2943.00"
    }
  ]
}

空数据 / 降级响应

团期下无子订单时返回空数组，不报错：

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": []
}

错误响应

未携带管理端令牌：

{
  "code": 401,
  "message": "缺少有效的 Authorization 头",
  "success": false,
  "data": null
}

业务边界

• 只读接口，不产生任何写入
• totalPrice 不等于 paidAmount + balanceAmount，超付、退款、取消单三种情况下都会不等
• 已取消子订单（includeCancelled=true 才可见）的 totalPrice 与 balanceAmount 同为 0，闭合财务勾稽
• 金额一律 2 位小数（HALF_UP），与订单域其他接口格式一致

---

四、契约约束与正确调用方式

• 应收总额一律读 totalPrice，不要自行用 paidAmount + balanceAmount 计算。
• totalPrice 与 balanceAmount 是不同语义：前者是「客户总共该付多少」，后者是「现在还差多少」。已付清时后者为 0，前者仍是原值。
• 三个金额字段是 JSON 字符串，不是数字。
• 取消单场景下 totalPrice 归 0 是有意设计（对齐 calcBalance 的取消单归 0），用于闭合「应收 0 / 已付 0 / 已退 0 / 待收 0」的勾稽链，不是缺陷。

---

五、数据库行为

本接口只读，不产生任何写入，也不涉及表结构调整。totalPrice 由既有字段实时计算，不新增存储列。

---

六、边界行为

• 超付单 → totalPrice 为真实应收，小于 paidAmount
• 取消单 → totalPrice 归 0
• 团期无子订单 → 返回 []
• 未登录 → 401（网关拦截）

---

六.5、枚举 / 数据字典

本次无新增枚举。

---

六.6、修改前后对比

项	变更前	变更后
出参字段数	28	29
应收总额	无字段，前端用 paidAmount + balanceAmount 反推	新增 totalPrice，服务端按既有 payableForDisplay 口径给出
超付单显示	反推值偏大（实测多 327.00）	totalPrice 为真实应收
取消单显示	反推得到已付金额，非应收	totalPrice 归 0，与 balanceAmount 一致
paidAmount / balanceAmount	—	语义与取值均不变
路径 / 入参	—	不变

六.7、影响评估

维度	评估
兼容性	纯 additive，老调用方不读新字段即无感，无破坏性变更
前端	需改为读 totalPrice；不改也不会报错，但超付 / 取消单场景显示值偏大
数据	无 DDL、无迁移、无回填；totalPrice 实时计算不落库
性能	无额外查询，复用同一 OrderInfo 实体计算，零新增 IO
回滚	移除字段即可，无数据侧残留
风险	低。口径复用 AdjustmentService 已在生产使用的既有方法，未新造公式

七、不影响范围

• 零影响：paidAmount / balanceAmount 的现有语义与取值
• 零影响：其余 28 个出参字段
• 零影响：老调用方——纯新增字段，不读即无感
• 未新建端点，未改动路径与入参

---

八、测试环境已验证

✅ 2026-09-04 于测试环境网关实测，真实鉴权（管理端 admin）。

• 网关 https://api.test.1814.love，分支 dev-v3，合并提交 e1ad8550b
• 部署方式：双实例滚动更新（8186 → 8086），各 11s 就绪，零停机

#	用例	期望	实测
1	字段上线	出参含 totalPrice	✅ 字段数 27 → 29
2	真实数据口径	totalPrice 为真实应收	✅ 2943.00；旧反推得 3270.00，偏差 327.00
3	序列化格式	字符串、2 位小数	✅ "totalPrice":"2943.00"
4	includeCancelled=true	正常返回	✅ 返回 1 条
5	无 Authorization	401	✅ 401 缺少有效的 Authorization 头
6	老字段回归	未受影响	✅ 8 个字段逐一核对一致
7	缺省过滤取消单	取消单不出现	✅ GET .../orders 返回 0 条
8	取消单归 0	totalPrice = 0 且与 balanceAmount 一致	✅ totalPrice="0.00"、balanceAmount="0.00"、paidAmount="3270.00"

部署前基线对照：同一接口部署前出参 27 字段、无 totalPrice，确认变更确实生效。

本地单测：GroupBatchConverterTest 新增 5 例（正常单 / 含增项优惠 / 超付单断言反推不等 / 取消单归 0 / 2 位小数）； 本地全量 750 例全过。

取消单分支已实测（用例 7–8）：验收期间该子订单被退单，恰好提供了取消单样本。 实测 totalPrice="0.00"，而 paidAmount="3270.00"——旧算法 paidAmount + balanceAmount 会把一条 已取消的子订单显示成「应收 3270」，真实应收应为 0。本字段同时修正了这一场景。

全部 8 组用例通过，无遗留未验分支。

---

九、相关历史 PR

• #7068 本次变更
• 口径来源：OrderAmountUtil.payableForDisplay（#4456 展示用应收总额，取消单归 0）
• 相关：#5733（calcBalance 改为退款冲减应收）、#2896 P1-3（金额统一 2 位小数）

---

十、相关文档

• 团期需求文档：docs/group/（dev-v3 分支）
• 3 天开发计划：docs/group/团期模块3天开发计划.md

---

关联 / 联系人

• Issue: #7066
• PR: #7068（合并提交 e1ad8550b）
• 服务: hl-order-service-v3
• 后端: jw
• 前端: 待认领（frontend_status: pending）