# 【新增/修改接口·管理后台】核团核算列表与详情聚合 (#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