wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
2cbdcfb13a4be84a0b720b6534953987ce2fb906
hl-api-changelog/changelogs-v2/2026-07/18_5055_核团核算列表详情-修改接口-管理后台.md
T

24 KiB
原始文件 Blame 文件历史

【新增/修改接口·管理后台】核团核算列表与详情聚合 (#5055)

PR: #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 示例

典型成功：

请求

GET /v3/admin/order-settlement/tasks?page=1&pageSize=10&settlementStatus=COMPLETED
Authorization: Bearer <JWT>

响应

{
  "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
}

空结果：

请求

GET /v3/admin/order-settlement/tasks?page=1&pageSize=10&keyword=不存在的订单
Authorization: Bearer <JWT>

响应

{
  "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 示例

典型成功：

请求

GET /v3/admin/order/2077233886248534018/settlement/return-detail
Authorization: Bearer <JWT>

响应

{
  "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
}

边界成功：无司机车辆、无收款记录。

请求

GET /v3/admin/order/2077233886248534019/settlement/return-detail
Authorization: Bearer <JWT>

响应

{
  "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
}

业务失败：订单不存在。

请求

GET /v3/admin/order/999999999999999999/settlement/return-detail
Authorization: Bearer <JWT>

响应

{
  "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 链接

13.2 联系人

  • 后端负责人: @yst
  • 需求确认: @yaosutu
在新工单中引用 查看 Git Blame 复制永久链接