更正 #7097 收敛：04_7066 应收字段以 totalPrice 为准（totalAmount 未上线即收敛）；6905 取消单 totalPrice 返 0.00 两位小数（#7097 复审）
changelog-filename-gate / validate (push) Successful in 2s
changelog-filename-gate / validate (push) Successful in 2s
这个提交包含在：
API Changelog Bot
@@ -1,7 +1,7 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "7066"
|
||||
title: "团期子订单列表补应收总额 totalAmount"
|
||||
title: "团期子订单列表补应收总额 totalPrice"
|
||||
consumer: "admin"
|
||||
author: "jw(GIT)"
|
||||
change_type: "修改接口"
|
||||
@@ -12,12 +12,12 @@ frontend_owner: ""
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: "2026-09-04"
|
||||
status_note: "PR #7068 已合入 dev-v3（合并提交 e1ad8550b）；2026-09-04 部署测试环境，网关实测 8 组用例全部通过（含取消单归 0）"
|
||||
status_note: "PR #7068 已合入 dev-v3（合并提交 e1ad8550b）；2026-09-04 部署测试环境，网关实测 8 组用例全部通过（含取消单归 0）。#7097 复审收敛：应收字段名 totalAmount 未上线即收敛为 totalPrice（#7113 合入 dev-v3 合并提交 11b677198），前端以 totalPrice 为准"
|
||||
updated_at: "2026-09-04"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
# 团期子订单: 出参新增应收总额 totalAmount
|
||||
# 团期子订单: 出参新增应收总额 totalPrice
|
||||
|
||||
> **服务**: hl-order-service-v3
|
||||
> **PR**: #7068 ｜ **Issue**: #7066 ｜ **合并提交**: `e1ad8550b`
|
||||
@@ -27,7 +27,9 @@ base: "dev-v3"
|
||||
|
||||
## ⚠️ 关键变化
|
||||
|
||||
**前端不要再用 `paidAmount + balanceAmount` 反推应收总额，改读新增的 `totalAmount`。**
|
||||
**前端不要再用 `paidAmount + balanceAmount` 反推应收总额，改读新增的 `totalPrice`。**
|
||||
|
||||
> **字段名收敛说明（#7097）**：本单初版字段名 `totalAmount`，与 #6929 已在 003 接口下发的 `totalPrice` 构成同义双字段；复审 #7097 在未上线前收敛为 `totalPrice`，`totalAmount` 已移除。本 changelog 全文按收敛后字段名 `totalPrice` 表述，字段语义与两位小数格式不变。
|
||||
|
||||
旧反推在两种场景下**偏大**：
|
||||
|
||||
@@ -35,7 +37,7 @@ base: "dev-v3"
|
||||
2. 已取消子订单 `calcBalance` 直接返 0，反推得到的是已付而非应收
|
||||
|
||||
**这不是理论风险**：2026-09-04 测试环境实测，现存子订单 `paidAmount=3270.00`、`balanceAmount=0.00`，
|
||||
而真实应收 `totalAmount=2943.00`——**旧算法多显示 327.00**。
|
||||
而真实应收 `totalPrice=2943.00`——**旧算法多显示 327.00**。
|
||||
|
||||
---
|
||||
|
||||
@@ -50,7 +52,7 @@ base: "dev-v3"
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||
|---|------|------|------|----------|------|
|
||||
| 1 | 团期下子订单列表 | GET | `/v3/admin/order/group-batch/:groupBatchId/orders` | **出参新增字段** | 新增 `totalAmount` 应收总额 |
|
||||
| 1 | 团期下子订单列表 | GET | `/v3/admin/order/group-batch/:groupBatchId/orders` | **出参新增字段** | 新增 `totalPrice` 应收总额 |
|
||||
|
||||
---
|
||||
|
||||
@@ -62,7 +64,7 @@ base: "dev-v3"
|
||||
|
||||
#### 使用场景
|
||||
|
||||
团期详情「子订单」页签加载时调用，渲染每户卡片。卡片右下角「已付 ¥X / ¥Y」中的 Y 即本次新增的 `totalAmount`。
|
||||
团期详情「子订单」页签加载时调用，渲染每户卡片。卡片右下角「已付 ¥X / ¥Y」中的 Y 即本次新增的 `totalPrice`。
|
||||
|
||||
#### 入参
|
||||
|
||||
@@ -79,7 +81,7 @@ base: "dev-v3"
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `totalAmount` | String | **本次新增**。应收总额 = `orderAmount + 增项 − 优惠`；**已取消子订单归 0**。2 位小数，字符串输出 |
|
||||
| `totalPrice` | String | **本次新增**。应收总额 = `orderAmount + 增项 − 优惠`；**已取消子订单归 0**。2 位小数，字符串输出 |
|
||||
| `paidAmount` | String | 已支付金额（未变） |
|
||||
| `balanceAmount` | String | 待支付尾款，**钳在 ≥0**（未变） |
|
||||
|
||||
@@ -110,7 +112,7 @@ GET /v3/admin/order/group-batch/2089713777065832450/orders
|
||||
"contactPhone": "138****0001",
|
||||
"paidAmount": "3270.00",
|
||||
"balanceAmount": "0.00",
|
||||
"totalAmount": "2943.00"
|
||||
"totalPrice": "2943.00"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -145,31 +147,31 @@ GET /v3/admin/order/group-batch/2089713777065832450/orders
|
||||
#### 业务边界
|
||||
|
||||
- 只读接口，不产生任何写入
|
||||
- `totalAmount` **不等于** `paidAmount + balanceAmount`，超付、退款、取消单三种情况下都会不等
|
||||
- 已取消子订单（`includeCancelled=true` 才可见）的 `totalAmount` 与 `balanceAmount` 同为 0，闭合财务勾稽
|
||||
- `totalPrice` **不等于** `paidAmount + balanceAmount`，超付、退款、取消单三种情况下都会不等
|
||||
- 已取消子订单（`includeCancelled=true` 才可见）的 `totalPrice` 与 `balanceAmount` 同为 0，闭合财务勾稽
|
||||
- 金额一律 2 位小数（HALF_UP），与订单域其他接口格式一致
|
||||
|
||||
---
|
||||
|
||||
## 四、契约约束与正确调用方式
|
||||
|
||||
- **应收总额一律读 `totalAmount`**，不要自行用 `paidAmount + balanceAmount` 计算。
|
||||
- **`totalAmount` 与 `balanceAmount` 是不同语义**：前者是「客户总共该付多少」，后者是「现在还差多少」。已付清时后者为 0，前者仍是原值。
|
||||
- **应收总额一律读 `totalPrice`**，不要自行用 `paidAmount + balanceAmount` 计算。
|
||||
- **`totalPrice` 与 `balanceAmount` 是不同语义**：前者是「客户总共该付多少」，后者是「现在还差多少」。已付清时后者为 0，前者仍是原值。
|
||||
- **三个金额字段是 JSON 字符串**，不是数字。
|
||||
- 取消单场景下 `totalAmount` 归 0 是**有意设计**（对齐 `calcBalance` 的取消单归 0），用于闭合「应收 0 / 已付 0 / 已退 0 / 待收 0」的勾稽链，不是缺陷。
|
||||
- 取消单场景下 `totalPrice` 归 0 是**有意设计**（对齐 `calcBalance` 的取消单归 0），用于闭合「应收 0 / 已付 0 / 已退 0 / 待收 0」的勾稽链，不是缺陷。
|
||||
|
||||
---
|
||||
|
||||
## 五、数据库行为
|
||||
|
||||
本接口只读，**不产生任何写入**，也不涉及表结构调整。`totalAmount` 由既有字段实时计算，不新增存储列。
|
||||
本接口只读，**不产生任何写入**，也不涉及表结构调整。`totalPrice` 由既有字段实时计算，不新增存储列。
|
||||
|
||||
---
|
||||
|
||||
## 六、边界行为
|
||||
|
||||
- 超付单 → `totalAmount` 为真实应收，小于 `paidAmount`
|
||||
- 取消单 → `totalAmount` 归 0
|
||||
- 超付单 → `totalPrice` 为真实应收，小于 `paidAmount`
|
||||
- 取消单 → `totalPrice` 归 0
|
||||
- 团期无子订单 → 返回 `[]`
|
||||
- 未登录 → 401（网关拦截）
|
||||
|
||||
@@ -186,9 +188,9 @@ GET /v3/admin/order/group-batch/2089713777065832450/orders
|
||||
| 项 | 变更前 | 变更后 |
|
||||
|---|---|---|
|
||||
| 出参字段数 | 28 | **29** |
|
||||
| 应收总额 | **无字段**，前端用 `paidAmount + balanceAmount` 反推 | 新增 `totalAmount`，服务端按既有 `payableForDisplay` 口径给出 |
|
||||
| 超付单显示 | 反推值偏大（实测多 327.00） | `totalAmount` 为真实应收 |
|
||||
| 取消单显示 | 反推得到已付金额，非应收 | `totalAmount` 归 0，与 `balanceAmount` 一致 |
|
||||
| 应收总额 | **无字段**，前端用 `paidAmount + balanceAmount` 反推 | 新增 `totalPrice`，服务端按既有 `payableForDisplay` 口径给出 |
|
||||
| 超付单显示 | 反推值偏大（实测多 327.00） | `totalPrice` 为真实应收 |
|
||||
| 取消单显示 | 反推得到已付金额，非应收 | `totalPrice` 归 0，与 `balanceAmount` 一致 |
|
||||
| `paidAmount` / `balanceAmount` | — | **语义与取值均不变** |
|
||||
| 路径 / 入参 | — | **不变** |
|
||||
|
||||
@@ -197,8 +199,8 @@ GET /v3/admin/order/group-batch/2089713777065832450/orders
|
||||
| 维度 | 评估 |
|
||||
|---|---|
|
||||
| 兼容性 | **纯 additive**，老调用方不读新字段即无感，无破坏性变更 |
|
||||
| 前端 | 需改为读 `totalAmount`；不改也不会报错，但超付 / 取消单场景显示值偏大 |
|
||||
| 数据 | 无 DDL、无迁移、无回填；`totalAmount` 实时计算不落库 |
|
||||
| 前端 | 需改为读 `totalPrice`；不改也不会报错，但超付 / 取消单场景显示值偏大 |
|
||||
| 数据 | 无 DDL、无迁移、无回填；`totalPrice` 实时计算不落库 |
|
||||
| 性能 | 无额外查询，复用同一 `OrderInfo` 实体计算，零新增 IO |
|
||||
| 回滚 | 移除字段即可，无数据侧残留 |
|
||||
| 风险 | 低。口径复用 `AdjustmentService` 已在生产使用的既有方法，未新造公式 |
|
||||
@@ -221,22 +223,22 @@ GET /v3/admin/order/group-batch/2089713777065832450/orders
|
||||
|
||||
| # | 用例 | 期望 | 实测 |
|
||||
|---|---|---|---|
|
||||
| 1 | 字段上线 | 出参含 `totalAmount` | ✅ 字段数 27 → 29 |
|
||||
| 2 | 真实数据口径 | `totalAmount` 为真实应收 | ✅ `2943.00`；旧反推得 `3270.00`，**偏差 327.00** |
|
||||
| 3 | 序列化格式 | 字符串、2 位小数 | ✅ `"totalAmount":"2943.00"` |
|
||||
| 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** | `totalAmount = 0` 且与 `balanceAmount` 一致 | ✅ `totalAmount="0.00"`、`balanceAmount="0.00"`、`paidAmount="3270.00"` |
|
||||
| 8 | **取消单归 0** | `totalPrice = 0` 且与 `balanceAmount` 一致 | ✅ `totalPrice="0.00"`、`balanceAmount="0.00"`、`paidAmount="3270.00"` |
|
||||
|
||||
**部署前基线对照**：同一接口部署前出参 27 字段、无 `totalAmount`，确认变更确实生效。
|
||||
**部署前基线对照**：同一接口部署前出参 27 字段、无 `totalPrice`，确认变更确实生效。
|
||||
|
||||
**本地单测**：`GroupBatchConverterTest` 新增 5 例（正常单 / 含增项优惠 / **超付单断言反推不等** / **取消单归 0** / 2 位小数）；
|
||||
本地全量 **750 例全过**。
|
||||
|
||||
**取消单分支已实测**（用例 7–8）：验收期间该子订单被退单，恰好提供了取消单样本。
|
||||
实测 `totalAmount="0.00"`，而 `paidAmount="3270.00"`——**旧算法 `paidAmount + balanceAmount` 会把一条
|
||||
实测 `totalPrice="0.00"`，而 `paidAmount="3270.00"`——**旧算法 `paidAmount + balanceAmount` 会把一条
|
||||
已取消的子订单显示成「应收 3270」，真实应收应为 0**。本字段同时修正了这一场景。
|
||||
|
||||
全部 8 组用例通过，无遗留未验分支。
|
||||
|
||||
在新工单中引用
屏蔽一个用户