From 5e2c374ab16af4d938cc8e2376eb9b81b6ae2511 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Sat, 18 Jul 2026 18:03:22 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=A0=B8=E5=9B=A2=E6=A0=B8?= =?UTF-8?q?=E7=AE=97=E5=88=97=E8=A1=A8=E8=AF=A6=E6=83=85=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E5=8F=98=E6=9B=B4=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...5055_核团核算列表详情-修改接口-管理后台.md | 752 ++++++++++++++++++ 1 file changed, 752 insertions(+) create mode 100644 changelogs-v2/2026-07/18_5055_核团核算列表详情-修改接口-管理后台.md diff --git a/changelogs-v2/2026-07/18_5055_核团核算列表详情-修改接口-管理后台.md b/changelogs-v2/2026-07/18_5055_核团核算列表详情-修改接口-管理后台.md new file mode 100644 index 0000000..95bbcf6 --- /dev/null +++ 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>`。 + +#### 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 +``` + +**响应** + +```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 +``` + +**响应** + +```json +{ + "code": 200, + "message": "成功", + "data": { + "records": [], + "total": 0, + "page": 1, + "pageSize": 10 + }, + "traceId": null, + "success": true +} +``` + +### 3.2 查询核团详情 + +- **使用场景**: 点击核团任务后进入返团核算详情页。 +- **认证**: 需要管理后台 JWT。 +- **幂等性**: 是，只读查询。 +- **请求体**: 无。 +- **响应结构**: `Result`。 + +#### 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 +``` + +**响应** + +```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 +``` + +**响应** + +```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 +``` + +**响应** + +```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` | `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