hl-api-changelog/changelogs-v2/2026-09/22_8181_线下收款废除报账人代收DRIVER_CASH渠道-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8181	线下收款废除报账人代收 DRIVER_CASH 渠道（尾款收款模型重构 PR-1）	admin	yst(GIT)	修改接口	merged	not_required	not_required					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 前端核验(2026-09-22):渠道 radio 由 options.channels 数据驱动渲染(channelText 优先 CHANNEL_LABELS 兜底),无「必有 DRIVER_CASH」硬编码假设,下线自动生效;历史行渲染映射 CHANNEL_LABELS.DRIVER_CASH 按 ⑫-2 明示保留;520417 由 request.js 拦截器透 message(msg 即操作指引);表单 DRIVER_CASH 分支成惰性保留防回滚。行为零改动判 not_required;orderV2.js JSDoc 与映射注释订正(412d7408)。	2026-09-22	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（订单状态非待支付、尾款未收齐）：

{
  "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：

{
  "channel": "BANK_TRANSFER",
  "payType": "BALANCE",
  "amount": 3000.00,
  "transferRef": "GZL20260922001",
  "remark": "客户对公转账尾款"
}

响应：

{
  "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 为空且禁用：

{
  "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）

请求：

{
  "channel": "DRIVER_CASH",
  "payType": "BALANCE",
  "amount": 2000.00,
  "collectorStaffId": "2099888777666555444",
  "receiptMethod": "CASH"
}

响应：

{
  "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