feat: statement api for business module

docs/business_api_reference.md

@@ -255,77 +255,18 @@
 
 ## 7. 对账单（Statements）
 
-对账单 API 汇总客户/供应商所有 **已审批通过** 的相关业务单据，并提供统一的金额正负视图，字段后续可通过 serializer context 继续扩展统计信息。
-
-### 7.1 客户对账单
+客户/供应商对账单提供统一的金额视图与余额快照，用于销售/采购结算场景。完整说明（含响应示例、字段定义与业务规则）请参阅 `docs/statements.md`。
 
 | API | 方法 | 描述 |
 |-----|------|------|
-| `/customers/<id>/statements/` | GET | 返回该客户的销售单、销售退货单、收款单对账记录。 |
+| `/customers/<id>/statements/` | GET | 指定客户的销售 / 销退 / 收款对账单 |
+| `/suppliers/<id>/statements/` | GET | 指定供应商的采购 / 采退 / 付款对账单 |
 
-```json
-{
-  "customer": 6,
-  "customer_name": "杭州零售商",
-  "records": [
-    {
-      "source_type": "sales_order",
-      "source_label": "销售单",
-      "source_id": 1024,
-      "occurred_at": "2025-11-30",
-      "recorded_at": "2025-12-01T03:26:18.815992Z",
-      "status": 2,
-      "status_label": "审批通过",
-      "counterparty": 6,
-      "counterparty_name": "杭州零售商",
-      "positive_amount": "3200.00",
-      "negative_amount": "0.00"
-    },
-    {
-      "source_type": "receipt_order",
-      "source_label": "收款单",
-      "source_id": 2001,
-      "occurred_at": "2025-12-05",
-      "recorded_at": "2025-12-05T02:11:07.441982Z",
-      "status": 2,
-      "status_label": "审批通过",
-      "counterparty": 6,
-      "counterparty_name": "杭州零售商",
-      "positive_amount": "0.00",
-      "negative_amount": "1500.00"
-    }
-  ],
-  "summary": {
-    "positive_total": "3200.00",
-    "negative_total": "1500.00"
-  }
-}
-```
+关键特性：
 
-- `records` 依照 `occurred_at -> recorded_at -> source_id` 倒序排列。
-- `positive_amount` 始终代表应收增加：销售单为正，其余（销售退货、收款）为负。
-- `summary` 通过 serializer context 生成，如需扩展其他统计字段可在视图中向 context 注入。
-
-### 7.2 供应商对账单
-
-| API | 方法 | 描述 |
-|-----|------|------|
-| `/suppliers/<id>/statements/` | GET | 返回该供应商的采购单、采购退货单、付款单对账记录。 |
-
-- 采购单为正向金额，采购退货与付款单为负向金额。
-- 其余字段与客户对账单完全一致。
-
-### 7.3 记录字段
-
-| 字段 | 说明 |
-|------|------|
-| `source_type` / `source_label` | 业务来源与可读名称（`sales_order`、`payment_order` 等）。 |
-| `source_id` | 原始单据 ID。 |
-| `occurred_at` / `recorded_at` | 业务日期（如 `sales_date`）与系统写入时间。 |
-| `status` / `status_label` | 当前单据状态。 |
-| `counterparty` / `counterparty_name` | 客户或供应商。 |
-| `positive_amount` / `negative_amount` | 金额正负值，字符串形式的 `Decimal`。 |
-| `extra` | 预留字典字段，后续可承载额外统计信息。 |
+- 固定按 `occurred_at -> recorded_at -> source_id` 倒序输出，不提供排序参数。
+- `positive_amount` / `negative_amount` 统一表示余额增减；`cumulative_amount`、`current_balance`、`arrears_amount` 均冗余在每条记录中，前端可直接使用。
+- 余额快照来自 `BalanceService`，每次请求只查询一次，保证与审批事务一致。
 
 ---