feat: statement for supplier and customer

2025-12-01 22:55:52 +08:00
parent fae33809ac
commit d522c0a9b0
15 changed files with 1085 additions and 52 deletions
--- a/docs/business_api_reference.md
+++ b/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`：销售单审批与严出模式说明。
--- a/docs/stock_api_overview.md
+++ b/docs/stock_api_overview.md
@@ -71,6 +71,7 @@ The system supports various source types for stock changes:
 - `3`: Transport In (调入)
 - `4`: Recheck Addition (盘盈)
 - `5`: Combine (合并)
+- `11`: Offset (红冲，反向抵销入库)

 **Outgoing (出库) Sources**:
 - `6`: Sales (销售)
@@ -78,6 +79,7 @@ The system supports various source types for stock changes:
 - `8`: Transport Out (调出)
 - `9`: Recheck Removal (盘亏)
 - `10`: Explode (拆卷)
+- `11`: Offset (红冲，反向抵销出库)

 ### Warehouse Modes

@@ -359,7 +361,62 @@ Warehouses can operate in different modes:
 }
 ```

-### 4. Stock Snapshot List
+### 4. 库存红冲（Stock Change Offset）
+
+- **URL**: `POST /api/v1/stock-change/<id>/offset/`
+- **权限**：登录员工，且仓库必须属于当前商户。
+- **描述**：针对已完成的库存变动记录生成反向库存记录，恢复库存数量并标记原快照 `cancelled=true`。
+
+**Request Body**
+```json
+{
+  "reason": "采购单作废，冲销库存",
+  "request_id": "rcf-20251201-0001",   // 可选，幂等键
+  "extra_meta": { "source": "purchase_order", "operator": 18 }
+}
+```
+
+> **注意**：当前版本仅支持“全量红冲”，`items` 字段请留空；未来版本会按需要开放部分明细红冲能力。
+
+**Response**
+```json
+{
+  "status": "success",
+  "message": "红冲记录已创建",
+  "stock_change_record": {
+    "id": 602,
+    "type": 2,
+    "source_type": 11,
+    "source_id": 498,
+    "warehouse": 3,
+    "is_finished": true
+  },
+  "details": [
+    {
+      "id": 1880,
+      "product": 15,
+      "quantity": "100.00",
+      "unit": 1
+    }
+  ],
+  "created_details_count": 1
+}
+```
+
+**错误返回**
+
+| HTTP | 状态 | 说明 |
+|------|------|------|
+| 400 | `{"error": "仅允许对已完成的库存变动执行红冲"}` | 原记录未完成或仍在处理中 |
+| 400 | `{"error": "该库存变动记录已执行红冲"}` | 阻止重复红冲 |
+| 403 | `{"error": "无权访问该库存变动记录"}` | 仓库不属于当前商户 |
+| 404 | `{"error": "库存变动记录ID xxx 不存在"}` | 记录不存在 |
+
+红冲成功后，会生成 `source_type=OFFSET` 的库存记录，`source_id` 指向原库存记录 ID；原 `StockSnapshot` 会设置 `cancelled=true`、`offset_id=<新快照ID>`，便于审计追踪。
+
+---
+
+### 5. Stock Snapshot List

 - **URL**: `GET /api/v1/stock-snapshots/`
 - **Description**: Read-only list of `StockSnapshot` entries. Supports `limit/offset` pagination,搜索与过滤。