---
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-30"
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`）