hl-api-changelog/changelogs-v2/2026-09/29_8533_团期详情已预支改为与财务页签同源-修改接口-管理后台.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	8533	团期详情（A2）出参 advanceAmount（已预支）改为与财务 Tab advanceApproved 同源——不再读 #7154 起已停写的旧列	admin	jw(GIT)	修改接口	deployed	verified	not_required					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 定暂不处理），本次只对齐来源、不改口径。	2026-09-30	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	整团待收（既有字段，本次未改）

请求示例

GET /v3/admin/order/group-batch/2104885714862899201 HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <admin token>

响应示例

{
  "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 一致。

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2104885713021587458",
    "advanceAmount": "0.00"
  }
}

错误响应

{
  "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）