hl-api-changelog/changelogs-v2/2026-07/07_4768_核单对账payout-新增接口-管理后台.md

# 核单对账(recon)+小算抨款(payout) 新增接口
- **变更日期**: 2026-07-07
- **端类型**: 管理后台
- **变更类型**: 新增接口
- **Issue**: https://git.1814.love:8443/wx/HL/issues/4768
- **PR**: https://git.1814.love:8443/wx/HL/pulls/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<OtherCollectItemVO> | 否 | 其他代收项 |
| 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<FileItem> | 签字单文件列表 |
| note | String | 备注 |
FileItem: { name(文件名), url(OSS 地址) }

### 4.3 PUT payout 请求体（`SettlementPayoutSaveReqVO`）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| items | List<Item> | 是 | 抨款列表 |

Item 字段:
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| staffId | Long | 否 | 人员 ID |
| staffRole | String | 是 | LEADER/DRIVER/GUIDE/PHOTOGRAPHER/OTHER |
| staffName | String | 是 | 展示性 |
| settleStatus | String | 是 | PENDING/COMPLETED |
| settledDate | LocalDate | 否 | 收款日期 |
| transferRef | String | 否 | 转账流水号 |
---
## 5. 出参字段

### GET recon 响应（`SettlementReconRespVO`）

| 字段 | 类型 | 说明 |
|------|------|------|
| customerCashToDriver | BigDecimal | 司机代收尾款 |
| customerCashCollectedFlag | Boolean | 尾款是否已收 |
| otherCollect | List<OtherCollectItemVO> | 其他代收 |
| 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
```json
{
  "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
```http
PUT /v3/admin/order/1234567890123456/settlement/recon

{
  "transferStatus": "COMPLETED",
  "transferDate": "2026-07-10",
  "transferRef": "202607100001"
}
```
```json
{
  "code": 200,
  "data": null
}
```

### 8.3 业务失败 -- transferRef 为空触发错误
```json
{
  "transferStatus": "COMPLETED"
}
```
```json
{
  "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. 关联/联系人

- Issue: https://git.1814.love:8443/wx/HL/issues/4768
- PR: https://git.1814.love:8443/wx/HL/pulls/4770
- Commit: https://git.1814.love:8443/wx/HL/commit/cbff5a4d2f0706732c360c0ec99609c4687e2749
- 后端负责人: 腰苏图