docs(changelog): #8533 团期详情已预支改为与财务 Tab 同源（修改接口·管理后台）

Refs wx/HL#8533 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 19:29:15 +08:00
@@ -0,0 +1,194 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8533"
+title: "团期详情（A2）出参 advanceAmount（已预支）改为与财务 Tab advanceApproved 同源——不再读 #7154 起已停写的旧列"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "A2 团期详情的 advanceAmount（已预支金额·累计）原先直读 order_group_batch.advance_amount。该列自 #7154（团期预支改为 order_advance 逐笔台账 + 实时聚合）起已无写入点：新团期永远 0；#7154 之前就有预支的老团期停在 V20260906_004 期初结转那一刻；且旧列只累加团期级、从不含子订单级。于是同一团期 A2 与财务 Tab（GB-ADM-040）advanceApproved 可以是两个数。本次 A2 改为与财务 Tab 调同一对方法（GroupBatchAdvanceQueryService.listActiveSubOrderIds + sumApproved），两位小数，字符串逐字一致。路径、入参、出参字段名与类型零变化；变的是 advanceAmount 的取值口径（旧列快照 → 团期级 ∪ 子订单级 APPROVED 实时聚合），属「语义取值」变化，按 jw 2026-09-18 口径推送。已合并 dev-v3（PR #8539，merge commit 27409a3f1）并部署测试服。hl-ui v2.1 团期详情页未渲染 advanceAmount（已预支卡在 FinanceTab 读 advanceApproved），前端零改动，frontend_status 记 not_required。PAID 不计入是 g-081 的既有口径（09-28 定暂不处理），本次只对齐来源、不改口径。"
+updated_at: "2026-09-29"
+base: "dev-v3"
+---
+
+# 团期详情（A2）已预支改为与财务 Tab 同源（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+
+## 一、接口背景
+
+团期详情（A2）的 `advanceAmount`「已预支金额（累计）」与财务 Tab（GB-ADM-040）的 `advanceApproved`「已预支」本应是同一个数，
+但两者读的来源不同：A2 直读 `order_group_batch.advance_amount` 列，财务 Tab 实时汇总 `order_advance`。
+
+`advance_amount` 列从 #7154 起就没有写入点了（团期预支改为逐笔台账，唯一写入点 `addAdvance` 已删除）。
+所以新团期的 A2 永远返回 `0.00`，老团期停在期初结转那一刻，而且旧列从来不含子订单级预支。
+
+本次 A2 改为与财务 Tab 调同一对方法取数，两个接口对同一团期必然同值。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | A2 团期详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 修改接口 | 出参 `advanceAmount` 取值口径改为与 GB-ADM-040 `advanceApproved` 同源；字段名、类型与其余字段零变化 |
+
+## 三、接口详情
+
+### 1. A2 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
+
+**VO**: `GroupBatchDetailRespVO`
+
+#### 使用场景
+
+团期详情页进入时拉取整团概览。本次只改其中 `advanceAmount` 的取值来源；需要「已预支 / 待审批 / 可支取」三个数时，
+仍以财务 Tab `GET /v3/admin/order/group-batch/{groupBatchId}/finance` 为准。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | 正整数，团期聚合主键 | 团期 ID，不存在返 589501 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| advanceAmount | BigDecimal（字符串序列化） | **本次改口径**。已预支 = Σ 本团期 `status=APPROVED` 且未软删的预支，范围是团期级（`group_batch_id` = 本团期）∪ 子订单级（`order_id` ∈ 本团活跃子订单）；两位小数。与 GB-ADM-040 `advanceApproved` 同一方法、同一格式，逐字一致。SUBMITTED、REJECTED、已撤回、PAID 均不计入 |
+| receivableAmount | BigDecimal | 整团应收（既有字段，本次未改） |
+| receivedAmount | BigDecimal | 整团已收（既有字段，本次未改） |
+| unpaidAmount | BigDecimal | 整团待收（既有字段，本次未改） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2104885714862899201 HTTP/1.1
+Host: api.test.1814.love
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2104885714862899201",
+    "batchStatus": "RECRUITING",
+    "advanceAmount": "1450.00",
+    "receivableAmount": "5960.00",
+    "receivedAmount": "0.00",
+    "unpaidAmount": "5960.00"
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+团期没有任何 APPROVED 预支时返回 `"0.00"`，不返回 null、不缺字段，与财务 Tab 一致。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2104885713021587458",
+    "advanceAmount": "0.00"
+  }
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589501,
+  "message": "团期不存在",
+  "data": null
+}
+```
+
+| 错误码 | 触发条件 |
+|---|---|
+| 589501 | groupBatchId 不存在或已软删 |
+| 589507 | 缺 `group-batch:view` 权限码 |
+
+#### 业务边界
+
+- 取数与财务 Tab 共用 `GroupBatchAdvanceQueryService.listActiveSubOrderIds` + `sumApproved`，不另写 SQL。
+- 子订单全部退团后，团期级预支仍然计入（子订单集为空时照样按 `group_batch_id` 汇总）。
+- PAID 不计入是 g-081 的既有口径，本次未改；若日后 `sumApproved` 改口径，A2 与财务 Tab 会一起变。
+- `order_group_batch.advance_amount` 列保留不删，只是 A2 不再读它。
+
+## 四、契约约束与正确调用方式
+
+- 页面展示「已预支」请继续取财务 Tab 的 `advanceApproved`；A2 的 `advanceAmount` 现在与它同值，可作为详情页概览的冗余读数。
+- 不要把 `advanceAmount` 与「待审批」「可支取」相加或互推，三个数请都取财务 Tab。
+
+## 五、数据库行为
+
+零数据库变更。本次不新增表、列或索引，不写任何数据。`advanceAmount` 改为只读聚合 `order_advance`（与财务 Tab 同一查询），
+详情装配多两次只读查询（取本团活跃子订单 ID + 一次金额聚合），单团期无 N+1，落在既有 `@Transactional(readOnly = true)` 段内，不涉及 Feign。
+
+## 六、边界行为
+
+- 团期不存在 → 589501。
+- 团期无任何预支 → `"0.00"`。
+- 只有 SUBMITTED / REJECTED / 已撤回的预支 → `"0.00"`（与财务 Tab 一致）。
+
+## 六.6、修改前后对比
+
+| 项 | 修改前 | 修改后 |
+|---|---|---|
+| `advanceAmount` 来源 | `order_group_batch.advance_amount`（#7154 起停写） | `order_advance` 实时聚合，与 GB-ADM-040 `advanceApproved` 同一方法 |
+| 新团期 | 永远 `0.00` | 实际通过的预支合计 |
+| 子订单级预支 | 不含 | 含 |
+| 字段名 / 类型 / 其余出参 | — | 逐字未变 |
+| 路径 / 入参 / 权限码 | — | 逐字未变 |
+
+## 六.7、影响评估
+
+- **兼容性**：字段名与类型不变；数值会从 0 或过期值变为实际值。hl-ui v2.1 团期详情页未渲染该字段，界面无变化。
+- **性能**：单团期多两次只读查询，无 N+1。
+- **回滚**：撤销 PR #8539 的合并提交后重新部署 order-v3，无数据与配置残留。
+
+## 七、不影响范围
+
+- 财务 Tab（GB-ADM-040）、预支记录（GB-ADM-043）、预支上限校验：口径与字段零改动。
+- 团期列表、看板：不含 `advanceAmount`，未涉及。
+- 网关：路径未变、无新增路由与权限码。
+- 小程序端：本接口仅管理后台使用。
+
+## 八、测试环境已验证
+
+2026-09-29 18:44–19:17 测试服（`api.test.1814.love`），部署 `dev-v3 @ 27409a3f1`（order-v3 双实例 8086/8186）。
+自建两个团期、真实订单与主报账人后造预支；每组同一时刻读 A2 与 GB-ADM-040，并用 SQL 按同一口径算期望值作第三方对照。
+旧列 `order_group_batch.advance_amount` 在全部读数时刻都是 `0.00`，证明新值不来自旧列。
+
+| 场景 | 造数 | A2 `advanceAmount` | GB-ADM-040 `advanceApproved` | SQL 期望 |
+|---|---|---|---|---|
+| 无预支（自建 2 团 + 现存 17 团只读） | 无 | `"0.00"` | `"0.00"` | 0.00 |
+| 只有团期级 APPROVED | 团期级 APPROVED 1200 + 待审 350 + 驳回 480 + 撤回 260 | `"1200.00"` | `"1200.00"`（`advancePending="350.00"`） | 1200.00 |
+| 团期级 + 子订单级 | 团期级 APPROVED 800 + 子订单级 APPROVED 650 + 子订单级待审 420 | `"1450.00"` | `"1450.00"`（`advancePending="420.00"`） | 1450.00 |
+
+- 部署身份：在「只有团期级 APPROVED」团期上经网关连打 A2 8 次，全是 `"1200.00"`（旧代码会返回 `"0.00"`）；直连 8086、8186 两实例各读，同为新值。
+- 验收造数已全部回收，回读零残留。
+
+单元测试：定向 35 类 487 例 0 失败（含新增 4 条，经 surefire XML 核实真执行）；团期整包 + 全部 ArchTest 3118 例中 11 例红，基底 `dfb5db832` 同样复现，属既有失败。
+
+## 十、相关文档
+
+- 工单 #8533、PR #8539（merge commit `27409a3f1`）
+- 团期预支改为逐笔台账 + 实时聚合：#7154
+- 同写法先例（详情字段与兄弟接口同源回填）：#8215
+- PAID 口径遗留：台账 g-081（09-28 定暂不处理）
+
+## 关联 / 联系人
+
+- 后端：jw
+- 前端：不涉及（`frontend_status: not_required`）