From a0413a53bec32fcb3754166972b7cfe39159d747 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 22 Sep 2026 17:07:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8181=20=E7=BA=BF=E4=B8=8B?= =?UTF-8?q?=E6=94=B6=E6=AC=BE=E5=BA=9F=E9=99=A4=E6=8A=A5=E8=B4=A6=E4=BA=BA?= =?UTF-8?q?=E4=BB=A3=E6=94=B6DRIVER=5FCASH=E6=B8=A0=E9=81=93=E2=80=94?= =?UTF-8?q?=E2=80=94options=E5=87=BA=E5=8F=82channels=E7=A7=BB=E9=99=A4DRI?= =?UTF-8?q?VER=5FCASH+register=E6=96=B0=E5=A2=9E520417=EF=BC=88=E5=B0=BE?= =?UTF-8?q?=E6=AC=BE=E6=94=B6=E6=AC=BE=E6=A8=A1=E5=9E=8B=E9=87=8D=E6=9E=84?= =?UTF-8?q?PR-1=EF=BC=8C=E4=BF=AE=E6=94=B9=E6=8E=A5=E5=8F=A3-=E7=AE=A1?= =?UTF-8?q?=E7=90=86=E5=90=8E=E5=8F=B0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...报账人代收DRIVER_CASH渠道-修改接口-管理后台.md | 369 ++++++++++++++++++ 1 file changed, 369 insertions(+) create mode 100644 changelogs-v2/2026-09/22_8181_线下收款废除报账人代收DRIVER_CASH渠道-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/22_8181_线下收款废除报账人代收DRIVER_CASH渠道-修改接口-管理后台.md b/changelogs-v2/2026-09/22_8181_线下收款废除报账人代收DRIVER_CASH渠道-修改接口-管理后台.md new file mode 100644 index 00000000..d2332561 --- /dev/null +++ b/changelogs-v2/2026-09/22_8181_线下收款废除报账人代收DRIVER_CASH渠道-修改接口-管理后台.md @@ -0,0 +1,369 @@ +--- +schema: "hl-changelog/v2" +ticket: "8181" +title: "线下收款废除报账人代收 DRIVER_CASH 渠道（尾款收款模型重构 PR-1）" +consumer: "admin" +author: "yst(GIT)" +change_type: "修改接口" +backend_status: "merged" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "v2.1" +verified_at: "" +status_note: "backend_status: merged - 已合 dev-v3（PR #8183，merge commit a1fb7bc5ef），未部署测试服; gateway_status: not_required - 零网关改动，/v3/admin/order/** 走 hl-gateway 既有通配路由; frontend_status: pending - 前端适配情况未知，需排查 options 消费方是否硬编码 DRIVER_CASH" +updated_at: "2026-09-22" +base: "dev-v3" +--- + +# 线下收款废除「报账人代收 DRIVER_CASH」渠道（尾款收款模型重构 PR-1，#8181） + +> 订单线下收款登记的「报账人收款（DRIVER_CASH）」渠道下线：登记选项接口不再返回该渠道，登记接口传 DRIVER_CASH 直接报新错误码 520417。历史 DRIVER_CASH 收款记录的查询、撤销不受影响。 + +## ① 接口背景 + +此前管理后台给订单补录线下收款时有三个渠道：定制师代收、对公转账、报账人收款（司机/导游等报账人手持现金收尾款）。「报账人代收尾款」模式资金不入公账、对账困难，尾款收款模型重构（Epic #8181）将其废除，改为「确认行程时指定主报账人，尾款挂其代收债务」的新链路（后续 PR 上线）。 + +本 PR 是该重构的第 1 步：只下线 DRIVER_CASH 的**登记入口**，存量数据完全兼容。 + +## ② 变更清单 + +| 类型 | 接口 | 变更 | +|---|---|---| +| 修改（出参结构收缩） | `GET /v3/admin/order/{orderId}/payment/manual-receipt/options` | 出参 `channels[]` 从 3 项变 2 项，**移除 DRIVER_CASH 渠道项** | +| 修改（行为变更 + 新错误码） | `POST /v3/admin/order/{orderId}/payment/manual-receipt` | `channel=DRIVER_CASH` 不再可登记，返回 **520417**（此前可正常登记尾款） | +| 不变 | `GET /v3/admin/order/{orderId}/payment/manual-receipt` 列表 | 历史 DRIVER_CASH 记录照常返回 | +| 不变 | `DELETE /v3/admin/order/{orderId}/payment/manual-receipt/{receiptId}` 撤销 | 历史 DRIVER_CASH 记录照常可撤销 | + +## ③ 接口详情 + +### 3.1 查询线下收款登记选项 + +``` +GET /v3/admin/order/{orderId}/payment/manual-receipt/options +``` + +- 使用场景：订单详情「登记线下收款」弹窗打开时拉取，渲染渠道 tabs + 各渠道可选款项/代收人/收款方式 +- 认证：管理后台 JWT（hl-gateway 统一鉴权） +- 权限：订单归属校验（订单顾问/财务相关角色可读），车务管理员（VEHICLE_MANAGER）可读；房源角色（HOUSE）禁止 +- 幂等性：只读接口，天然幂等 +- 限流：走网关默认限流，无单独配额 + +### 3.2 登记线下收款 + +``` +POST /v3/admin/order/{orderId}/payment/manual-receipt +``` + +- 使用场景：线下收到款项后补录（对公转账到账、定制师代收款），同事务推进订单 `paid_amount` / `pay_status` +- 认证：管理后台 JWT +- 权限：需线下收款写权限（结算写守卫） +- 幂等性：非幂等，每次成功调用新增一条收款凭据并累加已付金额；**重复提交会重复收款**，前端须防连击 +- 事务：凭据落库与订单已付金额累加在同一事务，不会出现半成功状态 + +## ④ 入参 + +### 4.1 选项接口入参 + +| 参数 | 位置 | 类型 | 必填 | 说明 | +|---|---|---|---|---| +| `orderId` | path | Long | 是 | 订单 ID | + +无 query / body 参数。 + +### 4.2 登记接口请求体 + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `channel` | string | 是 | 收款渠道：`CONSULTANT_COLLECTION`（定制师代收）/ `BANK_TRANSFER`（对公转账）。⚠️ `DRIVER_CASH` 已下线，传了返回 520417 | +| `payType` | string | 是 | 款项类型：`DEPOSIT`（订金）/ `BALANCE`（尾款）/ `FULL`（全款） | +| `amount` | number | 是 | 收款金额，必须 > 0，不能超过当前可收余额 | +| `receivedAt` | string(datetime) | 否 | 收款时间，可补录过去时间；不传默认当前时间 | +| `transferRef` | string | 条件必填 | 对公转账流水号，`BANK_TRANSFER` 渠道必填 | +| `receiptMethod` | string | 否 | 收款方式（字典 `manual_receipt_method`），`BANK_TRANSFER` 为空 | +| `collectorStaffId` | Long | 否 | 代收人 assignmentId。原为 DRIVER_CASH 必填，该渠道下线后登记链路不再使用 | +| `collectorType` | string | 否 | 实际代收人类型 `ORDER_STAFF`/`CONSULTANT`/`COMPANY_ACCOUNT`；不传按 channel 兼容推导 | +| `voucherUrls` | string[] | 否 | 凭证图片 URL 列表 | +| `remark` | string | 否 | 备注，最长 500 字 | + +## ⑤ 出参 + +### 5.1 选项接口出参 `ManualReceiptOptionsVO` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `channels` | array | 收款渠道选项。**本次变更后固定 2 项：`CONSULTANT_COLLECTION`、`BANK_TRANSFER`**（顺序即此顺序） | + +`channels[]` 元素 `ChannelOption`： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `channel` | string | 渠道值 | +| `channelText` | string | 渠道显示文案（「定制师代收」/「对公转账」） | +| `allowedPayTypes` | string[] | 当前订单状态下允许的款项类型，空数组 = 该渠道不可用 | +| `disabled` | boolean | 是否禁用，true 时前端置灰 | +| `disabledReason` | string | 禁用原因，`disabled=true` 时有值 | +| `collectors` | array | 该渠道可选代收人（见下表）；`BANK_TRANSFER` 恒为空 | +| `receiptMethods` | array | 该渠道可选收款方式（见下表）；`BANK_TRANSFER` 恒为空 | + +`collectors[]` 元素 `CollectorOption`： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `collectorType` | string | `ORDER_STAFF` / `CONSULTANT` / `COMPANY_ACCOUNT` | +| `collectorId` | Long(string) | 代收人 ID：`CONSULTANT` 为 adminId | +| `collectorName` | string | 代收人姓名 | +| `collectorRole` | string | 代收人角色 | +| `collectorRoleText` | string | 角色显示文案 | +| `defaultSelected` | boolean | 是否默认选中 | + +`receiptMethods[]` 元素 `OptionItem`： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `value` | string | 选项值（字典 `manual_receipt_method`） | +| `label` | string | 显示文案 | +| `defaultSelected` | boolean | 是否默认选中（首项为 true） | + +### 5.2 登记接口出参 `ManualReceiptVO` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `id` | Long(string) | 收款凭据 ID（雪花，String 防 JS 精度丢失） | +| `orderId` | Long(string) | 订单 ID | +| `channel` | string | 收款渠道值 | +| `channelLabel` | string | 渠道显示标签 | +| `payType` | string | 款项类型值 | +| `payTypeLabel` | string | 款项类型显示标签 | +| `amount` | number | 收款金额 | +| `receivedAt` | string(datetime) | 收款时间 | +| `collectorStaffId` | Long(string) | 代收人 assignmentId（历史 DRIVER_CASH 行才有值） | +| `collectorStaffName` | string | 代收人姓名（历史 DRIVER_CASH 行才有值） | +| `collectorType` | string | 实际代收人类型 | +| `collectorAdminId` | Long(string) | 定制师/管理员代收人 ID | +| `collectorName` | string | 通用代收人姓名快照 | +| `collectorRole` | string | 通用代收人角色快照 | +| `transferRef` | string | 对公转账流水号（BANK_TRANSFER） | +| `receiptMethod` | string | 收款方式值 | +| `receiptMethodLabel` | string | 收款方式显示标签 | +| `voucherUrls` | string[] | 凭证图片 URL 列表 | +| `remark` | string | 备注 | +| `operatorName` | string | 登记人姓名 | +| `createTime` | string(datetime) | 登记时间 | +| `voided` | boolean | 是否已撤销 | +| `voidedByName` | string | 撤销人姓名 | +| `voidedAt` | string(datetime) | 撤销时间 | +| `voidReason` | string | 撤销原因 | +| `paidAmountAfter` | number | 登记/撤销后订单累计已付金额（仅登记/撤销响应有值，列表查询为 null） | +| `payStatusAfter` | string | 登记/撤销后订单支付状态（同上） | + +## ⑥ 枚举 / 数据字典 + +**收款渠道 `channel`**： + +| 值 | 含义 | 本次变化 | +|---|---|---| +| `CONSULTANT_COLLECTION` | 定制师代收 | 不变 | +| `BANK_TRANSFER` | 对公转账 | 不变 | +| `DRIVER_CASH` | 报账人收款 | **已下线**：options 不再返回、register 拒绝（520417）。⚠️ 但列表接口的历史数据仍可能出现该值（channelLabel=「报账人收款」），渲染映射不能删 | + +**款项类型 `payType`**：`DEPOSIT` 订金 / `BALANCE` 尾款 / `FULL` 全款（不变）。 + +**代收人类型 `collectorType`**：`ORDER_STAFF` / `CONSULTANT` / `COMPANY_ACCOUNT`（不变）。 + +**收款方式 `receiptMethod`**：走数据字典 `manual_receipt_method`（如 `WECHAT_TRANSFER` 微信转账、`CASH` 现金收款），以 options 接口实际返回为准。 + +## ⑦ 错误码 + +| 码 | 语义 | 触发场景 | +|---|---|---| +| **520417** | 报账人代收尾款已下线，请通过确认行程挂账主报账人代收 | **本次新增**：register 传 `channel=DRIVER_CASH` | +| 520401 | 收款渠道非法: {0} | register 传了枚举外的渠道值 | +| 520402 | 对公转账渠道必须填写转账流水号 | BANK_TRANSFER 缺 `transferRef` | +| 520407 | 订单已取消，不允许登记线下收款 | 订单状态 CANCELLED | +| 520412 | 订单没有可用定制师，不能登记定制师代收 | CONSULTANT_COLLECTION 但订单无定制师 | +| 520413 | 本次收款金额超过当前可收余额 | 金额超可收余额 | +| 520415 | 收款方式不能为空 | 渠道要求 receiptMethod 但未传 | +| 520416 | 收款方式非法: {0} | receiptMethod 不在字典内 | +| 520405 | 线下收款凭据不存在 | 撤销时 receiptId 无效或不属本单 | +| 520406 | 该收款凭据已撤销，无法重复操作 | 重复撤销 | +| 520414 | 当前订单状态禁止撤销收款 | 当前订单/流程状态不允许撤销 | + +> 注：原 DRIVER_CASH 专属错误码 520403（缺代收人）/ 520404（代收人不属本单）/ 520410（只能登尾款）/ 520411（必须选报账人）因入口下线在 register 链路不再可达，前端无需再处理这几个码（保留兼容无害）。 + +## ⑧ 示例 + +### 8.1 典型：options 返回 2 个渠道 + BANK_TRANSFER 登记成功 + +请求 `GET /v3/admin/order/2100123456789012345/payment/manual-receipt/options`（订单状态非待支付、尾款未收齐）： + +```json +{ + "code": 200, + "success": true, + "data": { + "channels": [ + { + "channel": "CONSULTANT_COLLECTION", + "channelText": "定制师代收", + "allowedPayTypes": ["BALANCE"], + "disabled": false, + "disabledReason": null, + "collectors": [ + { + "collectorType": "CONSULTANT", + "collectorId": "2090001111222233334", + "collectorName": "王定制", + "collectorRole": "CONSULTANT", + "collectorRoleText": "定制师", + "defaultSelected": true + } + ], + "receiptMethods": [ + { "value": "WECHAT_TRANSFER", "label": "微信转账", "defaultSelected": true }, + { "value": "CASH", "label": "现金收款", "defaultSelected": false } + ] + }, + { + "channel": "BANK_TRANSFER", + "channelText": "对公转账", + "allowedPayTypes": ["BALANCE"], + "disabled": false, + "disabledReason": null, + "collectors": [], + "receiptMethods": [] + } + ] + } +} +``` + +请求 `POST /v3/admin/order/2100123456789012345/payment/manual-receipt`： + +```json +{ + "channel": "BANK_TRANSFER", + "payType": "BALANCE", + "amount": 3000.00, + "transferRef": "GZL20260922001", + "remark": "客户对公转账尾款" +} +``` + +响应： + +```json +{ + "code": 200, + "success": true, + "data": { + "id": "2102999888777666555", + "orderId": "2100123456789012345", + "channel": "BANK_TRANSFER", + "channelLabel": "对公转账", + "payType": "BALANCE", + "payTypeLabel": "尾款", + "amount": 3000.00, + "receivedAt": "2026-09-22T17:00:00", + "transferRef": "GZL20260922001", + "collectorType": "COMPANY_ACCOUNT", + "voided": false, + "paidAmountAfter": 8800.00, + "payStatusAfter": "FULLY_PAID" + } +} +``` + +### 8.2 边界：订单无定制师 → 定制师代收渠道置灰 + +订单无定制师快照时，`CONSULTANT_COLLECTION` 渠道 `collectors` 为空且禁用： + +```json +{ + "channel": "CONSULTANT_COLLECTION", + "channelText": "定制师代收", + "allowedPayTypes": [], + "disabled": true, + "disabledReason": "订单没有可用定制师", + "collectors": [], + "receiptMethods": [ + { "value": "WECHAT_TRANSFER", "label": "微信转账", "defaultSelected": true }, + { "value": "CASH", "label": "现金收款", "defaultSelected": false } + ] +} +``` + +尾款已收齐时各渠道 `allowedPayTypes=[]`、`disabled=true`、`disabledReason="尾款已收齐，无可收余额"`；订单已取消时 `disabledReason="订单已取消，不能登记收款"`。 + +### 8.3 业务失败：DRIVER_CASH 登记被拒（520417） + +请求： + +```json +{ + "channel": "DRIVER_CASH", + "payType": "BALANCE", + "amount": 2000.00, + "collectorStaffId": "2099888777666555444", + "receiptMethod": "CASH" +} +``` + +响应： + +```json +{ + "code": 520417, + "success": false, + "message": "报账人代收尾款已下线，请通过确认行程挂账主报账人代收" +} +``` + +不会落库任何收款记录，订单金额无变化。 + +## ⑨ 业务边界 + +- **适用**：订单收到线下款项后补录（订金/全款仅限待支付状态，尾款在非待支付、非已取消状态）；定制师代收、对公转账两种渠道照常可用。 +- **不适用**：报账人（司机/导游）手持现金收尾款的场景——此入口已废除，改走「确认行程挂账主报账人代收」链路（后续 PR 上线，前端关注后续 changelog）。 +- **存量兼容**：历史已登记的 DRIVER_CASH 收款记录正常返回在列表接口、正常可撤销，撤销后 `paid_amount` 精确回退，行为与旧版一致。 +- **可收余额**：`amount` 不能超过订单当前可收余额（520413）；可收余额 ≤ 0 时各渠道 `allowedPayTypes` 为空且置灰。 +- **登记接口非幂等**：重复点击会产生重复收款记录，前端须做按钮防重。 + +## ⑩ 修改前后对比 + +### 字段/结构级 + +| 项 | 修改前 | 修改后 | +|---|---|---| +| options 出参 `channels[]` | `[CONSULTANT_COLLECTION, BANK_TRANSFER, DRIVER_CASH]`（3 项，DRIVER_CASH 项内含本单报账人候选 collectors） | `[CONSULTANT_COLLECTION, BANK_TRANSFER]`（2 项，**DRIVER_CASH 项整体移除**） | +| register 入参 `channel=DRIVER_CASH` | 合法值，可登记尾款（仅 BALANCE，需 collectorStaffId 属本单报账人） | 非法值，一律返回 520417，不落库 | + +### 行为级 + +| 项 | 修改前 | 修改后 | +|---|---|---| +| 报账人代收尾款登记 | 可在订单详情登记 | 入口下线，需走确认行程挂账主报账人代收（后续 PR） | +| 历史 DRIVER_CASH 记录查询/撤销 | 可查可撤 | 不变，仍可查可撤 | +| 订金/全款/尾款的定制师代收、对公转账补录 | 可用 | 不变，照常可用 | + +## ⑪ 影响评估 / 回滚 + +- **破坏兼容**：是。options 出参结构收缩（少一个渠道项）+ register 对 DRIVER_CASH 的行为从成功变为报错。 +- **前端同步上线要求**：前端必须先排查并适配（见 ⑫），否则若按旧 channels 结构硬编码索引/枚举映射，渠道 tabs 渲染或默认值逻辑可能异常；若仍向用户展示 DRIVER_CASH 入口，登记会收到 520417。 +- **后端兼容**：已合 dev-v3，未部署测试服；列表/撤销接口对历史数据完全兼容。 +- **回滚方案**：代码回滚至本 PR 前版本即恢复 DRIVER_CASH 渠道；下线期间不会产生新 DRIVER_CASH 数据，回滚无数据迁移负担。 + +## ⑫ 注意事项 + +1. **前端排查 options 消费方是否硬编码 DRIVER_CASH**：检查渠道 tabs 渲染、渠道枚举映射、默认渠道选中逻辑、channel 文案映射表（`DRIVER_CASH → 报账人收款`）等位置。options 不再返回该渠道，任何按「必有 3 项 / 必有 DRIVER_CASH」假设的代码都要清理。 +2. **列表接口渲染映射不能删 DRIVER_CASH**：历史收款记录仍可能返回 `channel=DRIVER_CASH`、`channelLabel=报账人收款`，列表/详情的展示映射需保留该值，否则历史行显示异常。 +3. 新错误码 520417 的 message 可直接透出给用户（文案即操作指引）。 +4. 原 DRIVER_CASH 专属错误码 520403/520404/520410/520411 在 register 链路不再可达，前端可不再处理。 + +## ⑬ 关联 / 联系人 + +- Issue：https://git.1814.love:8443/wx/HL/issues/8181 +- PR：https://git.1814.love:8443/wx/HL/pulls/8183 +- Commit：https://git.1814.love:8443/wx/HL/commit/a1fb7bc5ef6befa409696fdba7c1d98b840a7c4a +- 后端负责人：yst