feat: P0-5 收款财务闭环(收款登记/作废/统计/账户管理/财务页)

doc/API.md

@@ -414,3 +414,20 @@ uv run uvicorn huamenchuang.main:app --reload   # 启动，http://localhost:8000
 - `use_stock=false`：按 `stock_length`（默认 6000mm）虚拟原料，数量按需求自动估算
 - 响应/保存均新增：`result`（完整优化方案）、`preparation[]`（切割准备/领料清单：原料×根数×切割件数×余料）、`shortage[]`（按库存模式的缺料清单）
 - `GET /api/cut_solution/{contract_id}` 返回完整保存方案（含 result/preparation/shortage）
+
+### 12.19 财务模块 `/api`（v2.20 新增，P0-收款财务闭环）
+
+对齐目标站 `/manage/financial` + `contract_receipt*` 语义。
+
+**收款方式**：1现金 2银行转账 3微信 4支付宝 5其他；**状态**：1正常 0已作废（作废不参与统计/已收）。
+
+| 接口名称 | 方式 | URL 路径 | 请求参数 | 说明 |
+|---|---|---|---|---|
+| 收款账户列表 | GET | `/api/receipt-accounts` | — | |
+| 新增/编辑/删除账户 | POST/PUT/DELETE | `/api/receipt-accounts[/{id}]` | `{type,name,number?,bank?,note?,is_default?}` | is_default=1 唯一默认 |
+| **登记收款** | POST | `/api/contracts/{id}/receipts` | `{amount(>0), method, account_id?, receipt_date?, note?}` | 收款单号 `SK+YYYYMMDD+3位流水` |
+| 作废收款 | POST | `/api/receipts/{id}/void` | 路径 | 对齐 void_contract_receipt |
+| 收款流水分页 | GET | `/api/receipts` | `page,keyword,year,contract_id,status` | 联合同号/客户名 |
+| **收款统计** | GET | `/api/receipts/statistics` | `year?`（默认当年） | `{total_received, contract_total, unreceived, monthly[12]}`（对齐 statistics/_tb） |
+
+合同列表（`GET /api/contracts`）响应行新增：`received`（有效收款合计）、`unreceived`（合同额-已收）。