feat: add discount_amount to payment_order and receipt_order, and change total_amount logic

docs/business_api_reference.md

@@ -159,13 +159,22 @@
 ```json
 {
   "supplier": 12,
+  "bank_account": 3,
   "payment_date": "2025-11-30",
   "amount": "5000.00",
-  "remarks": ""
+  "discount_amount": "120.00",
+  "remarks": "",
+  "markup": "审批备注"
 }
 ```
 
-`amount` 必须大于 0。返回 201 + 创建的记录。
+字段说明：
+
+- `bank_account`：可选，引用 `basic_info.BankAccount`，用于记录具体的付款账户。
+- `markup`：可选字符串，用于记录票据附言；与 `remarks`（内部备注）区分。
+- `discount_amount`：可选，默认 0，允许大于 `amount`（表示折扣大于实付）；必须 ≥ 0。
+- `settlement_amount = amount + discount_amount`，所有余额、对账及汇总均基于结算金额。
+- `amount` 必须大于 0。返回 201 + 创建的记录，响应中会包含 `discount_amount` 与 `settlement_amount`。
 
 ### 4.2 审批逻辑
 
@@ -187,12 +196,22 @@
 ```json
 {
   "customer": 6,
+  "bank_account": 3,
   "receipt_date": "2025-11-30",
   "amount": "3200.00",
-  "remarks": ""
+  "discount_amount": "50.00",
+  "remarks": "",
+  "markup": "回单附言"
 }
 ```
 
+字段说明：
+
+- `bank_account`：可选，引用到账银行账户。
+- `discount_amount`：可选，默认 0，可大于 `amount`，但必须 ≥ 0。
+- `markup`：可选，记录回单附言，默认留空。
+- `settlement_amount` 为响应只读字段（`amount + discount_amount`），对账及余额只会计算结算金额。
+
 ### 5.2 审批
 
 - `approve`：状态改为 `APPROVED`，客户余额 **减少** 对应金额（冲减欠款）。若已取消则拒绝再次审批。
@@ -261,12 +280,14 @@
 |-----|------|------|
 | `/customers/<id>/statements/` | GET | 指定客户的销售 / 销退 / 收款对账单 |
 | `/suppliers/<id>/statements/` | GET | 指定供应商的采购 / 采退 / 付款对账单 |
+| `/statements/record/` | GET | 通过主体与单据参数获取单条对账记录 |
 
 关键特性：
 
 - 固定按 `occurred_at -> recorded_at -> source_id` 倒序输出，不提供排序参数。
 - `positive_amount` / `negative_amount` 统一表示余额增减；`cumulative_amount`、`current_balance`、`arrears_amount` 均冗余在每条记录中，前端可直接使用。
 - 余额快照来自 `BalanceService`，每次请求只查询一次，保证与审批事务一致。
+- 单条查询接口需提供 `counterparty_type`、`counterparty_id`、`order_type`、`order_id` 四个 Query 参数，返回 schema 与列表一致，仅 `records` 中包含匹配记录。
 
 ---
 

docs/payment_receipt_workflow.md

@@ -13,7 +13,12 @@
 | 对方主体 | `supplier` (供应商 ID) | `customer` (客户 ID) |
 | 日期 | `payment_date` | `receipt_date` |
 | 金额 | `amount`，必须 > 0 | `amount`，必须 > 0 |
-| 其他 | `remarks`（可选） | `remarks`（可选） |
+| 银行账户 | `bank_account`（可选，引用 `BankAccount`） | `bank_account`（可选） |
+| 附言 | `markup`（可选，记录票据附言） | `markup`（可选） |
+| 备注 | `remarks`（可选，内部备注） | `remarks`（可选） |
+| 折扣 | `discount_amount`（可选，≥0，可大于 `amount`） | 同左 |
+
+> 结算金额 = `amount + discount_amount`，所有余额调整与对账单统计均以结算金额为准，响应中通过只读字段 `settlement_amount` 展示。
 
 创建成功返回 `201`，包含新建单据 ID、状态（默认 `PENDING`）与提示信息。
 

docs/statements.md

@@ -22,8 +22,18 @@
 |-----|------|------|
 | `/customers/<id>/statements/` | GET | 指定客户的销售、销退、收款对账单 |
 | `/suppliers/<id>/statements/` | GET | 指定供应商的采购、采退、付款对账单 |
+| `/statements/record/` | GET | 通过主体 + 单据信息查询单条对账记录 |
 
-请求无需额外参数；分页暂不开放（按时间倒序返回全部记录）。
+请求无需额外参数；分页暂不开放（按时间倒序返回全部记录）。单条记录查询则必须提供如下 Query 参数：
+
+| 参数 | 说明 |
+|------|------|
+| `counterparty_type` | 业务主体类型，`customer` 或 `supplier` |
+| `counterparty_id` | 对应客户或供应商 ID |
+| `order_type` | 单据类型，取值与 `source_type` 一致，例如 `sales_order`、`purchase_order` 等 |
+| `order_id` | 单据 ID |
+
+> ⚠️ 由于底层仍需构建完整对账单后再筛选匹配记录，在大体量数据下应谨慎调用此接口。
 
 ---
 
@@ -74,6 +84,12 @@
 }
 ```
 
+### 3.1 单条记录查询示例
+
+`GET /api/v1/statements/record/?counterparty_type=customer&counterparty_id=6&order_type=sales_order&order_id=1024`
+
+返回结构与对账单列表保持一致，仅 `records` 数组只包含匹配的那一条记录，`summary` 会基于该数组重新计算。
+
 ### 字段说明
 
 | 字段 | 说明 |