erpnew/docs/business_api_reference.md

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 入/出库任务；付款/收款审批通过将同步写入余额表。

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

---

2. 采购单（PurchaseOrder）

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

2.1 创建请求体

{
  "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 等）。

---

3. 销售单（SalesOrder）

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

3.1 创建请求体

{
  "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）则拒绝。

---

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 供应商余额

目前仅内部使用（审批写入），如需对外查询可在此基础上新增 /suppliers/<id>/balance/，逻辑与客户一致：采购单审批增加余额、付款单审批减少余额。

---

7. 错误码与常见响应

场景	HTTP	返回
未登录 / 认证失败	401	{"detail": "Authentication credentials were not provided."}
非本商户数据	403	{"error": "forbidden", "message": "无权限访问"}
单据不存在	404	{"error": "purchase_order_not_found"} 等
审批非法状态	400	例如 {"error": "purchase_order_has_stock_records"}、{"error": "receipt_order_already_approved"}
余额功能未实现	501	仅限未来拓展，例如库存红冲尚未开放

---

8. 参考文档

• docs/purchase_order_approval_and_red_flush.md：采购单审批及未来红冲方案。
• docs/sales_order_approval_and_red_flush.md：销售单审批与严出模式说明。
• docs/payment_receipt_workflow.md：资金类单据与余额表写入逻辑。

本汇总会随着业务扩展同步更新，如需新增接口请补充到此文件以保持前端“单文档”体验。***