docs(changelog): 团期核团详情统一接口 return-detail 上线，reports/group 旧路径已删 404（#8641）

- 新增 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 <noreply@anthropic.com>
2026-09-30 14:18:12 +08:00
@@ -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<GroupReturnDetailRespVO>`。字段分四段。
+
+### 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<GroupSettlementCustomerItemVO>` | 全团出行人/客户合并（一户一行：orderId/orderNo/teamNo/customerName 明文/customerPhone 脱敏/travelerCount） |
+| `householdCount` / `travelerCount` / `adultCount` / `childCount` / `youngChildCount` / `babyCount` | Integer | 户数 / 总人数（含婴儿）/ 各档人数 |
+
+### 5.4 司机车辆区间段（**本次新增** `driverVehicles`）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `driverVehicles` | `List<SettlementDriverVehicleSegmentVO>` | 全团司机车辆连续服务区间，默认空数组（不返回 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
+- 负责人：腰苏图