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. 错误码与常见响应