feat: statement for supplier and customer

docs/business_api_reference.md

@@ -31,6 +31,17 @@
 
 ### 2.1 创建请求体
 
+`items` 数组支持以下字段：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `product_id` | 是 | 产品 ID |
+| `price` | 是 | 单价 |
+| `unit` | 否 | 单位，默认使用产品单位 |
+| `numbers` / `quantity` + `num_of_rolls` | 仓库模式相关 | 严进提供 `numbers`，宽进提供 `quantity`/`num_of_rolls` |
+| `empty_diff_percent` | 否 | **空差百分比**，用于计算实际数量与空差（默认 `0`） |
+| `color` / `spec` / `batch_number` / `remarks` | 否 | 可选信息 |
+
 ```json
 {
   "supplier": 12,
@@ -83,6 +94,8 @@
 
 ### 3.1 创建请求体
 
+销售单 `items` 字段同样支持 `empty_diff_percent`、`color`、`spec`、`batch_number`、`remarks` 等信息，用途与采购单一致；仓库模式决定使用 `numbers`、`quantity + num_of_rolls` 或 `consume_detail_ids`。
+
 ```json
 {
   "customer": 6,
@@ -212,7 +225,22 @@
 
 ### 6.2 供应商余额
 
-目前仅内部使用（审批写入），如需对外查询可在此基础上新增 `/suppliers/<id>/balance/`，逻辑与客户一致：采购单审批增加余额、付款单审批减少余额。
+| API | 方法 | 描述 |
+|-----|------|------|
+| `/suppliers/<id>/balance/` | GET | 查询指定供应商待付余额。 |
+
+响应示例：
+
+```json
+{
+  "supplier": 3,
+  "supplier_name": "桐乡面料商",
+  "balance": "1850.00"
+}
+```
+
+- 正数表示仍需支付给供应商的金额；负数表示预付或多付。
+- 若供应商无记录返回 `"0"`。
 
 ### 6.3 余额变动记录（BalanceChangeRecord）
 
@@ -225,9 +253,83 @@
   - `request_id / extra_meta`：用于幂等和记录审批上下文（操作者、触发渠道等）
 - **用途**：对账、审计、未来的余额红冲。目前未开放对外查询 API，可在内部管理端或报表服务中直接访问；若后续开放，请提供分页、时间范围与 `source_type` 过滤能力。
 
+## 7. 对账单（Statements）
+
+对账单 API 汇总客户/供应商所有 **已审批通过** 的相关业务单据，并提供统一的金额正负视图，字段后续可通过 serializer context 继续扩展统计信息。
+
+### 7.1 客户对账单
+
+| API | 方法 | 描述 |
+|-----|------|------|
+| `/customers/<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` | 预留字典字段，后续可承载额外统计信息。 |
+
 ---
 
-## 7. 错误码与常见响应
+## 8. 错误码与常见响应
 
 | 场景 | HTTP | 返回 |
 |------|------|------|
@@ -239,7 +341,7 @@
 
 ---
 
-## 8. 参考文档
+## 9. 参考文档
 
 - `docs/purchase_order_approval_and_red_flush.md`：采购单审批及未来红冲方案。
 - `docs/sales_order_approval_and_red_flush.md`：销售单审批与严出模式说明。