# REV-003 营业收费 P0 整改设计

## 1. 目标

在不破坏历史数据查询的前提下，将柜台收费从“逐账单通用更新”迁移为服务端专用、可幂等、可并发保护、可准确结账和可完整红冲的交易链路。

## 2. 范围

本设计包含五个柜台主链路工作包和一个外部资金工作包：

1. 统一本金、违约金、渠道实收、预存抵扣和多缴转预存口径。
2. 新增专用批量柜台收费接口，在一个事务中处理多个账单。
3. 柜员结账改为按明确的支付记录 ID 集合确认。
4. 修复已结账和未结账预存红冲。
5. 增加账户行锁、请求幂等键和关键唯一约束，封堵通用支付旁路。
6. 修复银行冲正错误成功和预存审批回调重放；银行全量 outbox 状态机作为该工作包的后续增强，不阻塞柜台主链路首批上线。

本轮不扩展新的支付渠道适配器、发票平台、打印平台和柜员现金盘点页面。非现金渠道在没有真实渠道确认信息时不得通过新接口直接销账。

## 3. 方案比较

### 方案 A：继续修补现有逐账单 `/charge/update`

优点是改动小；缺点是无法提供跨账单事务、请求幂等和清晰的支付边界，通用 CRUD 仍可绕过财务校验。拒绝采用。

### 方案 B：新增专用柜台收费接口，保留旧接口作为非支付兼容入口

新接口负责金额校验、账户锁定、支付事实和账单投影；前端一次提交全部账单。旧接口禁止产生新的柜台支付状态迁移。该方案兼容历史查询和已有数据模型，风险可控。采用此方案。

### 方案 C：立即重建统一支付平台和单一支付主单模型

长期最完整，但会同时影响银行、微信、支付宝、代扣、发票和对账，超出单个 P0 修复窗口。作为后续支付域重构方向，不在本轮直接实施。

## 4. 目标架构

```text
前端选择账单
  -> POST /business/charge/counter-charge/submit
  -> 服务端按 requestId 查询幂等结果
  -> 锁定账单和主付款账户
  -> 重新计算本金、违约金、预存抵扣和渠道应收
  -> 校验页面期望金额与服务端金额
  -> 写同一 paymentBatchNo 下的支付记录和明细
  -> 扣减预存、处理多缴转预存并写账户流水
  -> 条件更新账单为已收
  -> 返回批次号、支付记录、金额拆分和余额结果
```

现阶段继续保留“一张账单一条 PaymentRecord”，通过 `payment_batch_no` 和 `request_id` 形成一次业务收费批次。这样避免一次性重写现有查询、红冲和发票关联逻辑，同时满足跨账单事务和批次凭证要求。

## 5. 金额模型

每张账单：

```text
principalAmount = max(extendedAmount, 0)
lateFeeAmount = max(lateFee, 0)
receivableAmount = principalAmount + lateFeeAmount
channelAmount + prepayAmount = receivableAmount
```

整个收费批次：

```text
totalReceivable = sum(receivableAmount)
actualChannelAmount + totalPrepayAmount
  = totalReceivable + overpayTopupAmount
```

PaymentRecord 字段口径：

- `payment_amount`：该账单实际核销总额，等于本金加违约金。
- `bill_amount`：本金。
- `late_fee_amount`：违约金。
- `channel_amount`：外部渠道实收。
- `prepay_amount`：预存抵扣。
- `overpay_amount`：仅独立多缴转预存记录使用；账单支付记录固定为零。
- `allocated_amount`：实际核销金额，账单支付时等于 `payment_amount`。

柜员结账只汇总 `channel_amount`，预存抵扣单独展示，不计入柜员应交渠道资金。

## 6. 接口设计

### 6.1 批量柜台收费

`POST /admin-api/business/charge/counter-charge/submit`

请求：

```json
{
  "requestId": "uuid-or-terminal-request-no",
  "chargeIds": [1001, 1002],
  "expectedReceivableAmount": 120.50,
  "actualPayAmount": 70.50,
  "usePrepay": true,
  "chargeWay": 1,
  "remark": "柜台收费"
}
```

规则：

- `requestId` 必填，同租户内相同请求重复提交返回首次成功结果。
- `chargeIds` 去重后不能为空，所有账单必须处于未收状态。
- 服务端重新计算应收；与 `expectedReceivableAmount` 不一致时拒绝并要求刷新。
- `actualPayAmount` 允许为零，但只允许出现在全额预存抵扣场景。
- 少付拒绝；多缴仅允许账单归属同一个主付款账户，多缴部分在同一事务生成独立预存记录。
- 首批新接口只允许现金渠道直接完成；其他渠道必须有真实渠道确认能力后再加入允许列表。
- 收费员、收费时间和网点由登录上下文生成，不接受客户端覆盖。

响应：

```json
{
  "paymentBatchNo": "CP202607150001",
  "paymentRecordIds": [5001, 5002],
  "totalReceivableAmount": 120.50,
  "channelAmount": 70.50,
  "prepayAmount": 50.00,
  "overpayTopupAmount": 0.00,
  "balanceAfter": 0.00
}
```

### 6.2 柜台预存

保留 `POST /business/charge/counter-topup` 路径，增加必填 `requestId`，收费员和时间改为服务端生成。充值支付记录写入 `channel_amount`、`request_id` 和 `payment_batch_no`。

### 6.3 柜员结账

