From 687999963bce9425f56f93a4606bc71745af8cdc Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Wed, 30 Sep 2026 14:18:12 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=9B=A2=E6=9C=9F=E6=A0=B8?= =?UTF-8?q?=E5=9B=A2=E8=AF=A6=E6=83=85=E7=BB=9F=E4=B8=80=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=20return-detail=20=E4=B8=8A=E7=BA=BF=EF=BC=8Creports/group=20?= =?UTF-8?q?=E6=97=A7=E8=B7=AF=E5=BE=84=E5=B7=B2=E5=88=A0=20404=EF=BC=88#86?= =?UTF-8?q?41=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 GET /v3/admin/order/group-batch/{gid}/settlement/return-detail 团期核团详情统一总览 - 出参新增 driverVehicles 司机车辆连续区间（本地快照按司机+车辆合并，driverPhone 脱敏） - 原 /settlement/reports/group 已下线，调用返回业务码 404（HTTP 200 包装） - PR #8651 / Issue #8641 Co-Authored-By: Claude Opus 4.8 --- ...详情return-detail统一接口-修改接口-管理后台.md | 262 ++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 changelogs-v2/2026-09/30_8641_团期核团详情return-detail统一接口-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/30_8641_团期核团详情return-detail统一接口-修改接口-管理后台.md b/changelogs-v2/2026-09/30_8641_团期核团详情return-detail统一接口-修改接口-管理后台.md new file mode 100644 index 00000000..374c662b --- /dev/null +++ b/changelogs-v2/2026-09/30_8641_团期核团详情return-detail统一接口-修改接口-管理后台.md @@ -0,0 +1,262 @@ +--- +schema: "hl-changelog/v2" +ticket: "8641" +title: "团期核单「核团详情」统一接口 return-detail 上线，reports/group 旧路径已删 404" +consumer: "admin" +author: "yst(GIT)" +change_type: "修改接口" +backend_status: "merged" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "v2.1" +verified_at: "2026-09-30" +base: "dev-v3" +updated_at: "2026-09-30" +status_note: "团期核单对齐核心订单 return-detail 形态：新增统一总览接口 GET /v3/admin/order/group-batch/{groupBatchId}/settlement/return-detail（一屏打包团期信息+财务总览+customers 全团出行人合并+人数汇总+复核快照段+driverVehicles 司机车辆区间），原 GET .../settlement/reports/group 已下线（调用返回业务码 404，HTTP 200 包装）。出参在 reports/group 基础上新增 driverVehicles（读 order_vehicle_assignment 本地快照按司机+车辆合并连续 serviceDate 成区间，driverPhone 已脱敏），其余字段与口径完全不变。后端已合并 dev-v3 待部署。前端：原 reports/group 调用方改调 return-detail（字段平移即可），并新增渲染 driverVehicles 司机车辆区间。" +--- + +# 团期核团详情统一接口 return-detail —— 修改接口（管理后台） + +> Issue: https://git.1814.love/wx/HL/issues/8641 +> PR: https://git.1814.love/wx/HL/pulls/8651 +> Commit: https://git.1814.love/wx/HL/commit/067753a12a283c8df011e7b312282bfa0f55f4ea +> 负责人：腰苏图 + +--- + +## 1. 接口背景 + +核心订单核单有「核团详情」总览接口 `GET /v3/admin/order/{orderId}/settlement/return-detail`，一屏打包订单信息+出行人+司机车辆区间+应收+收款。团期核单此前把财务总览放在 `GET .../settlement/reports/group`（PR-1），形态与核心订单「统一 return-detail」不一致，且缺司机车辆区间。 + +本次对齐核心订单：新增团期统一总览接口 `return-detail`，并把 `reports/group` 收敛下线。前端已确认未消费旧接口，收敛零破坏。 + +--- + +## 2. 变更清单 + +| 类型 | 接口 | 说明 | +|---|---|---| +| 新增 | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/return-detail` | 团期核团详情统一总览 | +| **删除** | `GET /v3/admin/order/group-batch/{groupBatchId}/settlement/reports/group` | **已下线，调用返回业务码 404**（见 §8.3） | + +出参在 `reports/group` 基础上**新增 `driverVehicles` 字段**，其余字段与口径完全不变。 + +--- + +## 3. 接口详情 + +- **方法/路径**：`GET /v3/admin/order/group-batch/{groupBatchId}/settlement/return-detail` +- **鉴权**：管理后台，复用团期核单查看权限 `group-batch:audit:view`（GROUP_BATCH_MANAGER / FINANCE / ADMIN） +- **说明**：团期核单「核团详情」一屏总览。`finalized=false`（未核单）时实时段（财务/客户/人数/司机车辆）照常返回，复核快照段为 null。 + +--- + +## 4. 入参 + +| 参数 | 位置 | 类型 | 必填 | 说明 | +|---|---|---|---|---| +| `groupBatchId` | path | Long | 是 | 运营团期 ID | + +--- + +## 5. 出参 + +统一返回 `Result`。字段分四段。 + +### 5.1 团期信息 + 核单状态段 + +| 字段 | 类型 | 说明 | +|---|---|---| +| `finalized` | Boolean | 是否已有核单快照（false=尚未核单，复核快照段全 null） | +| `groupSettlementId` | String | 团期核单快照 ID（Long 序列化字符串） | +| `groupBatchId` | String | 团期 ID（字符串） | +| `batchNo` | String | 团期号 | +| `productName` | String | 产品名称快照 | +| `departDate` | String | 出发日期（yyyy-MM-dd） | +| `batchStatus` | String | 团期状态（GroupBatchStatus，如 REVIEWING） | +| `reviewStatus` | String | 复核状态：PENDING / APPROVED / RETURNED | +| `settlementStatus` | String | 核单状态：PENDING / FINALIZED | +| `flowStatus` | String | 团期流程状态快照：TRIP_FINISHED / REVIEWING / SETTLED | +| `settledBy` / `settledByName` / `settledAt` | String / String / String | 核单人 ID/姓名/完成时间（未核单为 null） | +| `remark` / `createTime` | String / String | 备注 / 快照创建时间 | + +### 5.2 复核快照段（成本/利润/共享成本/预支/团级金额） + +| 字段 | 类型 | 说明 | +|---|---|---| +| `settledOrderCount` | Integer | 已核单子订单户数 | +| `totalActiveOrderCount` | Integer | 在团子订单总户数（仅排除已取消） | +| `subOrderTotalActualCost` | String | 子订单实际成本合计 | +| `subOrderTotalProfit` | String | 子订单毛利合计 | +| `sharedCostTotal` | String | 团期共享成本合计 | +| `sharedCostByType` | List | 共享成本按类型汇总 | +| `grandTotalCost` | String | 团期总成本（子订单成本+共享成本） | +| `actualTravelerCount` | Integer | 实际出行人数 | +| `perPersonSharedCost` | String | 人均共享成本（人数为 0 时 null） | +| `groupAdvanceApproved` / `groupAdvancePending` | String / String | 整团预支已批/待批合计 | +| `groupTotalAmount` / `groupPaidAmount` | String / String | 全团应收/已付总额（报账单净额输入，快照口径） | + +### 5.3 实时财务段 + 客户/人数（复用 PR-1，口径不变） + +| 字段 | 类型 | 说明 | +|---|---|---| +| `baseOrderAmount` | String | 基础订单金额合计（Σ order_amount，在团） | +| `otherIncomeAmount` | String | 有效增费合计（Σ surcharge_amount） | +| `discountAmount` | String | 有效优惠合计（Σ discount_amount） | +| `adjustedReceivableAmount` | String | 调整后应收合计（Σ calcPayable） | +| `onlinePaidAmount` | String | 成功线上支付合计（权威） | +| `offlinePaidAmount` | String | 有效线下收款合计（权威） | +| `primaryReporterCollectedAmount` | String | 主报账人代收合计（仅展示，已含在 offlinePaid 内） | +| `paidAmount` | String | 已收合计（镜像，与 outstanding 同源） | +| `actualRefundedAmount` | String | 实际退款合计（镜像，已收扣实退） | +| `netPaidAmount` | String | 净已收 = paidAmount − actualRefundedAmount | +| `outstandingAmount` | String | **待收尾款** = Σ calcBalance（与 /finance 应收台账同源） | +| `surchargeMirrorMatched` / `discountMirrorMatched` / `paidMirrorMatched` / `refundedMirrorMatched` | Boolean | 4 个镜像校验位（数据质量信号，前端一般不需展示） | +| `customers` | `List` | 全团出行人/客户合并（一户一行：orderId/orderNo/teamNo/customerName 明文/customerPhone 脱敏/travelerCount） | +| `householdCount` / `travelerCount` / `adultCount` / `childCount` / `youngChildCount` / `babyCount` | Integer | 户数 / 总人数（含婴儿）/ 各档人数 | + +### 5.4 司机车辆区间段（**本次新增** `driverVehicles`） + +| 字段 | 类型 | 说明 | +|---|---|---| +| `driverVehicles` | `List` | 全团司机车辆连续服务区间，默认空数组（不返回 null） | + +**SettlementDriverVehicleSegmentVO**（与核心订单 return-detail 同构）： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `driverId` | String | 司机 ID（Long 序列化字符串） | +| `driverName` | String | 司机姓名 | +| `driverPhone` | String | 司机手机号（**已脱敏**，如 138****0000） | +| `vehicleId` | String | 车辆 ID（字符串） | +| `vehiclePlateNo` | String | 车牌号 | +| `vehicleModelName` | String | 车型名称 | +| `seatCount` | Integer | 座位数 | +| `startDate` | String | 连续服务开始日期（yyyy-MM-dd） | +| `endDate` | String | 连续服务结束日期（yyyy-MM-dd） | + +> 区间口径：读 `order_vehicle_assignment` 本地快照（Fleet 配车回调回写），按 (司机+车辆) 分组合并连续 serviceDate 成 startDate~endDate；与核心订单 return-detail 口径一致。无派车/空团返回空数组。 + +--- + +## 6. 枚举 / 数据字典 + +- **reviewStatus**：`PENDING` / `APPROVED` / `RETURNED` +- **settlementStatus**：`PENDING` / `FINALIZED` +- **batchStatus / flowStatus**：团期状态机枚举（RECRUITING/RESOURCE_PREPARING/MATERIAL_PREPARING/PENDING_DEPARTURE/TRAVELLING/TRIP_FINISHED/REVIEWING/SETTLED/CANCELLED） + +无新增枚举值。 + +--- + +## 7. 错误码 + +| 错误码 | 说明 | +|---|---| +| `589500` | 团期不存在 | +| 404（业务码） | **旧路径 reports/group 已下线**（HTTP 200 包装，见 §8.3） | +| 403 | 无 `group-batch:audit:view` 权限 | + +--- + +## 8. 示例 + +### 8.1 典型（已核单团，return-detail 正常返回） + +`GET /v3/admin/order/group-batch/2105074382613413890/settlement/return-detail` + +```json +{ + "code": 200, + "message": "成功", + "data": { + "finalized": true, + "groupBatchId": "2105074382613413890", + "batchNo": "20261001-01", + "productName": "呼伦贝尔草原 5 日游", + "departDate": "2026-10-01", + "batchStatus": "REVIEWING", + "reviewStatus": "PENDING", + "settlementStatus": "FINALIZED", + "flowStatus": "REVIEWING", + "outstandingAmount": "2500.00", + "netPaidAmount": "47500.00", + "travelerCount": 18, + "householdCount": 6, + "customers": [ + {"orderId": "9001", "orderNo": "HL20260901001", "teamNo": "A1", "customerName": "张三", "customerPhone": "138****5678", "travelerCount": 3} + ], + "driverVehicles": [ + {"driverId": "20001", "driverName": "李师傅", "driverPhone": "138****0000", "vehicleId": "10001", "vehiclePlateNo": "蒙E12345", "vehicleModelName": "丰田普拉多", "seatCount": 7, "startDate": "2026-10-01", "endDate": "2026-10-05"} + ] + }, + "success": true +} +``` + +### 8.2 边界（未核单团，finalized=false） + +实时段（财务/客户/人数/司机车辆）照常返回，复核快照段（settledBy/settledAt/subOrderTotalActualCost 等）为 null，`finalized=false`。 + +### 8.3 异常（**旧路径 reports/group 已下线，调用返回业务码 404**） + +`GET /v3/admin/order/group-batch/{id}/settlement/reports/group` + +```json +{ + "code": 404, + "message": "接口不存在: GET /v3/admin/order/group-batch/2105074382613413890/settlement/reports/group", + "data": null, + "success": false +} +``` + +> ⚠️ HL 统一契约：未映射/已删除路由返回 **HTTP 200 + body 业务码 404**（非 HTTP 404），前端按 `code === 404` 判定。 + +--- + +## 9. 业务边界 + +- **数据范围**：财务/客户/司机车辆均只统计**在团子订单**，排除已取消（CANCELLED）。 +- **快照 vs 实时**：复核快照段是 finalize 时冻结的「活跃口径」；实时财务段是「在团口径」现算；两者有意并存，前端展示以实时段为准。 +- **driverVehicles**：来自订单侧本地快照（Fleet 配车回调回写），按司机+车辆合并连续日期成区间；不实时连 Fleet。 +- **待收尾款**：`outstandingAmount` 与 `/finance` 应收台账同源，两端可对拍。 + +--- + +## 10. 修改前后对比 + +| 维度 | 修改前（reports/group） | 修改后（return-detail） | +|---|---|---| +| 路径 | `/settlement/reports/group` | `/settlement/return-detail`（旧路径已删 404） | +| 出参字段 | 团期信息+财务+客户+人数+复核快照段 | **同上 + 新增 driverVehicles 司机车辆区间** | +| 司机车辆 | 无 | 有（本地快照合并连续区间，driverPhone 脱敏） | +| 口径 | — | 完全不变，纯路径迁移 + 字段新增 | + +--- + +## 11. 影响评估 / 回滚 + +- **前端迁移**：原 reports/group 调用方改调 `return-detail`，出参字段平移即可（仅多一个 driverVehicles 字段，可不消费）；新增渲染 driverVehicles 司机车辆区间。 +- **兼容性**：旧路径已删返回业务码 404——已核实前端未消费，无破坏。 +- **回滚**：回退 merge commit `067753a12a` 即恢复 reports/group；无 DDL、无数据迁移成本。 + +--- + +## 12. 注意事项 + +1. **路径迁移**：`reports/group` → `return-detail`，字段不变，仅改路径 + 新增 driverVehicles。 +2. **金额字段是字符串**（BigDecimal 序列化），展示直接用，计算需自行转数值。 +3. **driverPhone 已脱敏**；`driverVehicles` 无派车时是空数组 `[]` 不是 null。 +4. 本接口对齐核心订单 `return-detail` 形态；分类明细 tab（住宿/门票等）走 PR-2 的 `/settlement/{hotels,activities,...}` 端点，与本接口互补。 + +--- + +## 13. 关联 / 联系人 + +- Issue: https://git.1814.love/wx/HL/issues/8641 +- PR: https://git.1814.love/wx/HL/pulls/8651 +- Commit: https://git.1814.love/wx/HL/commit/067753a12a283c8df011e7b312282bfa0f55f4ea +- 负责人：腰苏图