# 付款单 / 收款单流程说明

## 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`、仓库等字段；扩展字段（如付款方式、附件）可在此基础上继续添加。
- 采购退货 / 销售退货等复合单据在审批时会**同时**触发库存与余额写入，可视为采购/销售单 + 资金单据的组合；资金类单据仍需保持独立，以便单独统计资金流水。