`POST /business/charge/counter-settle/confirm` 增加必填 `paymentRecordIds`：

```json
{
  "paymentRecordIds": [5001, 5002],
  "settleTime": "2026-07-15T18:00:00",
  "remark": "当班结账"
}
```

服务端只结清这些记录，并校验记录均属于当前登录收费员、均为未结账、均未绑定其他结账单。结账金额汇总 `channel_amount`，同时在明细中保留账单金额和预存抵扣金额。

## 7. 幂等与并发

- `biz_payment_record` 增加 `request_id`、`payment_batch_no`、`channel_amount`、`prepay_amount`、`overpay_amount`。
- 柜台账单支付增加 `(tenant_id, request_id, biz_scene, source_ref_id)` 条件唯一索引。
- 柜台充值增加 `(tenant_id, request_id, biz_scene)` 条件唯一索引。
- 反向支付增加 `(tenant_id, related_payment_record_id, biz_scene)` 条件唯一索引。
- 收费事务对所选营业账按 ID 排序并加行锁，对主付款账户按客户 ID 排序并加行锁，避免死锁。
- 账户增减统一从 `SELECT ... FOR UPDATE` 获取余额，再写余额和 AccountLog。
- 账单投影使用 `WHERE pay_state = UNPAID` 的条件更新，更新数不等于预期时整批回滚。

## 8. 红冲设计

- 未结账账单支付：原支付改为 `REVERSED`，追加 `CHARGE_REVERSE/OUT`，恢复预存抵扣并将账单恢复未收。
- 已结账账单支付：先反转结账明细，再执行同样的支付反向和账单恢复。
- 未结账预存：调用 `markCounterUnsettledTopupReversed`，扣减账户余额，追加 `DEPOSIT_REFUND/OUT`。
- 已结账预存：调用 `markCounterSettleTopupReversed`，反转结账明细，扣减账户余额，追加 `DEPOSIT_REFUND/OUT`。
- 红冲原因前后端统一必填。
- 数据库唯一索引阻止同一原支付产生两张相同业务场景的反向单。

## 9. 高风险旁路

- 通用 `updateCharge` 不再允许从未收到已收的柜台支付迁移，调用方必须使用新接口。
- 已收或已结账营业账禁止通过通用删除接口删除。
- 账户通用更新不得直接改变 `deposit`；账户删除至少要求余额为零且不存在有效流水。
- `invalidCharge` 在未实际执行反向处理时必须抛出明确错误，银行侧不得以非空对象判断冲正成功。
- 预存审批成功回调只允许从一个明确待执行状态进入完成状态；完成状态重放直接返回，不再修改余额。

## 10. 前端设计

- 实收金额改为受控金额输入，提交前校验有限数、非负和两位小数。
- 应收金额使用 `本金 + 违约金`，不再只取 `extendedAmount`。
- 前端不再计算逐账单预存分配，只提交 `usePrepay` 和批次金额，由服务端返回最终拆分。
- 收费确认框展示应收、本金、违约金、预存抵扣、渠道实收和多缴转预存。
- 一次调用批量收费接口；任何失败均不在前端制造部分成功状态。
- 柜员结账表格真实维护选择状态，确认请求提交选中的 `paymentRecordIds` 和对应金额。
- 配置加载失败时只保留现金安全默认项；没有真实渠道确认能力的方式不可提交。
- “删除账单”改名为“本次不收”。

## 11. 错误处理

- 金额变化：返回“账单金额已变化，请刷新后重新收费”。
- 幂等重复：返回首次成功批次，不重复扣款或充值。
- 并发收费：条件更新失败后整批回滚并返回“账单已被其他操作处理”。
- 余额不足：整批回滚，返回最新可用余额。
- 结账范围失效：任何选中记录已结账或不属于当前收费员时，整批拒绝。
- 红冲余额不足：不修改原支付和结账状态，返回“红冲预存款余额不足”。

## 12. 测试设计

必须按 TDD 完成：

1. 本金 100、违约金 10，收费总额必须为 110，支付明细本金 100、违约金 10。
2. `actualPayAmount` 为负数、少付、非数字映射结果时拒绝。
3. 两张账单第二张更新失败，第一张支付、预存和账单状态全部回滚。
4. 同一 `requestId` 重复收费或充值，只产生一组支付事实。
5. 同一账单并发收费，只有一个请求成功。
6. 同一账户并发扣款或充值，余额和账户流水不丢失。
7. 当前页选择两条结账时，后端只结这两条。
8. 已结账和未结账预存分别可以红冲；重复红冲只产生一张反向单。
9. 银行冲正未实际反向时返回失败。
10. 预存审批完成回调重放不重复修改余额。

前端验证使用 `node:test`、现有页面 smoke 或 Playwright；不运行 `vue-tsc`。后端按相关测试类单独执行，数据库集成测试继续由 `REV004_IT_DB_URL` 门禁控制。

## 13. 发布与兼容

1. 先部署数据库新增列和唯一索引，新增列允许为空，历史记录不强制回填。
2. 部署后端新接口及旧接口支付迁移封堵。
3. 部署前端切换到新接口。
4. 观察支付批次、账户流水和结账差异后，再将非现金渠道逐一接入真实确认流程。
5. 历史记录继续按旧字段读取；新记录优先使用显式金额拆分字段。

回滚时前端可切回旧页面版本，但后端不恢复通用接口的支付旁路；数据库新增列保留，不执行破坏性回滚。