# 柜台未结账正式红冲设计

## 背景

当前 `water-backend` 已实现柜台已结账红冲：`POST /admin-api/business/charge/counter-settle/red-flush` 先查 `biz_settle_record_detail`，再校验支付主单 `settleStatus=SETTLED`，因此只能处理已结清记录。历史操作手册要求柜台结账模块的“未结账”和“已结账”页签均可红冲。

本设计补齐“未结账正式红冲”能力。用户已确认业务口径：未结账红冲也按正式红冲处理；红冲后原收费记录不再参与后续柜台结账汇总，只能通过红冲记录查询和导出追溯。

## 目标

- 支持对未结账柜台收费记录执行正式红冲。
- 生成正式反向支付流水，保留原收费主单与反向流水关联。
- 红冲后原收费主单从待结清列表消失，后续结账确认不再统计。
- 红冲记录查询和导出能同时覆盖已结账红冲与未结账红冲。
- 保留红冲原因、经办人、红冲时间、客户、金额、原收费单号等审计字段。

## 非目标

- 不把未结账红冲伪造成普通结账单。
- 不改变已结账红冲的现有业务语义。
- 不在本次设计中扩展发票红冲、渠道退款、银行对账红冲等其他场景。
- 不修改 `.specify/` 流程工件。

## 推荐方案

采用“新增未结账正式红冲路径 + 独立红冲投影”的方案。

已结账红冲继续复用现有 `biz_settle_record` / `biz_settle_record_detail` 路径。未结账红冲不创建普通结账单，而是在支付主单和账单完成红冲状态流转后，写入一条未结账红冲投影记录。红冲记录查询将已结账明细和未结账投影合并返回。

不推荐先生成“红冲专用结清单”，因为这会让未结账业务产生结账单号，污染结账汇总、打印和财务日结语义。

## 接口设计

继续使用现有接口：

- `POST /admin-api/business/charge/counter-settle/red-flush`

请求对象 `CounterRedFlushReqVO` 保持兼容：

- `paymentRecordIds`：待红冲支付主单 ID 列表。
- `reason`：红冲原因。
- `operatorId`：兼容字段，实际操作人以当前登录用户为准。

接口行为按支付主单状态分流：

- `SETTLED` 且存在 `biz_settle_record_detail`：走现有已结账红冲逻辑。
- `UNSETTLED` 且 `settleId=null`：走新增未结账正式红冲逻辑。
- 同一批次中不建议混合已结账和未结账记录；若混合会增加事务回滚和结果解释复杂度，推荐直接拒绝并提示分批操作。

## 数据设计

新增未结账红冲投影表，建议命名为 `biz_counter_unsettled_red_flush_record`。

核心字段：

- `id`
- `payment_record_id`：原收费支付主单 ID，唯一约束。
- `payment_no`：原收费单号。
- `reverse_payment_record_id`：反向支付主单 ID。
- `reverse_payment_no`：反向支付单号。
- `charge_id`
- `source_cust_id`
- `source_cust_code`
- `source_cust_name`
- `cashier_id`
- `reversed_amount`
- `reversed_time`
- `reverse_reason`
- `proc_person`
- `proc_type`：固定为 `COUNTER_UNSETTLED_RED_FLUSH`。
- `tenant_id`、`creator`、`create_time`、`updater`、`update_time`、`deleted`

约束：

- `payment_record_id + tenant_id` 唯一，防止重复红冲。
- 按 `cashier_id + reversed_time`、`source_cust_code + reversed_time` 建普通索引，支撑红冲记录查询。

## 流程设计

未结账红冲流程：

1. 根据 `paymentRecordIds` 查询支付主单。
2. 校验每条记录均为柜台收费来源、收入方向、收费业务场景、`settleStatus=UNSETTLED`、`settleId=null`。
3. 校验当前登录收费员只能红冲自己的收费记录；具备管理权限的后台角色可按既有权限模型扩展。
4. 查询关联账单 `ChargeDO`，要求账单仍能与该收费主单匹配。
5. 调用现有 `PaymentCommandApplicationService.reverseChargePayment(charge)` 生成反向流水。
6. 将原支付主单更新为 `settleStatus=REVERSED`，并要求更新条件仍是 `UNSETTLED` 和 `settleId=null`。
7. 将账单恢复到可再次收费状态，状态规则与现有收费红冲保持一致。
8. 写入 `biz_counter_unsettled_red_flush_record`。
9. 返回红冲笔数、现金退回金额、预存抵扣退回金额等汇总结果。

待结清列表继续只查询 `settleStatus=UNSETTLED` 且 `settleId=null` 的收入主单。原收费主单改为 `REVERSED` 后自然不再出现，也不会被结清确认统计。

## 红冲记录查询

现有红冲记录查询从 `biz_settle_record_detail.detail_status=REVERSED` 读取已结账红冲记录。新增后查询逻辑改为合并两个来源：

- 已结账红冲：沿用现有 `biz_settle_record` + `biz_settle_record_detail`。
- 未结账红冲：读取 `biz_counter_unsettled_red_flush_record`。

响应 VO 可保持兼容：

- 未结账红冲的 `settleId`、`settleNo` 为空。
- `paymentRecordId`、`paymentNo`、客户、收费员、红冲金额、红冲时间、红冲原因正常返回。

导出逻辑使用同一合并查询，确保页面查询和 Excel 导出一致。

## 异常处理

- 支付主单不存在：拒绝。
- 已红冲：拒绝重复处理。
- 已结账与未结账记录混批：拒绝，提示分批红冲。
- 未结账记录已被其他事务结清：更新原支付主单为 `REVERSED` 时影响行数为 0，拒绝并回滚。
- 未结账记录已被其他事务红冲：唯一约束或状态更新失败，拒绝并回滚。
- 反向流水生成失败：拒绝并回滚，不写红冲投影。

## 测试设计

后端单测覆盖：

- 未结账柜台收费红冲成功：生成反向流水、原主单改为 `REVERSED`、写红冲投影、待结清不再出现。
- 未结账红冲记录查询和导出可查到记录，且 `settleNo` 为空。
- 已结账红冲现有行为不回归。
- 已结账和未结账混批被拒绝。
- 重复红冲被拒绝。
- 当前收费员红冲他人未结账收费被拒绝。
- 并发结账或并发红冲导致状态更新失败时回滚。

最小验证建议：

- `mvn -pl sw-business/sw-business-server -Dtest=CounterSettleApplicationServiceImplTest test`
- 如涉及 mapper SQL 或集成数据，补充受环境变量控制的柜台结账接口集成测试。

## 文档与证据

实现后需要回写：

- `docs/design/02_Detailed_Design/12_REV_Detailed.md`：明确未结账红冲与已结账红冲的状态边界。
- `docs/design/03_Technical_Design/01_Database_Design.md`：补充未结账红冲投影表。
- `docs/design/03_Technical_Design/03_Interface_Design.md`：补充 `counter-settle/red-flush` 对未结账记录的处理约束。
- `docs/evidence/bugfix/` 或对应模块 evidence：记录编译、单测、最小 smoke 结果。