diff --git a/changelogs-v2/2026-07/10_4884_线下收款代收人-修改接口-管理后台.md b/changelogs-v2/2026-07/10_4884_线下收款代收人-修改接口-管理后台.md new file mode 100644 index 0000000..8fd6f5d --- /dev/null +++ b/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 | 当前订单状态下该渠道允许登记的款项类型；为空数组表示该渠道当前不可登记 | +| `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` +- 负责人：腰苏图