From 147e1b34a78997b8d66cce6d3c672c355957b9c1 Mon Sep 17 00:00:00 2001 From: jw Date: Tue, 29 Sep 2026 19:29:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8533=20=E5=9B=A2=E6=9C=9F?= =?UTF-8?q?=E8=AF=A6=E6=83=85=E5=B7=B2=E9=A2=84=E6=94=AF=E6=94=B9=E4=B8=BA?= =?UTF-8?q?=E4=B8=8E=E8=B4=A2=E5=8A=A1=20Tab=20=E5=90=8C=E6=BA=90=EF=BC=88?= =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=8E=A5=E5=8F=A3=C2=B7=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E5=90=8E=E5=8F=B0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs wx/HL#8533 Co-Authored-By: Claude Opus 5.5 --- ...已预支改为与财务页签同源-修改接口-管理后台.md | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 changelogs-v2/2026-09/29_8533_团期详情已预支改为与财务页签同源-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/29_8533_团期详情已预支改为与财务页签同源-修改接口-管理后台.md b/changelogs-v2/2026-09/29_8533_团期详情已预支改为与财务页签同源-修改接口-管理后台.md new file mode 100644 index 00000000..e4477195 --- /dev/null +++ b/changelogs-v2/2026-09/29_8533_团期详情已预支改为与财务页签同源-修改接口-管理后台.md @@ -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 +``` + +#### 响应示例 + +```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`）