wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-07/07_4768_核单对账payout-新增接口-管理后台.md

6.6 KiB
原始文件 永久链接 Blame 文件历史

核单对账(recon)+小算抨款(payout) 新增接口

  • 变更日期: 2026-07-07
  • 端类型: 管理后台
  • 变更类型: 新增接口
  • Issue: wx/HL#4768
  • PR: wx/HL#4770

1. 接口背景

核单 epic PR3。在核单单子表喅录完毕后，定制师需要进行两项补充：

  1. recon (对账): 录入市属司机代收尾款信息、转账信息、预支冲抵确认、签字单回收
  2. payout (小算抨款): 查看干系人员应收金额，并确认转账状态

recon 派生字段说明:

  • 入参字段（数据库存储）: customerCashToDriver / customerCashCollectedFlag / otherCollect / transferStatus / transferDate / transferRef / advanceSettledFlag / signedVoucher
  • 派生字段（实时派生）: driverCollected / publicPrepaid / primaryDue / advanceOutstanding / reconNet
  • 公式: reconNet = driverCollected - publicPrepaid - primaryDue - advanceOutstanding

2. 变更清单

序号 方法 路径 说明
1 GET /v3/admin/order/{orderId}/settlement/recon 核单对账查询
2 PUT /v3/admin/order/{orderId}/settlement/recon 核单对账保存
3 GET /v3/admin/order/{orderId}/settlement/payout 小算抨款列表查询
4 PUT /v3/admin/order/{orderId}/settlement/payout 小算抨款状态更新

3. 接口详情

项 说明
认证 JWT Bearer(管理端)
幂等性 PUT recon: upsert(同一 orderId 却覆）。 PUT payout: 幂等守卫（匹配需授权人员）
HEDAN状态 settlement_status=IN_PROGRESS 时可调用

4. 接口入参

4.1 路径参数（四个接口通用）

| orderId | Long | 是 | 订单 ID |

4.2 PUT recon 请求体（SettlementReconSaveReqVO）

全部字段可空, null=保持现有値 (upsert 语义):

字段 类型 必填 说明
customerCashToDriver BigDecimal 否 司机代收尾款 (null=累加 DRIVER_CASH)
customerCashCollectedFlag Boolean 否 尾款是否已收
otherCollect List 否 其他代收项
transferStatus String 否 PENDING/COMPLETED
transferDate LocalDate 否 转账日期
transferRef String 条件 transferStatus=COMPLETED 时必填
advanceSettledFlag Boolean 否 预支确认冲扣
signedVoucher SignedVoucherVO 否 签字单回收，详见 4.2.1

4.2.1 OtherCollectItemVO

| name | String | 项目名称 | | amount | BigDecimal | 金额 | | collectedFlag | Boolean | 是否已收 |

4.2.2 SignedVoucherVO

| files | List | 签字单文件列表 | | note | String | 备注 | FileItem: { name(文件名), url(OSS 地址) }

4.3 PUT payout 请求体（SettlementPayoutSaveReqVO）

字段 类型 必填 说明
items List 是 抨款列表
字段 类型 必填 说明
staffId Long 否 人员 ID
staffRole String 是 LEADER/DRIVER/GUIDE/PHOTOGRAPHER/OTHER
staffName String 是 展示性
settleStatus String 是 PENDING/COMPLETED
settledDate LocalDate 否 收款日期
transferRef String 否 转账流水号

Item 字段:

5. 出参字段

GET recon 响应（SettlementReconRespVO）

字段 类型 说明
customerCashToDriver BigDecimal 司机代收尾款
customerCashCollectedFlag Boolean 尾款是否已收
otherCollect List 其他代收
transferStatus String 转账状态 PENDING/COMPLETED
transferDate LocalDate 转账日期
transferRef String 转账流水号
advanceSettledFlag Boolean 预支冲扣确认
signedVoucher SignedVoucherVO 签字单回收
primaryName String 主报账人姓名，实时派生
primaryRole String 主报账人角色，实时派生
driverCollected BigDecimal 司机实际代收 = customerCashToDriver + Σ DRIVER_CASH
publicPrepaid BigDecimal 公库预付
primaryDue BigDecimal 主报账人应付
advanceOutstanding BigDecimal 预支未充
reconNet BigDecimal 对账夹算 = driverCollected - publicPrepaid - primaryDue - advanceOutstanding

GET payout 响应（List<SettlementPayoutItemVO>）

字段 类型 说明
staffId Long 人员 ID
staffName String 姓名
staffRole String 角色： LEADER/DRIVER/GUIDE/PHOTOGRAPHER/OTHER
laborCost BigDecimal 工资/劳务费
reimburse BigDecimal 小算补助金额
dueAmount BigDecimal 应付 = laborCost + reimburse
settleStatus String PENDING/COMPLETED
settledDate LocalDate 实际收款日期
transferRef String 转账流水号

6. 枚举/数据字典

transferStatus

値 含义
PENDING 待转
COMPLETED 已转账

settleStatus (payout)

値 含义
PENDING 待抨款
COMPLETED 已抨款

7. 错误码

错误码 含义
584xxx settlement_status 未为 IN_PROGRESS

8. 示例

8.1 典型成功 -- GET recon

{
  "code": 200,
  "data": {
    "customerCashToDriver": 2000.00,
    "transferStatus": "PENDING",
    "primaryName": "张三",
    "driverCollected": 3500.00,
    "publicPrepaid": 1200.00,
    "primaryDue": 800.00,
    "advanceOutstanding": 0.00,
    "reconNet": 1500.00
  }
}

8.2 边界 -- PUT recon, transferStatus=COMPLETED+transferRef

PUT /v3/admin/order/1234567890123456/settlement/recon

{
  "transferStatus": "COMPLETED",
  "transferDate": "2026-07-10",
  "transferRef": "202607100001"
}

{
  "code": 200,
  "data": null
}

8.3 业务失败 -- transferRef 为空触发错误

{
  "transferStatus": "COMPLETED"
}

{
  "code": 584xxx,
  "msg": "transferRef 必填（ transferStatus=COMPLETED）"
}

9. 业务边界

适用: settlement_status=IN_PROGRESS 不适用: 已提交或已结算 特殊边界:

  • reconNet 为负属正常现象
  • payout staffId 可空（外请按实填 null)

12. 注意事项

  • reconNet 公式: driverCollected - publicPrepaid - primaryDue - advanceOutstanding
  • PUT recon: null 字段保持现有値，仅传变动字段

13. 关联/联系人