feat: purchase_order approve and calcel

docs/business_purchase.md

@@ -1,10 +1,10 @@
 # Business 模块采购单 API
 
-## 创建采购单并触发入库
+## 创建采购单（默认待审批）
 
 - **URL**: `POST /api/v1/purchase-orders/`
 - **权限**: 需要登录且具备员工身份
-- **描述**: 创建业务模块的 `PurchaseOrder`，并异步触发库存入库任务（通过 `stock.services.StockFlowService.stock_in` 实现）。
+- **描述**: 创建业务模块的 `PurchaseOrder`，默认状态为 `PENDING`（审批中）。此时不会立即生成入库记录，需在审批通过后才会触发库存入库任务。
 
 ### 请求体
 
@@ -53,11 +53,12 @@
 ```json
 {
   "id": 35,
-  "message": "采购单创建成功，入库任务已排队"
+  "status": 1,
+  "message": "采购单创建成功，等待审批"
 }
 ```
 
-创建成功即刻返回，实际入库明细由后台 Celery 任务生成，可在日志或 `stock_change` 记录中查看。
+创建成功即刻返回，状态为 `审批中`。只有在审批通过后才会调用库存入库任务。
 
 ### 错误示例
 
@@ -68,15 +69,60 @@
 | 400 | `{"error": "供应商 99 不存在"}` | 供应商不属于当前商户 |
 | 403 | `{"error": "无权限访问"}` | 当前用户无员工信息 |
 
+## 审批 / 作废采购单（API & Service）
+
+- **URL**: `POST /api/v1/purchase-orders/<id>/review/`
+- **权限**: 登录 + 员工身份
+- **请求体**:
+
+```json
+{
+  "action": "approve"  // 可选: approve / cancel
+}
+```
+
+当 `action=approve` 时，会调用 `business.services.review_purchase_order` 将采购单状态更新为 `APPROVED`，并在商户设置 `auto_create_stock_change_tasks=True` 时自动触发 `create_purchase_order_stock_entries` Celery 任务（根据采购单明细重建 `StockFlowService.stock_in` 所需 payload）。
+
+当 `action=cancel` 时，会尝试将采购单状态改为 `CANCELLED`。如果该采购单已经生成过出入库记录（`source_type=PURCHASE`、`source_id=采购单ID`），接口会返回 `400`，提示“采购单已生成出入库记录，无法作废”。
+
+### 响应示例
+
+```json
+{
+  "id": 12,
+  "status": 2,
+  "supplier_name": "供应商A",
+  "warehouse_name": "严进仓",
+  "total_amount": "1500.00",
+  "diff_quantity": "0.00",
+  "total_quantity": "120.00",
+  "items": [
+    {
+      "id": 33,
+      "product": 10,
+      "quantity": "120.00",
+      "unit": "米",
+      "spec": "50D",
+      "num_of_rolls": 3
+    }
+  ]
+}
+```
+
+### 错误示例
+
+| 状态码 | 示例 | 说明 |
+|--------|------|------|
+| 400 | `{"action": ["This field is required."]}` | 缺少 `action` |
+| 400 | `{"error": "采购单已生成出入库记录，无法作废"}` | 尝试作废但已生成出入库单 |
+| 404 | `{"error": "采购单不存在"}` | ID 不在当前商户下 |
+
 ### 关联任务（business/tasks.py）
 
-`create_purchase_order_stock_entries` 任务会接收 `purchase_order_id`、`warehouse_id`、已转换好的 `items` 信息，并通过 `StockFlowService.stock_in` 创建入库记录。
-
-- 任务日志示例：`采购单 35 入库任务完成`
-- 返回 payload 包含 `stock_change_record_id`、`created_details_count`
+`create_purchase_order_stock_entries` 任务会接收 `purchase_order_id`、`warehouse_id`、已转换好的 `items` 信息，并通过 `StockFlowService.stock_in` 创建入库记录。只有当采购单审批通过且商户开启自动入库设置时才会派发该任务。
 
 ### 测试
 
-`api_v1/tests.py` 中的 `PurchaseOrderAPITestCase` 覆盖宽进/严进模式、模式不匹配和未登录场景；  
-`business/tests.py` 中的 `PurchaseOrderServiceTestCase`、`PurchaseOrderStockTaskTestCase` 验证 service 层逻辑与 Celery 任务（通过 mock `StockFlowService`）。
+- `business/tests.PurchaseOrderServiceTestCase`：覆盖创建采购单、审批触发任务、作废校验以及宽/严模式的 payload 生成逻辑。  
+- `business/tests.PurchaseOrderStockServiceTestCase` 与 `PurchaseOrderStockTaskTestCase`：继续验证 service 层生成入库单及 Celery 任务封装逻辑。