wx/hl-api-changelog

派生 0

yaosutu 318917e6cf 新增线下收款代收人接口变更说明

2026-07-10 16:37:52 +08:00

11 KiB

原始文件 Blame 文件历史

线下收款代收人能力接口变更说明

1. 接口背景

管理后台“登记线下收款”需要区分实际代收人：公司账户转账、定制师代收、司机现场收款。原接口只能表达司机或银行转账，不能覆盖“订金 / 全款阶段由定制师代收”的业务场景，也没有给前端提供可选代收人列表。

本次变更补齐收款选项查询接口，并扩展登记接口的代收人字段。司机现场收款限定为尾款，订金和全款不允许选择司机现场收款。

2. 变更清单

类型	接口	说明
新增接口	`GET /v3/admin/order/{orderId}/payment/manual-receipt/options`	查询当前订单可登记的线下收款渠道、可登记款项类型、可选代收人
修改接口	`POST /v3/admin/order/{orderId}/payment/manual-receipt`	入参新增 `collectorType`，渠道枚举新增 `CONSULTANT_COLLECTION`
修改接口	`GET /v3/admin/order/{orderId}/payment/manual-receipt`	列表出参新增代收人快照字段
修改出参	`ManualReceiptVO`	新增 `collectorType` / `collectorAdminId` / `collectorName` / `collectorRole`

3. 接口详情

3.1 查询线下收款选项

GET /v3/admin/order/{orderId}/payment/manual-receipt/options

用途：前端进入登记线下收款弹窗时调用，用于渲染渠道、款项类型和代收人下拉框。

3.2 登记线下收款

POST /v3/admin/order/{orderId}/payment/manual-receipt

用途：登记一笔线下收款，并根据订单当前支付状态推进为订金已付、全款已付或尾款已付。

3.3 查询线下收款记录

GET /v3/admin/order/{orderId}/payment/manual-receipt

用途：查询订单线下收款记录。返回结构沿用原 ManualReceiptVO 列表，本次只新增代收人快照字段。

4. 入参

4.1 查询线下收款选项

参数	位置	类型	必填	说明
`orderId`	Path	Long	是	订单 ID

4.2 登记线下收款

字段	类型	必填	说明
`channel`	String	是	收款渠道：`DRIVER_CASH` / `BANK_TRANSFER` / `CONSULTANT_COLLECTION`
`payType`	String	是	登记款项类型：`DEPOSIT` / `FULL` / `BALANCE`
`amount`	Decimal	是	收款金额
`collectorType`	String	否	代收人类型：`ORDER_STAFF` / `CONSULTANT` / `COMPANY_ACCOUNT`。不传时后端按渠道推断
`collectorStaffId`	Long	条件必填	`DRIVER_CASH` 时必填，且必须是当前订单司机
`transferRef`	String	条件必填	`BANK_TRANSFER` 时必填
`remark`	String	否	备注

渠道规则：

`channel`	允许的 `payType`	代收人规则
`CONSULTANT_COLLECTION`	`DEPOSIT` / `FULL` / `BALANCE`	使用订单定制师作为代收人；订金和全款阶段通常选择此渠道
`BANK_TRANSFER`	`DEPOSIT` / `FULL` / `BALANCE`	公司账户收款；必须填写 `transferRef`
`DRIVER_CASH`	`BALANCE`	只能登记尾款；必须选择当前订单司机

5. 出参

5.1 查询线下收款选项出参

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "channels": [
      {
        "channel": "CONSULTANT_COLLECTION",
        "channelText": "定制师代收",
        "allowedPayTypes": ["DEPOSIT", "FULL"],
        "collectors": [
          {
            "collectorType": "CONSULTANT",
            "collectorId": 2037350531801993218,
            "collectorName": "腰苏图",
            "collectorRole": "CONSULTANT",
            "collectorRoleText": "定制师",
            "defaultSelected": true
          }
        ]
      }
    ]
  },
  "success": true
}

字段说明：

字段	类型	说明
`channels`	Array	可展示的线下收款渠道列表
`channel`	String	渠道枚举值
`channelText`	String	渠道展示文案
`allowedPayTypes`	Array	当前订单状态下该渠道允许登记的款项类型；为空数组表示该渠道当前不可登记
`collectors`	Array	该渠道可选代收人列表
`collectorType`	String	代收人类型
`collectorId`	Long	代收人 ID；定制师为管理员 ID，司机为订单人员 ID
`collectorName`	String	代收人姓名
`collectorRole`	String	代收人角色枚举
`collectorRoleText`	String	代收人角色文案
`defaultSelected`	Boolean	是否建议前端默认选中

5.2 登记 / 列表接口 ManualReceiptVO 新增字段

字段	类型	说明
`collectorType`	String	代收人类型：`ORDER_STAFF` / `CONSULTANT` / `COMPANY_ACCOUNT`
`collectorAdminId`	Long	定制师 / 管理员代收人 ID；司机收款时为空
`collectorName`	String	代收人姓名快照
`collectorRole`	String	代收人角色快照

6. 枚举 / 数据字典

6.1 channel

枚举值	文案	说明
`DRIVER_CASH`	司机现场收款	仅允许登记尾款
`BANK_TRANSFER`	银行转账	公司账户收款
`CONSULTANT_COLLECTION`	定制师代收	本次新增，支持订金 / 全款 / 尾款

6.2 collectorType

枚举值	文案	说明
`ORDER_STAFF`	订单人员	当前用于订单司机
`CONSULTANT`	定制师	当前订单归属定制师
`COMPANY_ACCOUNT`	公司账户	银行转账场景

6.3 payType

