zuowei/erpnew

Fork 0

forked from erp-dev/erp

Files

colaftc d522c0a9b0 feat: statement for supplier and customer

2025-12-01 22:55:52 +08:00

12 KiB

Raw Blame History

Business 模块 API 汇总

本文件汇集 business 模块及其在 api_v1 下的所有接口，前端只需参考本页即可完成对接。所有接口均位于 /api/v1/，除明确说明外均需用户已登录且具备员工身份。

1. 通用约定

项	说明
认证	Session / Token（与项目统一）。用户必须关联 `Employee` 且属于目标 `Merchant`。
多租户	`request.user.employee.merchant` 自动限定数据范围，接口内部已校验，无需额外参数。
分页	列表接口使用 `limit` / `offset`，默认 `limit=20`，最大 `100`。
状态枚举	`1=PENDING`、`2=APPROVED`、`3=CANCELLED`。审批接口通过 `action=approve/cancel` 修改状态。
金额字段	字符串形式的十进制数（例如 `"123.45"`），与后端 `Decimal` 精度一致。
items 结构	受仓库模式影响： • 严进/严进严出：`numbers: [int,…]` 表示条数明细 • 宽进宽出：`quantity` + `num_of_rolls` • 严出：`consume_detail_ids: [detail_id,…]`
审批副作用	采购/销售审批通过后根据商户设置触发 Celery 入/出库任务；付款/收款审批通过将同步写入余额表。
余额审计	审批成功后会同步写入 `BalanceChangeRecord`，记录来源单据、方向、前后余额与冲抵占位字段，供审计/红冲使用。

错误响应统一为 {"error": "代码", "message": "描述"}，字段可能因场景扩展（如 record_id、fields 等）。

2. 采购相关：采购单 + 采购退货单

API	方法	描述
`/purchase-orders/`	GET	分页列表。
`/purchase-orders/`	POST	创建采购单。
`/purchase-orders/<id>/review/`	POST	审批或作废。

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`	否	可选信息

{
  "supplier": 12,
  "warehouse": 8,
  "order_date": "2025-11-30",
  "items": [
    {
      "product_id": 1001,
      "numbers": [30, 25],
      "price": "12.50",
      "unit": "米"
    }
  ],
  "remarks": "可选"
}

宽进仓将 numbers 换为 quantity + num_of_rolls。至少 1 条明细，否则返回 400。

2.2 审批

POST /purchase-orders/<id>/review/，请求体 {"action": "approve"} 或 {"action": "cancel"}。

approve：在事务内将状态置为 APPROVED、写入供应商余额（正向金额），并在商户开启自动任务时触发 create_purchase_order_stock_entries。
cancel：若已存在 StockChangeRecord（source=PURCHASE），返回 400；否则置为 CANCELLED。

成功返回最新的采购单序列化（含 items、total_amount、status_name 等）。

2.3 采购退货单（PurchaseReturnOrder）

API	方法	描述
`/purchase-return-orders/`	GET/POST	与采购单相同的查询/创建接口，字段改为 `return_date`。
`/purchase-return-orders/<id>/review/`	POST	审批或作废，流程与采购单一致。

创建字段：supplier、warehouse、return_date、items、可选 purchase_order。items 结构沿用采购单；当仓库 mode=RESTRICT_IN_OUT 时必须提供 consume_detail_ids，指明要冲销的入库明细。
审批逻辑：
- approve：在事务内锁单、构建 stock_flow_items，状态置为 APPROVED，调用 StockFlowService.stock_out（source=PURCHASE_RETURN），并向 BalanceService 写入负值以减少供应商应付。
- cancel：仅允许 PENDING 且尚未生成 StockChangeRecord 的单据；审批完成后禁止作废。

3. 销售相关：销售单 + 销售退货单

API	方法	描述
`/sales-orders/`	GET	分页列表。
`/sales-orders/`	POST	创建销售单。
`/sales-orders/<id>/review/`	POST	审批或作废。

3.1 创建请求体

销售单 items 字段同样支持 empty_diff_percent、color、spec、batch_number、remarks 等信息，用途与采购单一致；仓库模式决定使用 numbers、quantity + num_of_rolls 或 consume_detail_ids。

{
  "customer": 6,
  "warehouse": 3,
  "order_date": "2025-11-30",
  "items": [
    {
      "product_id": 1001,
      "numbers": [20, 18],
      "price": "18.80",
      "unit": "米"
    }
  ],
  "remarks": ""
}

仓库为严出（RESTRICT_IN_OUT）时必须改用：

{
  "product_id": 1001,
  "consume_detail_ids": [321, 322],
  "quantity": 200,
  "price": "20",
  "unit": "米"
}

3.2 审批

与采购单一致，但方向为出库：

approve：写入客户余额（正向欠款），若商户配置自动出库则触发 create_sales_order_stock_entries。
cancel：如果已存在 StockChangeRecord（source=SALES）则拒绝。

3.3 销售退货单（SalesReturnOrder）

API	方法	描述
`/sales-return-orders/`	GET/POST	创建 / 列表接口。
`/sales-return-orders/<id>/review/`	POST	审批或作废。

创建字段：customer、warehouse、return_date、items、可选 sales_order。因退货为入库动作，严出仓不再需要 consume_detail_ids。
审批逻辑：
- approve：状态置为 APPROVED，调用 StockFlowService.stock_in（source=SALES_RETURN），并向 BalanceService 写入负值以冲减客户欠款，同时写 BalanceChangeRecord。
- cancel：仅允许 PENDING 且未生成 StockChangeRecord 的单据；审批通过后不可作废。

4. 付款单（PaymentOrder）

API	方法	描述
`/payment-orders/`	GET	分页列表。
`/payment-orders/`	POST	创建付款单。
`/payment-orders/<id>/review/`	POST	审批或作废。

4.1 创建请求体

{
  "supplier": 12,
  "payment_date": "2025-11-30",
  "amount": "5000.00",
  "remarks": ""
}

amount 必须大于 0。返回 201 + 创建的记录。

4.2 审批逻辑

approve：在事务内锁定单据，防止重复审批；状态改为 APPROVED，并将供应商余额减少对应金额。
cancel：仅允许从 PENDING 作废，且若已审批则返回 400。

5. 收款单（ReceiptOrder）

API	方法	描述
`/receipt-orders/`	GET	列表。
`/receipt-orders/`	POST	创建收款单。
`/receipt-orders/<id>/review/`	POST	审批或作废。

5.1 创建

{
  "customer": 6,
  "receipt_date": "2025-11-30",
  "amount": "3200.00",
  "remarks": ""
}

5.2 审批

approve：状态改为 APPROVED，客户余额减少对应金额（冲减欠款）。若已取消则拒绝再次审批。
cancel：仅允许从 PENDING 作废；当单据已审批时返回 400。

6. 余额表 / 对账接口

余额数据来自 SupplierBalance / CustomerBalance 表，所有审批通过的单据均在事务内写入，保证与业务状态一致。

6.1 客户余额

API	方法	描述
`/customers/<id>/balance/`	GET	查询指定客户应收余额。

响应示例：

{
  "customer": 6,
  "customer_name": "杭州零售商",
  "balance": "3200.00"
}

正数表示客户仍欠款；负数表示已收超额。
若客户无记录返回 "0"。

6.2 供应商余额

API	方法	描述
`/suppliers/<id>/balance/`	GET	查询指定供应商待付余额。