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 入/出库任务；付款/收款审批通过将同步写入余额表。
余额审计	审批成功后会同步写入 BalanceChangeRecord，记录来源单据、方向、前后余额与冲抵占位字段，供审计/红冲使用。

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

---

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

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

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 创建请求体

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

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

6.3 余额变动记录（BalanceChangeRecord）

• 写入时机：仅在审批通过瞬间写入；审批成功后禁止作废，若需冲销必须通过红冲/对冲流程生成反向记录。
• 字段概要：
  • target_type：供应商 / 客户
  • source_type + source_id：关联具体业务对象（采购/销售/付款/收款）
  • delta / balance_before / balance_after / direction：记录本次增减与余额快照
  • offset_to / offset_id：预留冲抵链路，与库存 StockSnapshot 设计一致
  • request_id / extra_meta：用于幂等和记录审批上下文（操作者、触发渠道等）
• 用途：对账、审计、未来的余额红冲。目前未开放对外查询 API，可在内部管理端或报表服务中直接访问；若后续开放，请提供分页、时间范围与 source_type 过滤能力。

---

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：资金类单据与余额表写入逻辑。

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