枚举值	文案	说明
`DEPOSIT`	订金	待支付阶段可登记
`FULL`	全款	待支付阶段可登记
`BALANCE`	尾款	已付订金后可登记

7. 错误码

code	message	触发场景
`520011`	收款类型非法	`payType` 不支持或不符合订单当前状态
`520401`	线下收款渠道非法	`channel` 不支持
`520402`	银行转账流水号不能为空	`BANK_TRANSFER` 未传 `transferRef`
`520403`	司机现场收款必须选择代收人	`DRIVER_CASH` 未传 `collectorStaffId`
`520404`	代收人不属于当前订单	选择的司机不属于当前订单
`520407`	已取消订单不能登记线下收款	订单已取消
`520409`	线下收款代收人类型非法	`collectorType` 与渠道不匹配
`520410`	司机现场收款只能登记尾款	`DRIVER_CASH` 登记订金或全款
`520411`	司机现场收款必须选择本订单司机	选择的代收人不是本订单司机
`520412`	订单没有可用定制师，不能登记定制师代收	`CONSULTANT_COLLECTION` 场景无法定位订单定制师

8. 示例

8.1 待支付订单查询选项

请求：

GET /v3/admin/order/2075415307597357058/payment/manual-receipt/options

响应：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "channels": [
      {
        "channel": "CONSULTANT_COLLECTION",
        "channelText": "定制师代收",
        "allowedPayTypes": ["DEPOSIT", "FULL"],
        "collectors": [
          {
            "collectorType": "CONSULTANT",
            "collectorId": 2037350531801993218,
            "collectorName": "腰苏图",
            "collectorRole": "CONSULTANT",
            "collectorRoleText": "定制师",
            "defaultSelected": true
          }
        ]
      },
      {
        "channel": "BANK_TRANSFER",
        "channelText": "银行转账",
        "allowedPayTypes": ["DEPOSIT", "FULL"],
        "collectors": [
          {
            "collectorType": "COMPANY_ACCOUNT",
            "collectorId": null,
            "collectorName": "公司账户",
            "collectorRole": "COMPANY_ACCOUNT",
            "collectorRoleText": "公司账户",
            "defaultSelected": true
          }
        ]
      },
      {
        "channel": "DRIVER_CASH",
        "channelText": "司机现场收款",
        "allowedPayTypes": [],
        "collectors": []
      }
    ]
  },
  "success": true
}

8.2 定制师代收订金成功

请求：

{
  "channel": "CONSULTANT_COLLECTION",
  "payType": "DEPOSIT",
  "amount": 0.01,
  "collectorType": "CONSULTANT",
  "remark": "测试定制师代收订金"
}

响应节选：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 2075498676913938434,
    "orderId": 2075415307597357058,
    "channel": "CONSULTANT_COLLECTION",
    "payType": "DEPOSIT",
    "amount": 0.01,
    "collectorType": "CONSULTANT",
    "collectorAdminId": 2037350531801993218,
    "collectorName": "腰苏图",
    "collectorRole": "CONSULTANT",
    "paidAmountAfter": 0.01,
    "payStatusAfter": "DEPOSIT_PAID"
  },
  "success": true
}

8.3 司机登记订金失败

请求：

{
  "channel": "DRIVER_CASH",
  "payType": "DEPOSIT",
  "amount": 0.01,
  "collectorType": "ORDER_STAFF",
  "collectorStaffId": 2075415568273350658
}

响应：

{
  "code": 520410,
  "message": "司机现场收款只能登记尾款",
  "data": null,
  "success": false
}

9. 业务边界

待支付订单：

渠道	可登记款项
定制师代收	订金、全款
银行转账	订金、全款
司机现场收款	不允许

已付订金订单：

渠道	可登记款项
定制师代收	尾款
银行转账	尾款
司机现场收款	尾款

已取消订单：不允许登记线下收款。

10. 修改前后对比

项目	修改前	修改后
前端获取可选渠道	无专用接口，需要自行判断	使用 options 接口返回后端裁剪后的渠道、款项和代收人
定制师代收	不支持独立渠道	支持 `CONSULTANT_COLLECTION`
司机现场收款	可传任意款项类型，后端限制不完整	后端强制只允许 `BALANCE`
收款记录展示	无代收人快照字段	返回 `collectorType` / `collectorAdminId` / `collectorName` / `collectorRole`

11. 影响评估 / 回滚

影响范围：管理后台订单详情里的登记线下收款弹窗和线下收款记录列表。

兼容性：

原 BANK_TRANSFER、DRIVER_CASH 渠道仍保留。
collectorType 非必填；老前端不传时后端按渠道推断。
新前端应优先调用 options 接口，避免在前端硬编码订单状态和渠道限制。

回滚注意：若前端已使用 CONSULTANT_COLLECTION，后端回滚后会出现渠道非法，需要前后端同步回滚。

12. 注意事项

DRIVER_CASH 不能用于订金和全款。
CONSULTANT_COLLECTION 不需要传 collectorStaffId。
BANK_TRANSFER 必须传 transferRef。
options 接口里某个渠道的 allowedPayTypes 为空数组时，前端应置灰或隐藏该渠道的提交入口。

13. 关联 / 联系人

Issue：https://git.1814.love:8443/wx/HL/issues/4884
主 PR：https://git.1814.love:8443/wx/HL/pulls/4886
迁移修复 PR：https://git.1814.love:8443/wx/HL/pulls/4888
渠道字段修复 PR：https://git.1814.love:8443/wx/HL/pulls/4890
合并提交：ab253660f / cd6a70b47 / a9d085040
负责人：腰苏图

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