feat: red flush and cost

docs/2026-06-12_business_red_flush_design.md

@@ -10,6 +10,7 @@
 
 - 红冲后原单据 `status` 保持 `APPROVED`，不回退、不作废。
 - 原单据增加“已红冲”标记，用于列表查询提速。
+- 因为 `status` 保持 `APPROVED`，**对账单 builder 必须额外按 `is_red_flushed=False` 过滤**，否则红冲单会被原值计入 `positive_amount`/`negative_amount`，summary 多算一倍。
 - 每次红冲由 service 自动生成一个 UUID 类型的 `red_flush_id`。
 - `red_flush_id` 用于跨表、跨记录追踪同一次红冲涉及的所有数据，是审计关联批次 ID。
 - 不新增 `red_flush_no`。该编号只适合人工展示，目前无需求。
@@ -103,7 +104,7 @@
 - 只允许 `APPROVED` 单据红冲。
 - `is_red_flushed=True` 的单据不能重复红冲。
 - 原始余额变动记录必须存在且未被冲抵。
-- 有库存影响的单据必须找到对应库存记录，库存记录必须已完成且未被红冲。
+- 有库存影响且要求库存闭环的单据必须找到对应库存记录，库存记录必须已完成且未被红冲；销售单允许不存在库存记录，此时只红冲余额。
 - 资金和库存任一红冲失败，整体事务回滚。
 
 资金侧实现：
@@ -125,7 +126,7 @@
 新增 service 测试覆盖：
 
 - 采购单整单红冲：余额反向、库存反向、单据标记、批次 ID 写入。
-- 销售单整单红冲：余额反向、库存反向、单据标记、批次 ID 写入。
+- 销售单整单红冲：余额反向、单据标记、批次 ID 写入；若存在销售出库记录则同步库存反向，若无库存记录则跳过库存红冲。
 - 采购退货单整单红冲。
 - 销售退货单整单红冲。
 - 付款单整单红冲。
@@ -143,11 +144,25 @@ API 测试覆盖：
 - 无员工身份权限拒绝。
 - 跨商户查询隔离。
 - 外部付款/收款单拒绝。
-- 未审核、重复红冲、缺库存记录等 service 校验错误映射为 400。
+- 未审核、重复红冲、采购等要求库存闭环的单据缺库存记录等 service 校验错误映射为 400。
 - 成功响应包含 `is_red_flushed`、`red_flush_id`、`red_flushed_at`，并抽样断言余额/库存副作用。
 
 目标：red flush 关键 service/API 路径需要有定向测试覆盖。
 
+## 对账单 builder 联动修复（2026-06-22）
+
+`business.services._CustomerStatementBuilder._build_sales_records` / `_build_sales_return_records` / `_build_receipt_records` 以及 `_SupplierStatementBuilder._build_purchase_records` / `_build_purchase_return_records` / `_build_payment_records` 之前只过滤 `status=APPROVED`，未过滤 `is_red_flushed`。
+
+红冲后单据 `status` 仍为 `APPROVED`，所以会继续以原金额出现在 `build_customer_statement` / `build_supplier_statement` 的 `records` 列表中，被 `build_statement_summary` 双倍计入 `positive_total`/`negative_total`。
+
+修复办法：6 个 builder queryset 全部追加 `is_red_flushed=False`。
+
+注意：
+- `BalanceService.get_customer_balance` / `get_supplier_balance` 读取 `CustomerBalance/SupplierBalance` 表，红冲服务通过反向 `BalanceChangeRecord` 已经把余额抵消，因此 `current_balance` 字段一直是正确的；只有 `records` 与 `summary` 受影响。
+- `ExternalCustomerStatementOrder` 目前不在 6 类红冲入口里，相关 builder/adjustment 暂不需要过滤，将来若开放外部单红冲必须同步更新。
+
+定向测试：见 `business.tests.test_statement_services.BusinessStatementRedFlushExclusionTestCase`，覆盖 6 类正式单据红冲后 statement 中 `records` 不再包含、`summary` 不再多算。
+
 ## 测试命令
 
 开发环境在容器内运行测试，并绕过 PgBouncer：