feat: BalanceChangeRecord

docs/business_api_reference.md

@@ -15,6 +15,7 @@
 | 金额字段 | 字符串形式的十进制数（例如 `"123.45"`），与后端 `Decimal` 精度一致。 |
 | items 结构 | 受仓库模式影响：<br>• 严进/严进严出：`numbers: [int,…]` 表示条数明细<br>• 宽进宽出：`quantity` + `num_of_rolls`<br>• 严出：`consume_detail_ids: [detail_id,…]` |
 | 审批副作用 | 采购/销售审批通过后根据商户设置触发 Celery 入/出库任务；付款/收款审批通过将同步写入余额表。 |
+| 余额审计 | 审批成功后会同步写入 `BalanceChangeRecord`，记录来源单据、方向、前后余额与冲抵占位字段，供审计/红冲使用。 |
 
 错误响应统一为 `{"error": "代码", "message": "描述"}`，字段可能因场景扩展（如 `record_id`、`fields` 等）。
 
@@ -189,6 +190,17 @@
 
 目前仅内部使用（审批写入），如需对外查询可在此基础上新增 `/suppliers/<id>/balance/`，逻辑与客户一致：采购单审批增加余额、付款单审批减少余额。
 
+### 6.3 余额变动记录（BalanceChangeRecord）
+
+- **写入时机**：仅在审批通过瞬间写入；审批成功后禁止作废，若需冲销必须通过红冲/对冲流程生成反向记录。
+- **字段概要**：
+  - `target_type`：供应商 / 客户
+  - `source_type` + `source_id`：关联具体业务对象（采购/销售/付款/收款）
+  - `delta / balance_before / balance_after / direction`：记录本次增减与余额快照
+  - `offset_to / offset_id`：预留冲抵链路，与库存 `StockSnapshot` 设计一致
+  - `request_id / extra_meta`：用于幂等和记录审批上下文（操作者、触发渠道等）
+- **用途**：对账、审计、未来的余额红冲。目前未开放对外查询 API，可在内部管理端或报表服务中直接访问；若后续开放，请提供分页、时间范围与 `source_type` 过滤能力。
+
 ---
 
 ## 7. 错误码与常见响应

docs/payment_receipt_workflow.md

@@ -5,7 +5,7 @@
 - `ReceiptOrder`：针对客户的资金收入单据，审批通过后代表“确认收款”。
 - 两者均位于 `business` 模块，API 路径分别为 `/api/v1/payment-orders/`、`/api/v1/receipt-orders/`。
 - 与采购/销售相比，不涉及产品与库存，仅维护资金方向、对方主体、金额与状态。
-- 审批通过会同步更新供应商/客户余额表（`SupplierBalance` / `CustomerBalance`），提供 O(1) 的欠款查询。
+- 审批通过会同步更新供应商/客户余额表（`SupplierBalance` / `CustomerBalance`），并写入 `BalanceChangeRecord`，提供 O(1) 的欠款查询与可追溯的余额流水。
 
 ## 2. 创建流程
 | 字段 | 付款单 | 收款单 |
@@ -20,8 +20,8 @@
 ## 3. 审批 / 作废
 - 接口：`POST /api/v1/<payment|receipt>-orders/<id>/review/`
 - 请求体：`{"action": "approve"}` 或 `{"action": "cancel"}`
-- 审批通过：状态变为 `APPROVED`，后续可用于应付/应收对账。
-- 作废：状态变为 `CANCELLED`；若已是目标状态则返回原状态（幂等）。
+- 审批通过：状态变为 `APPROVED`，同步写入余额表与 `BalanceChangeRecord`（记录来源单据、方向、前后余额）；审批成功后禁止再作废。
+- 作废：仅允许 `PENDING` 状态作废，状态变为 `CANCELLED`。若已审批或已作废会抛出业务错误（幂等）。
 
 ## 4. 常见异常
 | 场景 | 响应 |