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

## 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": []
      },
      {
        "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`
- 负责人：腰苏图