wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

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

浏览代码
这个提交包含在：
yaosutu 2026-07-10 16:37:52 +08:00
父节点 5aad9d2ed3
当前提交 318917e6cf
共有 1 个文件被更改，包括 340 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

340
changelogs-v2/2026-07/10_4884_线下收款代收人-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,340 @@
# 线下收款代收人能力接口变更说明
## 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 查询线下收款选项出参
```json
{
"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<String> | 当前订单状态下该渠道允许登记的款项类型；为空数组表示该渠道当前不可登记 |
| `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 待支付订单查询选项
请求：
```http
GET /v3/admin/order/2075415307597357058/payment/manual-receipt/options
```
响应：
```json
{
"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 定制师代收订金成功
请求：
```json
{
"channel": "CONSULTANT_COLLECTION",
"payType": "DEPOSIT",
"amount": 0.01,
"collectorType": "CONSULTANT",
"remark": "测试定制师代收订金"
}
```
响应节选：
```json
{
"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 司机登记订金失败
请求：
```json
{
"channel": "DRIVER_CASH",
"payType": "DEPOSIT",
"amount": 0.01,
"collectorType": "ORDER_STAFF",
"collectorStaffId": 2075415568273350658
}
```
响应：
```json
{
"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`
- 负责人：腰苏图