forked from erp-dev/erp
feat: balance api
This commit is contained in:
213
docs/business_api_reference.md
Normal file
213
docs/business_api_reference.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# 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 结构 | 受仓库模式影响：<br>• 严进/严进严出：`numbers: [int,…]` 表示条数明细<br>• 宽进宽出：`quantity` + `num_of_rolls`<br>• 严出：`consume_detail_ids: [detail_id,…]` |
|
||||
| 审批副作用 | 采购/销售审批通过后根据商户设置触发 Celery 入/出库任务；付款/收款审批通过将同步写入余额表。 |
|
||||
|
||||
错误响应统一为 `{"error": "代码", "message": "描述"}`，字段可能因场景扩展（如 `record_id`、`fields` 等）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 采购单（PurchaseOrder）
|
||||
|
||||
| API | 方法 | 描述 |
|
||||
|-----|------|------|
|
||||
| `/purchase-orders/` | GET | 分页列表。 |
|
||||
| `/purchase-orders/` | POST | 创建采购单。 |
|
||||
| `/purchase-orders/<id>/review/` | POST | 审批或作废。 |
|
||||
|
||||
### 2.1 创建请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"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` 等）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 销售单（SalesOrder）
|
||||
|
||||
| API | 方法 | 描述 |
|
||||
|-----|------|------|
|
||||
| `/sales-orders/` | GET | 分页列表。 |
|
||||
| `/sales-orders/` | POST | 创建销售单。 |
|
||||
| `/sales-orders/<id>/review/` | POST | 审批或作废。 |
|
||||
|
||||
### 3.1 创建请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"customer": 6,
|
||||
"warehouse": 3,
|
||||
"order_date": "2025-11-30",
|
||||
"items": [
|
||||
{
|
||||
"product_id": 1001,
|
||||
"numbers": [20, 18],
|
||||
"price": "18.80",
|
||||
"unit": "米"
|
||||
}
|
||||
],
|
||||
"remarks": ""
|
||||
}
|
||||
```
|
||||
|
||||
仓库为严出（`RESTRICT_IN_OUT`）时必须改用：
|
||||
|
||||
```json
|
||||
{
|
||||
"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`）则拒绝。
|
||||
|
||||
---
|
||||
|
||||
## 4. 付款单（PaymentOrder）
|
||||
|
||||
| API | 方法 | 描述 |
|
||||
|-----|------|------|
|
||||
| `/payment-orders/` | GET | 分页列表。 |
|
||||
| `/payment-orders/` | POST | 创建付款单。 |
|
||||
| `/payment-orders/<id>/review/` | POST | 审批或作废。 |
|
||||
|
||||
### 4.1 创建请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"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 创建
|
||||
|
||||
```json
|
||||
{
|
||||
"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 | 查询指定客户应收余额。 |
|
||||
|
||||
响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"customer": 6,
|
||||
"customer_name": "杭州零售商",
|
||||
"balance": "3200.00"
|
||||
}
|
||||
```
|
||||
|
||||
- 正数表示客户仍欠款；负数表示已收超额。
|
||||
- 若客户无记录返回 `"0"`。
|
||||
|
||||
### 6.2 供应商余额
|
||||
|
||||
目前仅内部使用（审批写入），如需对外查询可在此基础上新增 `/suppliers/<id>/balance/`，逻辑与客户一致：采购单审批增加余额、付款单审批减少余额。
|
||||
|
||||
---
|
||||
|
||||
## 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`：资金类单据与余额表写入逻辑。
|
||||
|
||||
本汇总会随着业务扩展同步更新，如需新增接口请补充到此文件以保持前端“单文档”体验。***
|
||||
|
||||
Reference in New Issue
Block a user