fix: docs

docs/business_api_reference.md

@@ -284,7 +284,30 @@
   - `delta / balance_before / balance_after / direction`：记录本次增减与余额快照
   - `offset_to / offset_id`：预留冲抵链路，与库存 `StockSnapshot` 设计一致
   - `request_id / extra_meta`：用于幂等和记录审批上下文（操作者、触发渠道等）
-- **用途**：对账、审计、未来的余额红冲。目前未开放对外查询 API，可在内部管理端或报表服务中直接访问；若后续开放，请提供分页、时间范围与 `source_type` 过滤能力。
+- **用途**：对账、审计和红冲追踪。业务单据红冲会生成反向 `BalanceChangeRecord`，并通过 `offset_to / offset_id / red_flush_id` 与原记录关联。目前余额变动记录仍未开放对外查询 API，可在内部管理端或报表服务中直接访问；若后续开放，请提供分页、时间范围与 `source_type` 过滤能力。
+
+### 6.4 业务单据红冲（Red Flush）
+
+正式业务单据已开放整单红冲入口，详细说明请参阅独立文档 `docs/2026-06-12_business_red_flush_api.md`。
+
+| API | 方法 | 描述 |
+|-----|------|------|
+| `/purchase-orders/<id>/red-flush/` | POST | 红冲已审批采购单，反向余额和库存影响 |
+| `/sales-orders/<id>/red-flush/` | POST | 红冲已审批销售单，反向余额和库存影响 |
+| `/purchase-return-orders/<id>/red-flush/` | POST | 红冲已审批采购退货单，反向余额和库存影响 |
+| `/sales-return-orders/<id>/red-flush/` | POST | 红冲已审批销售退货单，反向余额和库存影响 |
+| `/payment-orders/<id>/red-flush/` | POST | 红冲已审批付款单，反向供应商余额 |
+| `/receipt-orders/<id>/red-flush/` | POST | 红冲已审批收款单，反向客户余额 |
+
+请求体：
+
+```json
+{
+  "reason": "录入错误，需要红冲"
+}
+```
+
+`reason` 必填且不能为空。红冲成功后原单据状态保持已审批，并返回 `is_red_flushed=true`、`red_flush_id`、`red_flushed_at`。外部来源付款/收款单不允许红冲。
 
 ## 7. 对账单（Statements）
 
@@ -314,13 +337,15 @@
 | 非本商户数据 | 403 | `{"error": "forbidden", "message": "无权限访问"}` |
 | 单据不存在 | 404 | `{"error": "purchase_order_not_found"}` 等 |
 | 审批非法状态 | 400 | 例如 `{"error": "purchase_order_has_stock_records"}`、`{"error": "receipt_order_already_approved"}` |
-| 余额功能未实现 | 501 | 仅限未来拓展，例如库存红冲尚未开放 |
+| 红冲非法状态 | 400 | 例如未审批、重复红冲、缺少可红冲库存/余额记录、外部来源单据不允许红冲 |
 
 ---
 
 ## 9. 参考文档
 
-- `docs/purchase_order_approval_and_red_flush.md`：采购单审批及未来红冲方案。
+- `docs/2026-06-12_business_red_flush_api.md`：业务单据红冲独立 API 文档。
+- `docs/2026-06-12_business_red_flush_design.md`：业务单据红冲 service/API 设计备查。
+- `docs/purchase_order_approval_and_red_flush.md`：采购单审批与红冲背景。
 - `docs/sales_order_approval_and_red_flush.md`：销售单审批与严出模式说明。
 - `docs/payment_receipt_workflow.md`：资金类单据与余额表写入逻辑。