erpnew/docs/payment_receipt_workflow.md

付款单 / 收款单流程说明

1. 概述

• PaymentOrder：针对供应商的资金支出单据，审批通过后代表“确认付款”。
• ReceiptOrder：针对客户的资金收入单据，审批通过后代表“确认收款”。
• 两者均位于 business 模块，API 路径分别为 /api/v1/payment-orders/、/api/v1/receipt-orders/。
• 与采购/销售相比，不涉及产品与库存，仅维护资金方向、对方主体、金额与状态。
• 审批通过会同步更新供应商/客户余额表（SupplierBalance / CustomerBalance），并写入 BalanceChangeRecord，提供 O(1) 的欠款查询与可追溯的余额流水。

2. 创建流程

字段	付款单	收款单
对方主体	supplier (供应商 ID)	customer (客户 ID)
日期	payment_date	receipt_date
金额	amount，必须 > 0	amount，必须 > 0
银行账户	bank_account（可选，引用 BankAccount）	bank_account（可选）
附言	markup（可选，记录票据附言）	markup（可选）
备注	remarks（可选，内部备注）	remarks（可选）
折扣	discount_amount（可选，≥0，可大于 amount）	同左

结算金额 = amount + discount_amount，所有余额调整与对账单统计均以结算金额为准，响应中通过只读字段 settlement_amount 展示。

创建成功返回 201，包含新建单据 ID、状态（默认 PENDING）与提示信息。

3. 审批 / 作废

• 接口：POST /api/v1/<payment|receipt>-orders/<id>/review/
• 请求体：{"action": "approve"} 或 {"action": "cancel"}
• 审批通过：状态变为 APPROVED，同步写入余额表与 BalanceChangeRecord（记录来源单据、方向、前后余额）；审批成功后禁止再作废。
• 作废：仅允许 PENDING 状态作废，状态变为 CANCELLED。若已审批或已作废会抛出业务错误（幂等）。

4. 常见异常

场景	响应
缺少主体/日期/金额	400 + {"error": "缺少 ... "}
金额 ≤ 0	400 + {"error": "amount 必须大于 0"}
目标单据不存在或非当前商户	404
无权限（用户非员工）	403

5. 与采购/销售单的关系

• 继承相同的方向抽象（get_direction()），可与采购/销售的金额统计组合成统一的应收/应付报表。
• 不触发库存任务，也没有 items、仓库等字段；扩展字段（如付款方式、附件）可在此基础上继续添加。
• 采购退货 / 销售退货等复合单据在审批时会同时触发库存与余额写入，可视为采购/销售单 + 资金单据的组合；资金类单据仍需保持独立，以便单独统计资金流水。