yaosutu 83cbc282aa 推送 4 条核单侧改造接口变更 changelog（PR1 线下收款 / PR2 子表扩列 / PR3 recon+payout / PR5 submit收口）

2026-07-07 18:00:42 +08:00

6.4 KiB

原始文件 Blame 文件历史

线下收款登记（司机现场代收人 / 对公转账）

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

1. 接口背景

核单 epic PR1。核单流程中，定制师需要记录非微信支付渠道的线下收款（司机现场代收人现金、对公转账），并确保订单 paid_amount 实时更新。登记成功后事务层推进 paid_amount 累加并重算 pay_status(PARTIAL_PAID/FULLY_PAID)。已撤销的凭据行保留在列表供审计溯源。

2. 变更清单

序号	方法	路径	说明
1	POST	`/v3/admin/order/{orderId}/payment/manual-receipt`	登记线下收款
2	DELETE	`/v3/admin/order/{orderId}/payment/manual-receipt/{receiptId}`	撤销线下收款（转删，行保留）
3	GET	`/v3/admin/order/{orderId}/payment/manual-receipt`	查询订单线下收款列表

3. 接口详情

项	说明
认证	JWT Bearer(管理端), Gateway 注入 X-Admin-Id/X-Admin-RealName
幂等性	POST 非幂等; DELETE 幂等守卫（已撤销返 520406）
限流	网关全局限流
订单状态白名单	仅 CANCELLED 拒绝，其余状态（含已结算）均可登记

4. 接口入参

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

字段	类型	必填	说明
orderId	Long	是	订单 ID

DELETE 额外路径参数: receiptId (Long, 必, 凭据 ID 由 POST 响应获取)

4.2 请求体(POST)

字段	类型	必填	说明
channel	String	是	收款渠道: DRIVER_CASH/BANK_TRANSFER
payType	String	是	款项类型: DEPOSIT/BALANCE/FULL
amount	BigDecimal	是	>0
receivedAt	LocalDateTime	否	可补录历史，不传默认当前
transferRef	String	条件必填	`BANK_TRANSFER`时必填
collectorStaffId	Long	条件必填	`DRIVER_CASH`时必填且属本订单人员
voucherUrls	List	否	凭证图片 URL
remark	String	否	备注, max 500

DELETE 请求体: voidReason (String, 否, 撤销原因)

5. 出参字段

POST/DELETE 返回单条 ManualReceiptVO，GET 返回 List<ManualReceiptVO>。

paidAmountAfter/payStatusAfter 仅在 POST/DELETE 响应有値，GET 列表为 null。

字段	类型	说明
id	String(Long)	凭据 ID(雪花序列化）
orderId	String(Long)	订单 ID
channel	String	DRIVER_CASH/BANK_TRANSFER
channelLabel	String	渠道显示标签
payType	String	DEPOSIT/BALANCE/FULL
payTypeLabel	String	款项显示标签
amount	BigDecimal	收款金额
receivedAt	LocalDateTime	收款时间
collectorStaffId	String(Long)	代收人 assignmentId, 仅 DRIVER_CASH 有値
collectorStaffName	String	代收人姓名, 仅 DRIVER_CASH 有値
transferRef	String	流水号, 仅 BANK_TRANSFER 有値
voucherUrls	List	凭证图片 URL
remark	String	备注
operatorName	String	登记人姓名
createTime	LocalDateTime	登记时间
voided	Boolean	是否已撤销
voidedByName/voidedAt/voidReason	-	撤销时有値
paidAmountAfter	BigDecimal	操作后订单累计已付金额, GET 为 null
payStatusAfter	String	操作后订单支付状态, GET 为 null

6. 枚举/数据字典

channel: DRIVER_CASH(司机现场代收人) / BANK_TRANSFER(对公转账)

payType: DEPOSIT(订金) / BALANCE(尾款) / FULL(全款)

payStatusAfter: UNPAID(未付款) / PARTIAL_PAID(已付订金) / FULLY_PAID(已付全款)

7. 错误码

错误码	含义	触发场景
520401	收款渠道非法	channel not DRIVER_CASH/BANK_TRANSFER
520402	对公转账必填转账流水号	channel=BANK_TRANSFER & transferRef 为空
520403	必须指定代收人	channel=DRIVER_CASH & collectorStaffId 为空
520404	代收人不属本订单人员	collectorStaffId 不在order_staff_assignment中
520405	凭据不存在	receiptId 非法
520406	已撤销，无法重复	对已撤销行再 DELETE
520407	订单已取消，不允许登记	订单状态为 CANCELLED
520408	收款金额必须>0	amount<=0

8. 示例

8.1 典型成功 -- 登记司机现场代收人尾款

请求:

POST /v3/admin/order/1234567890123456/payment/manual-receipt
Content-Type: application/json
X-Admin-RealName: 扎西师傅

{
  "channel": "DRIVER_CASH",
  "payType": "BALANCE",
  "amount": 8800.00,
  "collectorStaffId": "9800001001",
  "remark": "客户现场支付尾款"
}

响应:

{
  "code": 200,
  "data": {
    "id": "1900000001000001",
    "channelLabel": "司机现场代收人",
    "payTypeLabel": "尾款",
    "amount": 8800.00,
    "collectorStaffName": "扎西师傅",
    "voided": false,
    "paidAmountAfter": 24800.00,
    "payStatusAfter": "FULLY_PAID"
  }
}

8.2 边界 -- 对公转账，补录历史时间

{
  "channel": "BANK_TRANSFER",
  "payType": "DEPOSIT",
  "amount": 5000.00,
  "receivedAt": "2026-06-20T10:00:00",
  "transferRef": "GZL20260620001"
}

返回: paidAmountAfter 为当前累计已付金额。

8.3 业务失败 -- DRIVER_CASH 未指定代收人

{
  "channel": "DRIVER_CASH",
  "amount": 3000.00
}

{
  "code": 520403,
  "msg": "司机现场必须指定代收人"
}

9. 业务边界

适用: 客户现金付款 / 对公转账补录 不适用: 微信支付/支付宝 / 订单已取消 特殊边界:

同一订单可登记多条，每条独立计入paid_amount
撤销后paid_amount同事务回退，行记录保留
paidAmountAfter/payStatusAfter 仅在 POST/DELETE 响应, GET 列表为 null

12. 注意事项

id/orderId 均为 Long 雪花，序列化为字符串，前端禁 Number
collectorStaffId 属于本订单人员配置(order_staff_assignment)中选取
登记后在核单对账页查看paid_amount，需重请 GET /v3/admin/order/{orderId}/settlement/recon

13. 关联/联系人

Issue: wx/HL#4763
PR: wx/HL#4766
Commit: 076bd285a5
后端负责人: 腰苏图

6.4 KiB 原始文件 Blame 文件历史 Unescape Escape