新增核团核算列表详情接口变更说明

2026-07-18 18:03:22 +08:00 · 2026-07-18 18:03:22 +08:00 · 5e2c374ab1
--- a/changelogs-v2/2026-07/18_5055_核团核算列表详情-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/18_5055_核团核算列表详情-修改接口-管理后台.md
@ -0,0 +1,752 @@
+# 【新增/修改接口·管理后台】核团核算列表与详情聚合 (#5055)
+
+> **PR**: [#5058](https://git.1814.love:8443/wx/HL/pulls/5058) | **服务**: `hl-order-service-v3` | **更新时间**: 2026-07-18 18:20
+
+## 1. 接口背景
+
+核团核算页面需要一个常规产品订单入口列表，并且详情页需要一次性拿到订单信息、出行人、司机车辆、应收构成、线上支付和线下收款记录。此前详情接口字段不完整，前端需要自行合并多个接口；本次把核团入口和详情聚合契约收敛到订单服务接口。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 核团核算任务列表 | GET | `/v3/admin/order-settlement/tasks` | 新增接口 | 查询常规 CORE 产品、无团期批次、已完成订单的核团任务列表 |
+| 2 | 查询核团详情 | GET | `/v3/admin/order/{orderId}/settlement/return-detail` | 修改接口 | 扩展订单信息、出行人中文枚举、司机车辆集合、应收汇总/明细、支付+线下收款合并记录 |
+
+## 3. 接口详情
+
+### 3.1 核团核算任务列表
+
+- **使用场景**: 核团核算页的常规产品列表。
+- **认证**: 需要管理后台 JWT。
+- **幂等性**: 是，只读查询。
+- **请求体**: 无。
+- **响应结构**: `Result<PageResult<SettlementTaskRespVO>>`。
+
+#### 3.1.1 Query 入参
+
+| 字段 | 类型 | 必填 | 默认值 | 校验规则 | 说明 |
+|---|---|---|---|---|---|
+| `page` | number | 否 | `1` | 最小 `1` | 当前页码 |
+| `pageSize` | number | 否 | `20` | `1` 到 `100` | 每页条数 |
+| `keyword` | string | 否 | - | - | 关键词，按订单号、团号、产品名模糊查询 |
+| `departureDateFrom` | string | 否 | - | `yyyy-MM-dd` | 出发日期开始 |
+| `departureDateTo` | string | 否 | - | `yyyy-MM-dd` | 出发日期结束 |
+| `settlementStatus` | string | 否 | - | `NONE` / `PENDING` / `COMPLETED` | 核算状态筛选 |
+
+#### 3.1.2 响应字段
+
+顶层统一响应：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` | number | 成功为 `200` |
+| `message` | string | 成功为 `成功` |
+| `data` | object | 分页数据 |
+| `traceId` | string/null | 链路追踪 ID |
+| `success` | boolean | 是否成功 |
+
+`data` 分页字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `records` | array | 核团任务行列表，空结果返回 `[]` |
+| `total` | number | 总记录数 |
+| `page` | number | 当前页码 |
+| `pageSize` | number | 每页条数 |
+
+`records[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `orderId` | string | 订单 ID |
+| `orderNo` | string | 订单号 |
+| `teamNo` | string/null | 团号 |
+| `productName` | string | 产品名称 |
+| `departureDate` | string/null | 出发日期，格式 `yyyy-MM-dd` |
+| `returnDate` | string/null | 返团日期，格式 `yyyy-MM-dd` |
+| `peopleCount` | number | 出行人总数 |
+| `peopleSummary` | string | 人数文案，如 `2成人2儿童`、`2成人1婴儿`、`0人` |
+| `systemBalanceAmount` | number | 系统计算待收尾款 |
+| `settlementStatus` | string | 核算状态 |
+| `settlementStatusName` | string | 核算状态中文名 |
+
+列表不返回 `routeName`、`driverName`、`vehiclePlateNo`。
+
+#### 3.1.3 示例
+
+典型成功：
+
+**请求**
+
+```http
+GET /v3/admin/order-settlement/tasks?page=1&pageSize=10&settlementStatus=COMPLETED
+Authorization: Bearer <JWT>
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "orderId": "2077233886248534018",
+        "orderNo": "HL202607180001",
+        "teamNo": "T20260718001",
+        "productName": "呼伦贝尔草原 5 日游",
+        "departureDate": "2026-07-20",
+        "returnDate": "2026-07-24",
+        "peopleCount": 3,
+        "peopleSummary": "2成人1婴儿",
+        "systemBalanceAmount": 0.00,
+        "settlementStatus": "COMPLETED",
+        "settlementStatusName": "已结算"
+      }
+    ],
+    "total": 12,
+    "page": 1,
+    "pageSize": 10
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+空结果：
+
+**请求**
+
+```http
+GET /v3/admin/order-settlement/tasks?page=1&pageSize=10&keyword=不存在的订单
+Authorization: Bearer <JWT>
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [],
+    "total": 0,
+    "page": 1,
+    "pageSize": 10
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+### 3.2 查询核团详情
+
+- **使用场景**: 点击核团任务后进入返团核算详情页。
+- **认证**: 需要管理后台 JWT。
+- **幂等性**: 是，只读查询。
+- **请求体**: 无。
+- **响应结构**: `Result<SettlementReturnDetailRespVO>`。
+
+#### 3.2.1 路径入参
+
+| 字段 | 类型 | 必填 | 校验规则 | 说明 |
+|---|---|---|---|---|
+| `orderId` | string | 是 | 长整型字符串，必须大于 `0` | 订单 ID |
+
+#### 3.2.2 响应字段
+
+`data` 顶层字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `orderInfo` | object/null | 订单信息；取消订单可能为空 |
+| `travelers` | array | 出行人列表，敏感字段已脱敏 |
+| `driverVehicles` | array | 当前有效司机车辆连续服务区间；无有效派车返回 `[]` |
+| `receivableSummary` | object/null | 应收汇总 |
+| `receivableItems` | array | 应收计算明细 |
+| `collectionSummary` | object/null | 收款汇总 |
+| `collectionRecords` | array | 线上支付和线下收款合并记录 |
+
+`orderInfo` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `orderId` | string | 订单 ID |
+| `orderNo` | string | 订单号 |
+| `teamNo` | string/null | 团号 |
+| `productName` | string | 产品名称 |
+| `departureDate` | string/null | 出发日期，格式 `yyyy-MM-dd` |
+| `returnDate` | string/null | 返团日期，格式 `yyyy-MM-dd` |
+| `peopleCount` | number | 出行人总数 |
+| `adultCount` | number | 成人数 |
+| `childCount` | number | 儿童数 |
+| `youngChildCount` | number | 幼童数 |
+| `babyCount` | number | 婴儿数 |
+| `peopleSummary` | string | 人数文案 |
+| `consultantId` | string/null | 定制师 ID |
+| `consultantName` | string/null | 定制师姓名 |
+| `houseStaffId` | string/null | 房务人员 ID |
+| `houseStaffName` | string/null | 房务人员姓名 |
+| `fleetStaffId` | string/null | 车务人员 ID |
+| `fleetStaffName` | string/null | 车务人员姓名 |
+| `settlementStatus` | string | 核算状态 |
+| `settlementStatusName` | string | 核算状态中文名 |
+
+`travelers[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `travelerId` | string | 出行人 ID |
+| `travelerName` | string | 出行人姓名 |
+| `travelerType` | string | 出行人类型 |
+| `travelerTypeName` | string | 出行人类型中文名 |
+| `idType` | string/null | 证件类型 |
+| `idTypeName` | string/null | 证件类型中文名 |
+| `phone` | string/null | 脱敏手机号 |
+| `idCardNo` | string/null | 脱敏证件号 |
+
+`driverVehicles[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `driverId` | string/null | 司机 ID |
+| `driverName` | string/null | 司机姓名 |
+| `driverPhone` | string/null | 脱敏司机手机号 |
+| `vehicleId` | string/null | 车辆 ID |
+| `vehiclePlateNo` | string/null | 车牌号 |
+| `vehicleModelName` | string/null | 车型名称 |
+| `seatCount` | number/null | 座位数 |
+| `startDate` | string | 连续服务开始日期，格式 `yyyy-MM-dd` |
+| `endDate` | string | 连续服务结束日期，格式 `yyyy-MM-dd` |
+
+`receivableSummary` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `orderAmount` | number | 订单基础金额 |
+| `surchargeAmount` | number | 附加费金额 |
+| `discountAmount` | number | 优惠金额 |
+| `payableAmount` | number | 应收总额 |
+| `formulaText` | string | 应收总额公式文案，固定为 `订单金额 + 附加费 - 优惠 = 应收总额` |
+
+`receivableItems[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sourceRecordId` | string/null | 来源记录 ID |
+| `itemType` | string | 应收项类型 |
+| `itemTypeName` | string | 应收项类型中文名 |
+| `itemCode` | string/null | 应收项编码 |
+| `itemName` | string/null | 应收项名称 |
+| `direction` | string | 方向，`ADD` 增加应收，`DEDUCT` 减少应收 |
+| `amount` | number | 金额 |
+
+`collectionSummary` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `payableAmount` | number | 应收总额 |
+| `paidAmount` | number | 累计已收 |
+| `refundedAmount` | number | 累计已退 |
+| `netPaidAmount` | number | 净已收，等于已收减已退 |
+| `balanceAmount` | number | 待收尾款 |
+| `depositPaidAmount` | number | 已收订金 |
+| `balancePaidAmount` | number | 已收尾款 |
+| `fullPaidAmount` | number | 已收全款 |
+
+`collectionRecords[]` 字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `recordId` | string | 收款记录 ID |
+| `recordType` | string | 记录类型，线上支付或线下收款 |
+| `recordTypeName` | string | 记录类型中文名 |
+| `payType` | string/null | 款项类型 |
+| `payTypeName` | string/null | 款项类型中文名 |
+| `channel` | string/null | 支付或收款渠道 |
+| `channelName` | string/null | 支付或收款渠道中文名 |
+| `receiptMethod` | string/null | 线下收款方式；在线支付和对公转账可为空 |
+| `receiptMethodName` | string/null | 线下收款方式中文名 |
+| `amount` | number | 金额 |
+| `collectedAt` | string/null | 收款时间，格式 `yyyy-MM-dd HH:mm:ss` 或 ISO 时间字符串 |
+| `status` | string/null | 收款记录状态 |
+| `statusName` | string/null | 收款记录状态中文名 |
+| `collectorName` | string/null | 代收人姓名 |
+| `operatorName` | string/null | 登记人姓名 |
+| `thirdPartyNoMasked` | string/null | 脱敏第三方交易号 |
+| `transferRef` | string/null | 转账流水号 |
+| `voucherUrls` | string[]/null | 凭证图片 URL |
+| `remark` | string/null | 备注 |
+| `includedInPaidAmount` | boolean | 是否计入已收金额 |
+
+详情接口不返回 `needsVehicle`、`vehicleControlStatus`、`vehicleControlStatusName`。
+
+#### 3.2.3 示例
+
+典型成功：
+
+**请求**
+
+```http
+GET /v3/admin/order/2077233886248534018/settlement/return-detail
+Authorization: Bearer <JWT>
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderInfo": {
+      "orderId": "2077233886248534018",
+      "orderNo": "HL202607180001",
+      "teamNo": "T20260718001",
+      "productName": "呼伦贝尔草原 5 日游",
+      "departureDate": "2026-07-20",
+      "returnDate": "2026-07-24",
+      "peopleCount": 3,
+      "adultCount": 2,
+      "childCount": 0,
+      "youngChildCount": 0,
+      "babyCount": 1,
+      "peopleSummary": "2成人1婴儿",
+      "consultantId": "1001",
+      "consultantName": "admin",
+      "houseStaffId": "20001",
+      "houseStaffName": "房务A",
+      "fleetStaffId": "30001",
+      "fleetStaffName": "车务A",
+      "settlementStatus": "COMPLETED",
+      "settlementStatusName": "已结算"
+    },
+    "travelers": [
+      {
+        "travelerId": "2077233886248535001",
+        "travelerName": "张三",
+        "travelerType": "ADULT",
+        "travelerTypeName": "成人",
+        "idType": "ID_CARD",
+        "idTypeName": "身份证",
+        "phone": "138****0000",
+        "idCardNo": "150***********1234"
+      }
+    ],
+    "driverVehicles": [
+      {
+        "driverId": "2078304714008522754",
+        "driverName": "李师傅",
+        "driverPhone": "176****3787",
+        "vehicleId": "2065329514644152321",
+        "vehiclePlateNo": "蒙C01E01",
+        "vehicleModelName": "丰田埃尔法",
+        "seatCount": 7,
+        "startDate": "2026-07-20",
+        "endDate": "2026-07-24"
+      }
+    ],
+    "receivableSummary": {
+      "orderAmount": 6000.00,
+      "surchargeAmount": 200.00,
+      "discountAmount": 90.00,
+      "payableAmount": 6110.00,
+      "formulaText": "订单金额 + 附加费 - 优惠 = 应收总额"
+    },
+    "receivableItems": [
+      {
+        "sourceRecordId": "2077233886248534018",
+        "itemType": "BASE_ORDER",
+        "itemTypeName": "订单基础应收",
+        "itemCode": "ORDER_AMOUNT",
+        "itemName": "呼伦贝尔草原 5 日游",
+        "direction": "ADD",
+        "amount": 6000.00
+      },
+      {
+        "sourceRecordId": "2077233886248536001",
+        "itemType": "SURCHARGE",
+        "itemTypeName": "附加费",
+        "itemCode": "SINGLE_ROOM",
+        "itemName": "单房差",
+        "direction": "ADD",
+        "amount": 200.00
+      },
+      {
+        "sourceRecordId": "2077233886248537001",
+        "itemType": "DISCOUNT",
+        "itemTypeName": "优惠",
+        "itemCode": "PROMOTION",
+        "itemName": "活动优惠",
+        "direction": "DEDUCT",
+        "amount": 90.00
+      }
+    ],
+    "collectionSummary": {
+      "payableAmount": 6110.00,
+      "paidAmount": 6110.00,
+      "refundedAmount": 0.00,
+      "netPaidAmount": 6110.00,
+      "balanceAmount": 0.00,
+      "depositPaidAmount": 1000.00,
+      "balancePaidAmount": 5110.00,
+      "fullPaidAmount": 0.00
+    },
+    "collectionRecords": [
+      {
+        "recordId": "2077233886248538001",
+        "recordType": "ONLINE_PAYMENT",
+        "recordTypeName": "在线支付",
+        "payType": "DEPOSIT",
+        "payTypeName": "订金",
+        "channel": "WECHAT",
+        "channelName": "微信支付",
+        "receiptMethod": null,
+        "receiptMethodName": null,
+        "amount": 1000.00,
+        "collectedAt": "2026-07-10 10:30:00",
+        "status": "SUCCEEDED",
+        "statusName": "支付成功",
+        "collectorName": null,
+        "operatorName": null,
+        "thirdPartyNoMasked": "4200****0001",
+        "transferRef": null,
+        "voucherUrls": null,
+        "remark": null,
+        "includedInPaidAmount": true
+      },
+      {
+        "recordId": "2077233886248539001",
+        "recordType": "MANUAL_RECEIPT",
+        "recordTypeName": "线下收款",
+        "payType": "BALANCE",
+        "payTypeName": "尾款",
+        "channel": "DRIVER_CASH",
+        "channelName": "报账人收款",
+        "receiptMethod": "WECHAT_TRANSFER",
+        "receiptMethodName": "微信转账",
+        "amount": 5110.00,
+        "collectedAt": "2026-07-20 18:30:00",
+        "status": "CONFIRMED",
+        "statusName": "已确认",
+        "collectorName": "李师傅",
+        "operatorName": "admin",
+        "thirdPartyNoMasked": null,
+        "transferRef": null,
+        "voucherUrls": [
+          "https://oss.example.com/receipt/a.jpg"
+        ],
+        "remark": "现场收尾款",
+        "includedInPaidAmount": true
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+边界成功：无司机车辆、无收款记录。
+
+**请求**
+
+```http
+GET /v3/admin/order/2077233886248534019/settlement/return-detail
+Authorization: Bearer <JWT>
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderInfo": {
+      "orderId": "2077233886248534019",
+      "orderNo": "HL202607180002",
+      "teamNo": null,
+      "productName": "呼伦贝尔草原 5 日游",
+      "departureDate": "2026-07-20",
+      "returnDate": "2026-07-24",
+      "peopleCount": 1,
+      "adultCount": 1,
+      "childCount": 0,
+      "youngChildCount": 0,
+      "babyCount": 0,
+      "peopleSummary": "1成人",
+      "consultantId": "1001",
+      "consultantName": "admin",
+      "houseStaffId": null,
+      "houseStaffName": null,
+      "fleetStaffId": null,
+      "fleetStaffName": null,
+      "settlementStatus": "NONE",
+      "settlementStatusName": "未结算"
+    },
+    "travelers": [],
+    "driverVehicles": [],
+    "receivableSummary": {
+      "orderAmount": 3000.00,
+      "surchargeAmount": 0.00,
+      "discountAmount": 0.00,
+      "payableAmount": 3000.00,
+      "formulaText": "订单金额 + 附加费 - 优惠 = 应收总额"
+    },
+    "receivableItems": [
+      {
+        "sourceRecordId": "2077233886248534019",
+        "itemType": "BASE_ORDER",
+        "itemTypeName": "订单基础应收",
+        "itemCode": "ORDER_AMOUNT",
+        "itemName": "呼伦贝尔草原 5 日游",
+        "direction": "ADD",
+        "amount": 3000.00
+      }
+    ],
+    "collectionSummary": {
+      "payableAmount": 3000.00,
+      "paidAmount": 0.00,
+      "refundedAmount": 0.00,
+      "netPaidAmount": 0.00,
+      "balanceAmount": 3000.00,
+      "depositPaidAmount": 0.00,
+      "balancePaidAmount": 0.00,
+      "fullPaidAmount": 0.00
+    },
+    "collectionRecords": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+业务失败：订单不存在。
+
+**请求**
+
+```http
+GET /v3/admin/order/999999999999999999/settlement/return-detail
+Authorization: Bearer <JWT>
+```
+
+**响应**
+
+```json
+{
+  "code": 581007,
+  "message": "订单不存在",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+## 4. 入参汇总
+
+| 接口 | 入参位置 | 字段 |
+|---|---|---|
+| `GET /v3/admin/order-settlement/tasks` | Query | `page`、`pageSize`、`keyword`、`departureDateFrom`、`departureDateTo`、`settlementStatus` |
+| `GET /v3/admin/order/{orderId}/settlement/return-detail` | Path | `orderId` |
+
+## 5. 出参汇总
+
+| 接口 | 出参根结构 | 主要字段 |
+|---|---|---|
+| `GET /v3/admin/order-settlement/tasks` | `PageResult<SettlementTaskRespVO>` | `records[]`、`total`、`page`、`pageSize` |
+| `GET /v3/admin/order/{orderId}/settlement/return-detail` | `SettlementReturnDetailRespVO` | `orderInfo`、`travelers`、`driverVehicles`、`receivableSummary`、`receivableItems`、`collectionSummary`、`collectionRecords` |
+
+## 6. 枚举 / 数据字典
+
+### 6.1 `settlementStatus`
+
+**所属字段**: `settlementStatus`、`records[].settlementStatus`、`orderInfo.settlementStatus` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `NONE` | 未结算 | 初始态，尚未提交核单 |
+| `PENDING` | 待财务复核 | 已提交核单，等待财务复核 |
+| `COMPLETED` | 已结算 | 财务复核已完成 |
+
+### 6.2 `travelerType`
+
+**所属字段**: `travelers[].travelerType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `ADULT` | 成人 | 成人出行人 |
+| `CHILD` | 儿童 | 儿童出行人 |
+| `YOUNG_CHILD` | 幼童 | 幼童出行人 |
+| `BABY` | 婴儿 | 婴儿出行人 |
+
+### 6.3 `idType`
+
+**所属字段**: `travelers[].idType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `ID_CARD` | 身份证 | 居民身份证 |
+| `PASSPORT` | 护照 | 护照 |
+| `BIRTH_CERT` | 出生证明 | 出生医学证明 |
+
+### 6.4 `itemType`
+
+**所属字段**: `receivableItems[].itemType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `BASE_ORDER` | 订单基础应收 | 订单基础金额 |
+| `SURCHARGE` | 附加费 | 附加费用，增加应收 |
+| `DISCOUNT` | 优惠 | 优惠项目，减少应收 |
+
+### 6.5 `direction`
+
+**所属字段**: `receivableItems[].direction` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `ADD` | 增加 | 计入应收增加项 |
+| `DEDUCT` | 扣减 | 计入应收扣减项 |
+
+### 6.6 `recordType`
+
+**所属字段**: `collectionRecords[].recordType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `ONLINE_PAYMENT` | 在线支付 | 线上支付流水 |
+| `MANUAL_RECEIPT` | 线下收款 | 管理后台登记的线下收款 |
+
+### 6.7 `payType`
+
+**所属字段**: `collectionRecords[].payType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `DEPOSIT` | 订金 | 订金 |
+| `FULL` | 全款 | 全款 |
+| `BALANCE` | 尾款 | 尾款 |
+
+### 6.8 `channel`
+
+**所属字段**: `collectionRecords[].channel` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `WECHAT` | 微信支付 | 在线微信支付 |
+| `ALIPAY` | 支付宝 | 在线支付宝支付 |
+| `OFFLINE_TRANSFER` | 线下转账 | 线下转账渠道 |
+| `DRIVER_CASH` | 报账人收款 | 报账人代收 |
+| `BANK_TRANSFER` | 对公转账 | 对公银行转账 |
+| `CONSULTANT_COLLECTION` | 定制师代收 | 定制师代收 |
+
+### 6.9 `receiptMethod`
+
+**所属字段**: `collectionRecords[].receiptMethod` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `WECHAT_TRANSFER` | 微信转账 | 线下微信转账 |
+| `CASH` | 现金收款 | 现金收款 |
+
+### 6.10 `collectionRecords[].status`
+
+**所属字段**: `collectionRecords[].status` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `SUCCEEDED` | 支付成功 | 成功在线支付，计入已收 |
+| `PENDING` | 待支付 | 在线支付待支付，不计入已收 |
+| `CLOSED` | 已关闭 | 在线支付已关闭，不计入已收 |
+| `REFUNDED` | 已退款 | 在线支付已退款 |
+| `CONFIRMED` | 已确认 | 线下收款已确认，计入已收 |
+| `VOIDED` | 已撤销 | 线下收款已撤销，不计入已收 |
+
+## 7. 错误码
+
+| code | 含义 | 触发场景 |
+|---|---|---|
+| `200` | 成功 | 查询成功 |
+| `400` | 参数校验失败 | `page < 1`、`pageSize > 100`、`orderId <= 0`、日期格式非法、`settlementStatus` 非法 |
+| `401` | 未认证 | 未携带有效管理后台 JWT |
+| `581007` | 订单不存在 | 详情接口查询不存在的订单 |
+| `581045` | 房务角色无权查看订单详情，房务仅可配房 | 房务管理员或房务组长访问列表或详情 |
+| `584072` | 车务司机车辆信息暂时不可用，请稍后重试 | 详情接口读取司机车辆信息不可用 |
+
+## 8. 示例
+
+示例已按接口放在 `3.1.3` 和 `3.2.3`：列表接口包含典型成功和空结果；详情接口包含典型成功、无司机车辆/无收款记录边界成功、订单不存在业务失败。
+
+## 9. 业务边界
+
+- 列表只包含常规 CORE 产品、无团期批次、已完成订单；团期、小蒙马、导游/摄影团队独立列表不在本接口范围。
+- 列表按返团日期倒序、订单 ID 倒序返回。
+- 详情接口取消订单返回成功响应，但 `orderInfo`、汇总对象可为空，数组字段为空数组。
+- 详情中的手机号、身份证号、第三方交易号、司机手机号均为脱敏值。
+- `collectionRecords` 已合并在线支付和线下收款，前端不需要再把支付记录接口与线下收款接口自行合并。
+- `receivableSummary.payableAmount` 是应收总额，计算项通过 `receivableItems` 返回。
+
+## 10. 修改前后对比
+
+### 10.1 列表接口
+
+| 项 | 修改前 | 修改后 |
+|---|---|---|
+| 常规产品核团列表 | 无专用接口 | 新增 `GET /v3/admin/order-settlement/tasks` |
+| 人数文案 | 无 | 返回 `peopleSummary` |
+| 核算状态中文 | 无 | 返回 `settlementStatusName` |
+| 司机/车牌 | 不适用 | 列表不返回司机和车牌字段 |
+
+### 10.2 详情接口
+
+| 字段/结构 | 修改前 | 修改后 |
+|---|---|---|
+| `orderInfo.peopleSummary` | 无 | 新增 |
+| `orderInfo.adultCount/childCount/youngChildCount/babyCount` | 无 | 新增 |
+| `orderInfo.consultantId/consultantName` | 无 | 新增 |
+| `orderInfo.houseStaffId/houseStaffName` | 无 | 新增 |
+| `orderInfo.fleetStaffId/fleetStaffName` | 无 | 新增 |
+| `orderInfo.settlementStatusName` | 无 | 新增 |
+| `travelers[].travelerTypeName` | 无 | 新增 |
+| `travelers[].idTypeName` | 无 | 新增 |
+| `driverVehicles` | 无 | 新增司机车辆集合 |
+| `receivableSummary` | 不完整 | 新增订单金额、附加费、优惠、应收总额、公式文案 |
+| `receivableItems` | 无 | 新增应收计算明细 |
+| `collectionSummary` | 不完整 | 新增已收/已退/净已收/待收/订金/尾款/全款汇总 |
+| `collectionRecords` | 无 | 新增在线支付+线下收款合并记录 |
+| `needsVehicle/vehicleControlStatus/vehicleControlStatusName` | 可能需要前端关注 | 本接口不返回 |
+
+## 11. 影响评估 / 回滚
+
+### 11.1 影响评估
+
+- **是否破坏向后兼容**: 否。列表为新增接口；详情为新增出参字段和新增集合结构。
+- **前端是否必须同步上线**: 建议同步。核团列表页应改用新增列表接口；详情页可直接使用新增聚合字段，减少前端合并接口逻辑。
+- **影响已有数据**: 不需要数据迁移。
+
+### 11.2 回滚方案
+
+- **回滚方式**: 回滚 PR #5058。
+- **回滚后前端影响**: 新增列表接口不可用，详情新增字段消失；前端需要回退到原有多接口合并方案或旧页面逻辑。
+
+## 12. 注意事项
+
+- `orderId`、`travelerId`、`driverId`、`vehicleId` 等长整型 ID 均按字符串处理，避免 JS 精度丢失。
+- 列表不要展示司机和车牌；司机车辆只在详情的 `driverVehicles` 中展示。
+- 详情里的线下收款和在线支付已经按统一记录结构返回，`recordType` 用于区分来源。
+- 金额字段单位均为元。
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **Issue**: [#5055](https://git.1814.love:8443/wx/HL/issues/5055)
+- **PR**: [#5058](https://git.1814.love:8443/wx/HL/pulls/5058)
+- **Merge commit**: [d916901f8](https://git.1814.love:8443/wx/HL/commit/d916901f8)
+
+### 13.2 联系人
+
+- **后端负责人**: @yst
+- **需求确认**: @yaosutu