From b1c170c5a9646994af1dd7935431279790d709f7 Mon Sep 17 00:00:00 2001
From: tangweijie <877588133@qq.com>
Date: Tue, 30 Jun 2026 16:16:30 +0800
Subject: [PATCH] docs: design counter unsettled red flush

---
 ...6-30-counter-unsettled-red-flush-design.md | 142 ++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-30-counter-unsettled-red-flush-design.md

diff --git a/docs/superpowers/specs/2026-06-30-counter-unsettled-red-flush-design.md b/docs/superpowers/specs/2026-06-30-counter-unsettled-red-flush-design.md
new file mode 100644
index 0000000..bdfc8ae
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-30-counter-unsettled-red-flush-design.md
@@ -0,0 +1,142 @@
+# 柜台未结账正式红冲设计
+
+## 背景
+
+当前 `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 结果。
+