feat: payment order and receipt order

api_v1/business/README.md

@@ -104,7 +104,41 @@
 
 ---
 
-## 4. 错误示例
+## 4. 付款单（PaymentOrder）
+
+### 4.1 列表
+- **GET** `/api/v1/payment-orders/`
+- 返回字段：`supplier_name`、`payment_date`、`amount`、`status` 等。
+
+### 4.2 创建
+- **POST** `/api/v1/payment-orders/`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `supplier` | int | 供应商 ID |
+| `payment_date` | str (`YYYY-MM-DD`) | 付款日期 |
+| `amount` | decimal | 付款金额（必须 > 0） |
+| `remarks` | str | 可选 |
+
+### 4.3 审批 / 作废
+- **POST** `/api/v1/payment-orders/<id>/review/`
+- `{"action": "approve"}` 或 `{"action": "cancel"}`
+
+---
+
+## 5. 收款单（ReceiptOrder）
+
+接口与付款单类似，只是主体为 `customer`：
+
+- **GET** `/api/v1/receipt-orders/`
+- **POST** `/api/v1/receipt-orders/`：需要 `customer`、`receipt_date`、`amount`
+- **POST** `/api/v1/receipt-orders/<id>/review/`
+
+审批通过表示“确认收款”，作废则恢复为初始状态。
+
+---
+
+## 6. 错误示例
 
 | 场景 | HTTP | 返回体 |
 |------|------|--------|

api_v1/business/payment/views.py

@@ -0,0 +1,133 @@
+from rest_framework import status, views, serializers, pagination
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+
+from basic_info import models as basic_models
+from business import services as business_services
+from business import models as business_models
+from api_v1.views.stock_change_views.mixins import StockChangeViewMixin
+
+
+class PaymentOrderSerializer(serializers.ModelSerializer):
+    supplier_name = serializers.CharField(source='supplier.name', read_only=True)
+    operator_name = serializers.CharField(source='operator.name', read_only=True)
+
+    class Meta:
+        model = business_models.PaymentOrder
+        fields = [
+            'id', 'supplier', 'supplier_name', 'payment_date',
+            'amount', 'operator', 'operator_name', 'status',
+            'remarks', 'created_at', 'updated_at',
+        ]
+        read_only_fields = ['id', 'supplier_name', 'operator_name', 'status', 'created_at', 'updated_at']
+
+
+class PaymentOrderPagination(pagination.LimitOffsetPagination):
+    default_limit = 20
+    max_limit = 100
+
+
+class PaymentOrderView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    pagination_class = PaymentOrderPagination
+
+    def get(self, request):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+        merchant = request.user.employee.merchant
+        queryset = business_models.PaymentOrder.objects.filter(merchant=merchant).select_related(
+            'supplier', 'operator'
+        ).order_by('-created_at')
+        paginator = self.pagination_class()
+        page = paginator.paginate_queryset(queryset, request, view=self)
+        serializer = PaymentOrderSerializer(page, many=True)
+        return paginator.get_paginated_response(serializer.data)
+
+    def post(self, request):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+        merchant = request.user.employee.merchant
+        data = request.data or {}
+        supplier_id = data.get('supplier')
+        payment_date = data.get('payment_date')
+        amount = data.get('amount')
+        remarks = data.get('remarks', '')
+
+        if not supplier_id:
+            return Response({'error': '缺少供应商 ID'}, status=status.HTTP_400_BAD_REQUEST)
+        if not payment_date:
+            return Response({'error': '缺少 payment_date'}, status=status.HTTP_400_BAD_REQUEST)
+        if amount is None:
+            return Response({'error': '缺少 amount'}, status=status.HTTP_400_BAD_REQUEST)
+
+        try:
+            supplier = basic_models.Supplier.objects.get(id=supplier_id, merchant=merchant)
+        except basic_models.Supplier.DoesNotExist:
+            return Response({'error': f'供应商 {supplier_id} 不存在'}, status=status.HTTP_400_BAD_REQUEST)
+
+        operator = request.user.employee
+
+        try:
+            payment_order = business_services.create_payment_order(
+                merchant=merchant,
+                supplier=supplier,
+                payment_date=payment_date,
+                amount=amount,
+                operator=operator,
+                remarks=remarks,
+            )
+        except ValueError as exc:
+            return Response({'error': str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+        return Response(
+            {
+                'id': payment_order.id,
+                'status': payment_order.status,
+                'message': '付款单创建成功，等待审批',
+            },
+            status=status.HTTP_201_CREATED,
+        )
+
+
+class PaymentOrderReviewSerializer(serializers.Serializer):
+    action = serializers.ChoiceField(choices=[('approve', '审批通过'), ('cancel', '作废')])
+
+
+class PaymentOrderReviewView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    ACTION_STATUS_MAP = {
+        'approve': business_models.PaymentOrderStatusEnum.APPROVED,
+        'cancel': business_models.PaymentOrderStatusEnum.CANCELLED,
+    }
+
+    def post(self, request, pk: int):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+
+        merchant = request.user.employee.merchant
+        try:
+            payment_order = business_models.PaymentOrder.objects.select_related(
+                'supplier', 'operator'
+            ).get(id=pk, merchant=merchant)
+        except business_models.PaymentOrder.DoesNotExist:
+            return self.not_found_response('付款单不存在')
+
+        serializer = PaymentOrderReviewSerializer(data=request.data or {})
+        serializer.is_valid(raise_exception=True)
+        action = serializer.validated_data['action']
+        target_status = self.ACTION_STATUS_MAP[action]
+
+        try:
+            business_services.review_payment_order(
+                payment_order=payment_order,
+                target_status=target_status,
+                reviewed_by=request.user,
+            )
+        except ValueError as exc:
+            return Response({'error': str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+        refreshed = business_models.PaymentOrder.objects.select_related(
+            'supplier', 'operator'
+        ).get(id=payment_order.id)
+        return Response(PaymentOrderSerializer(refreshed).data, status=status.HTTP_200_OK)
+

api_v1/business/receipt/views.py

@@ -0,0 +1,133 @@
+from rest_framework import status, views, serializers, pagination
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+
+from basic_info import models as basic_models
+from business import services as business_services
+from business import models as business_models
+from api_v1.views.stock_change_views.mixins import StockChangeViewMixin
+
+
+class ReceiptOrderSerializer(serializers.ModelSerializer):
+    customer_name = serializers.CharField(source='customer.name', read_only=True)
+    operator_name = serializers.CharField(source='operator.name', read_only=True)
+
+    class Meta:
+        model = business_models.ReceiptOrder
+        fields = [
+            'id', 'customer', 'customer_name', 'receipt_date',
+            'amount', 'operator', 'operator_name', 'status',
+            'remarks', 'created_at', 'updated_at',
+        ]
+        read_only_fields = ['id', 'customer_name', 'operator_name', 'status', 'created_at', 'updated_at']
+
+
+class ReceiptOrderPagination(pagination.LimitOffsetPagination):
+    default_limit = 20
+    max_limit = 100
+
+
+class ReceiptOrderView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    pagination_class = ReceiptOrderPagination
+
+    def get(self, request):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+        merchant = request.user.employee.merchant
+        queryset = business_models.ReceiptOrder.objects.filter(merchant=merchant).select_related(
+            'customer', 'operator'
+        ).order_by('-created_at')
+        paginator = self.pagination_class()
+        page = paginator.paginate_queryset(queryset, request, view=self)
+        serializer = ReceiptOrderSerializer(page, many=True)
+        return paginator.get_paginated_response(serializer.data)
+
+    def post(self, request):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+        merchant = request.user.employee.merchant
+        data = request.data or {}
+        customer_id = data.get('customer')
+        receipt_date = data.get('receipt_date')
+        amount = data.get('amount')
+        remarks = data.get('remarks', '')
+
+        if not customer_id:
+            return Response({'error': '缺少客户 ID'}, status=status.HTTP_400_BAD_REQUEST)
+        if not receipt_date:
+            return Response({'error': '缺少 receipt_date'}, status=status.HTTP_400_BAD_REQUEST)
+        if amount is None:
+            return Response({'error': '缺少 amount'}, status=status.HTTP_400_BAD_REQUEST)
+
+        try:
+            customer = basic_models.Customer.objects.get(id=customer_id, merchant=merchant)
+        except basic_models.Customer.DoesNotExist:
+            return Response({'error': f'客户 {customer_id} 不存在'}, status=status.HTTP_400_BAD_REQUEST)
+
+        operator = request.user.employee
+
+        try:
+            receipt_order = business_services.create_receipt_order(
+                merchant=merchant,
+                customer=customer,
+                receipt_date=receipt_date,
+                amount=amount,
+                operator=operator,
+                remarks=remarks,
+            )
+        except ValueError as exc:
+            return Response({'error': str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+        return Response(
+            {
+                'id': receipt_order.id,
+                'status': receipt_order.status,
+                'message': '收款单创建成功，等待审批',
+            },
+            status=status.HTTP_201_CREATED,
+        )
+
+
+class ReceiptOrderReviewSerializer(serializers.Serializer):
+    action = serializers.ChoiceField(choices=[('approve', '审批通过'), ('cancel', '作废')])
+
+
+class ReceiptOrderReviewView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    ACTION_STATUS_MAP = {
+        'approve': business_models.ReceiptOrderStatusEnum.APPROVED,
+        'cancel': business_models.ReceiptOrderStatusEnum.CANCELLED,
+    }
+
+    def post(self, request, pk: int):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+
+        merchant = request.user.employee.merchant
+        try:
+            receipt_order = business_models.ReceiptOrder.objects.select_related(
+                'customer', 'operator'
+            ).get(id=pk, merchant=merchant)
+        except business_models.ReceiptOrder.DoesNotExist:
+            return self.not_found_response('收款单不存在')
+
+        serializer = ReceiptOrderReviewSerializer(data=request.data or {})
+        serializer.is_valid(raise_exception=True)
+        action = serializer.validated_data['action']
+        target_status = self.ACTION_STATUS_MAP[action]
+
+        try:
+            business_services.review_receipt_order(
+                receipt_order=receipt_order,
+                target_status=target_status,
+                reviewed_by=request.user,
+            )
+        except ValueError as exc:
+            return Response({'error': str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+        refreshed = business_models.ReceiptOrder.objects.select_related(
+            'customer', 'operator'
+        ).get(id=receipt_order.id)
+        return Response(ReceiptOrderSerializer(refreshed).data, status=status.HTTP_200_OK)
+

api_v1/tests.py

@@ -11,6 +11,7 @@ from rest_framework import status
 from basic_info.models import (
     Customer,
     Employee,
+    EmployeeStatusEnum,
     Merchant,
     MerchantTypeEnum,
     Product,
@@ -450,6 +451,124 @@ class SalesOrderAPITestCase(TestCase):
         self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
         order = business_models.SalesOrder.objects.get(id=order_id)
         self.assertEqual(order.status, business_models.SalesOrderStatusEnum.PENDING)
+
+
+class PaymentOrderAPITestCase(TestCase):
+    def setUp(self):
+        self.merchant = Merchant.objects.create(name='付款商户', type=MerchantTypeEnum.FACTORY)
+        self.supplier = Supplier.objects.create(merchant=self.merchant, name='付款供应商')
+        self.user = User.objects.create_user(username='pay_user', password='pass123')
+        self.employee = Employee.objects.create(
+            merchant=self.merchant,
+            sys_user=self.user,
+            name='财务',
+            status=EmployeeStatusEnum.ACTIVE,
+        )
+        self.client = APIClient()
+        self.client.force_authenticate(user=self.user)
+        self.payload = {
+            'supplier': self.supplier.id,
+            'payment_date': '2025-11-26',
+            'amount': '120.5',
+            'remarks': '付款备注',
+        }
+
+    def test_create_payment_order_success(self):
+        response = self.client.post('/api/v1/payment-orders/', self.payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertIn('id', response.data)
+
+    def test_create_payment_order_invalid_supplier(self):
+        payload = {**self.payload, 'supplier': 999}
+        response = self.client.post('/api/v1/payment-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_review_payment_order(self):
+        resp = self.client.post('/api/v1/payment-orders/', self.payload, format='json')
+        order_id = resp.data['id']
+        response = self.client.post(f'/api/v1/payment-orders/{order_id}/review/', {'action': 'approve'}, format='json')
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data['status'], business_models.PaymentOrderStatusEnum.APPROVED)
+        response_cancel = self.client.post(
+            f'/api/v1/payment-orders/{order_id}/review/',
+            {'action': 'cancel'},
+            format='json',
+        )
+        self.assertEqual(response_cancel.status_code, status.HTTP_200_OK)
+        self.assertEqual(response_cancel.data['status'], business_models.PaymentOrderStatusEnum.CANCELLED)
+
+    def test_payment_order_requires_amount(self):
+        payload = {**self.payload}
+        payload.pop('amount')
+        response = self.client.post('/api/v1/payment-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn('缺少 amount', response.data['error'])
+
+    def test_payment_order_amount_must_be_positive(self):
+        payload = {**self.payload, 'amount': '0'}
+        response = self.client.post('/api/v1/payment-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn('amount 必须大于 0', response.data['error'])
+
+
+class ReceiptOrderAPITestCase(TestCase):
+    def setUp(self):
+        self.merchant = Merchant.objects.create(name='收款商户', type=MerchantTypeEnum.FACTORY)
+        self.customer = Customer.objects.create(
+            merchant=self.merchant,
+            name='客户C',
+            mobile='13812345678',
+            created_by=None,
+        )
+        self.user = User.objects.create_user(username='receipt_user', password='pass123')
+        self.employee = Employee.objects.create(
+            merchant=self.merchant,
+            sys_user=self.user,
+            name='财务员',
+            status=EmployeeStatusEnum.ACTIVE,
+        )
+        self.client = APIClient()
+        self.client.force_authenticate(user=self.user)
+        self.payload = {
+            'customer': self.customer.id,
+            'receipt_date': '2025-11-26',
+            'amount': '88.00',
+            'remarks': '收款备注',
+        }
+
+    def test_create_receipt_order_success(self):
+        response = self.client.post('/api/v1/receipt-orders/', self.payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertIn('id', response.data)
+
+    def test_create_receipt_order_invalid_customer(self):
+        payload = {**self.payload, 'customer': 999}
+        response = self.client.post('/api/v1/receipt-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_review_receipt_order(self):
+        resp = self.client.post('/api/v1/receipt-orders/', self.payload, format='json')
+        order_id = resp.data['id']
+        response = self.client.post(
+            f'/api/v1/receipt-orders/{order_id}/review/',
+            {'action': 'cancel'},
+            format='json',
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data['status'], business_models.ReceiptOrderStatusEnum.CANCELLED)
+
+    def test_receipt_order_requires_amount(self):
+        payload = {**self.payload}
+        payload.pop('amount')
+        response = self.client.post('/api/v1/receipt-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn('缺少 amount', response.data['error'])
+
+    def test_receipt_order_amount_must_be_positive(self):
+        payload = {**self.payload, 'amount': '0'}
+        response = self.client.post('/api/v1/receipt-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn('amount 必须大于 0', response.data['error'])
 @override_settings(
     CELERY_TASK_ALWAYS_EAGER=True,
     CELERY_TASK_EAGER_PROPAGATES=True,

api_v1/urls.py

@@ -12,6 +12,8 @@ from .views import (
 )
 from .business.purchase import views as purchase_views
 from .business.sales import views as sales_views
+from .business.payment import views as payment_views
+from .business.receipt import views as receipt_views
 from .views.stock_change_views.snapshot import StockSnapshotListView
 from .views.printing.views import PrintingOrderViewSet, PrintingJobViewSet, PlateOrderViewSet
 from .views.upload import UploadFileViewSet
@@ -63,6 +65,10 @@ urlpatterns = [
     path('purchase-orders/<int:pk>/review/', purchase_views.PurchaseOrderReviewView.as_view(), name='purchase_order_review'),
     path('sales-orders/', sales_views.SalesOrderView.as_view(), name='sales_orders'),
     path('sales-orders/<int:pk>/review/', sales_views.SalesOrderReviewView.as_view(), name='sales_order_review'),
+    path('payment-orders/', payment_views.PaymentOrderView.as_view(), name='payment_orders'),
+    path('payment-orders/<int:pk>/review/', payment_views.PaymentOrderReviewView.as_view(), name='payment_order_review'),
+    path('receipt-orders/', receipt_views.ReceiptOrderView.as_view(), name='receipt_orders'),
+    path('receipt-orders/<int:pk>/review/', receipt_views.ReceiptOrderReviewView.as_view(), name='receipt_order_review'),
     path('health/', healthy.HealthCheckView.as_view(), name='health_check'),
     path('print-count/delta/', print_count.adjust_print_count, name='print_count_delta'),
     

business/ARCHITECTURE.md

@@ -32,17 +32,18 @@
 ### 2.3 OrderCounterpartyMixin
 对外暴露统一的 `get_counterparty()` 接口，通过 `get_counterparty_field_name()`（或 `counterparty_field_name` 属性）确定具体业务主体字段。这样采购单/销售单分别返回 `Supplier` 与 `Customer`，但调用方只需面对一个接口。
 
-### 2.4 PurchaseOrder / SalesOrder
-两类订单模型均继承上述三个 Mixin：
+### 2.4 订单类型
+当前业务对象覆盖：
 
-- 采购单：`get_direction()` 返回 `1`，`get_counterparty_field_name()` 返回 `supplier`
-- 销售单：`get_direction()` 返回 `-1`，`get_counterparty_field_name()` 返回 `customer`
-- 其余字段（`merchant/warehouse/operator/status/items`）保持一致，便于服务、序列化与统计逻辑复用
+- **PurchaseOrder**（采购单）：`direction=1`，`counterparty=supplier`，含库存明细。
+- **SalesOrder**（销售单）：`direction=-1`，`counterparty=customer`，含库存明细；严进严出模式需记录 `consume_detail_ids`。
+- **PaymentOrder**（付款单）：`direction=-1`，`counterparty=supplier`，仅金额字段，不触发库存。
+- **ReceiptOrder**（收款单）：`direction=-1`，`counterparty=customer`，仅金额字段，不触发库存。
 
-通过 mixin，两个模型天然具备：
-- 金额聚合与带方向金额计算
-- 统一的业务主体读取接口
-- 与库存/财务交互时一致的 `StockFlowService` payload
+通过 mixin，所有单据都具备：
+- 统一的金额聚合与方向计算（资金/库存可共用 `get_signed_total_amount()`）
+- 一致的业务主体接口（供应商/客户）
+- 可扩展的服务与序列化模式（有无库存由具体模型决定）
 
 ## 3. 服务层约定
 
@@ -52,10 +53,10 @@
 
 ## 4. 未来演进建议
 
-1. **新增单据**：若未来出现调拨单、退货单等，优先继承 `OrderItemsAggregationMixin + OrderDirectionMixin + OrderCounterpartyMixin`，仅通过 `get_direction()` / `get_counterparty_field_name()` 区别方向与主体，减少重复实现。
+1. **新增单据**：若未来出现调拨单、退货单或更多资金类单据，优先复用 `OrderDirectionMixin + OrderCounterpartyMixin`（如有明细再叠加 `OrderItemsAggregationMixin`），仅通过 `get_direction()` / `get_counterparty_field_name()` 区别方向与主体，减少重复实现。
 2. **审批/状态机**：采购与销售如需共享状态流转，可提炼状态机或 service 层 mixin，而无需在模型层合并。
 3. **统计与报表**：财务/库存统计应依赖 `get_signed_total_amount()` / `get_direction()`，确保采购/销售、退货/正向都能通过统一接口处理。
 4. **文档同步**：新增单据或服务时必须更新本文件，描述新增模型如何复用 mixin、如何影响下游模块，保持设计透明。
 
-以上约定的目标是：**保持采购单与未来销售单等业务对象的独立性，同时通过 mixin/服务层抽象复用绝大多数公共逻辑**。如需变更此架构（例如重新合并模型或修改核心 mixin 行为），请在评估后更新本文件，明确变化原因与迁移方案。 
+以上约定的目标是：**保持各类业务单据的独立性，同时通过 mixin/服务层抽象复用绝大多数公共逻辑**。如需变更此架构，请在评估后更新本文件，说明原因与迁移方案。
 

business/migrations/0011_paymentorder_receiptorder.py

@@ -0,0 +1,56 @@
+# Generated by Django 5.2.7 on 2025-11-30 13:20
+
+import business.models
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('basic_info', '0016_merchantsetting_type'),
+        ('business', '0010_salesorder_salesorderitem'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='PaymentOrder',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')),
+                ('updated_at', models.DateTimeField(auto_now=True, verbose_name='更新时间')),
+                ('id', models.BigAutoField(primary_key=True, serialize=False)),
+                ('payment_date', models.DateField(verbose_name='付款日期')),
+                ('amount', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='金额')),
+                ('status', models.IntegerField(choices=[(1, '审批中'), (2, '审批通过'), (3, '作废')], default=1, verbose_name='状态')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('merchant', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='payment_orders', to='basic_info.merchant', verbose_name='所属商户')),
+                ('operator', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='payment_orders', to='basic_info.employee', verbose_name='经办人')),
+                ('supplier', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='payment_orders', to='basic_info.supplier', verbose_name='供应商')),
+            ],
+            options={
+                'verbose_name': '付款单',
+                'verbose_name_plural': '付款单',
+            },
+            bases=(business.models.OrderDirectionMixin, business.models.OrderCounterpartyMixin, models.Model),
+        ),
+        migrations.CreateModel(
+            name='ReceiptOrder',
+            fields=[
+                ('created_at', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')),
+                ('updated_at', models.DateTimeField(auto_now=True, verbose_name='更新时间')),
+                ('id', models.BigAutoField(primary_key=True, serialize=False)),
+                ('receipt_date', models.DateField(verbose_name='收款日期')),
+                ('amount', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='金额')),
+                ('status', models.IntegerField(choices=[(1, '审批中'), (2, '审批通过'), (3, '作废')], default=1, verbose_name='状态')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('customer', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='receipt_orders', to='basic_info.customer', verbose_name='客户')),
+                ('merchant', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='receipt_orders', to='basic_info.merchant', verbose_name='所属商户')),
+                ('operator', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='receipt_orders', to='basic_info.employee', verbose_name='经办人')),
+            ],
+            options={
+                'verbose_name': '收款单',
+                'verbose_name_plural': '收款单',
+            },
+            bases=(business.models.OrderDirectionMixin, business.models.OrderCounterpartyMixin, models.Model),
+        ),
+    ]

business/models.py

@@ -316,3 +316,107 @@ class SalesOrderItem(ModelBase):
 
     def total_amount(self):
         return round(self.price * self.real_quantity(), 2)
+
+
+class PaymentOrderStatusEnum(models.IntegerChoices):
+    PENDING = 1, '审批中'
+    APPROVED = 2, '审批通过'
+    CANCELLED = 3, '作废'
+
+
+class PaymentOrder(OrderDirectionMixin, OrderCounterpartyMixin, ModelBase):
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.ForeignKey(
+        basic_info_models.Merchant,
+        on_delete=models.PROTECT,
+        related_name='payment_orders',
+        verbose_name='所属商户',
+    )
+    supplier = models.ForeignKey(
+        basic_info_models.Supplier,
+        on_delete=models.PROTECT,
+        related_name='payment_orders',
+        verbose_name='供应商',
+    )
+    payment_date = models.DateField(verbose_name='付款日期')
+    amount = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='金额')
+    operator = models.ForeignKey(
+        basic_info_models.Employee,
+        on_delete=models.PROTECT,
+        related_name='payment_orders',
+        verbose_name='经办人',
+    )
+    status = models.IntegerField(
+        choices=PaymentOrderStatusEnum.choices,
+        default=PaymentOrderStatusEnum.PENDING,
+        verbose_name='状态',
+    )
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '付款单'
+        verbose_name_plural = '付款单'
+
+    def __str__(self):
+        return f'付款单 {self.id} - {self.supplier.name}'
+
+    def get_total_amount(self) -> Decimal:
+        return self.amount
+
+    def get_direction(self) -> int:
+        return -1
+
+    def get_counterparty_field_name(self) -> str:
+        return 'supplier'
+
+
+class ReceiptOrderStatusEnum(models.IntegerChoices):
+    PENDING = 1, '审批中'
+    APPROVED = 2, '审批通过'
+    CANCELLED = 3, '作废'
+
+
+class ReceiptOrder(OrderDirectionMixin, OrderCounterpartyMixin, ModelBase):
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.ForeignKey(
+        basic_info_models.Merchant,
+        on_delete=models.PROTECT,
+        related_name='receipt_orders',
+        verbose_name='所属商户',
+    )
+    customer = models.ForeignKey(
+        basic_info_models.Customer,
+        on_delete=models.PROTECT,
+        related_name='receipt_orders',
+        verbose_name='客户',
+    )
+    receipt_date = models.DateField(verbose_name='收款日期')
+    amount = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='金额')
+    operator = models.ForeignKey(
+        basic_info_models.Employee,
+        on_delete=models.PROTECT,
+        related_name='receipt_orders',
+        verbose_name='经办人',
+    )
+    status = models.IntegerField(
+        choices=ReceiptOrderStatusEnum.choices,
+        default=ReceiptOrderStatusEnum.PENDING,
+        verbose_name='状态',
+    )
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '收款单'
+        verbose_name_plural = '收款单'
+
+    def __str__(self):
+        return f'收款单 {self.id} - {self.customer.name}'
+
+    def get_total_amount(self) -> Decimal:
+        return self.amount
+
+    def get_direction(self) -> int:
+        return -1
+
+    def get_counterparty_field_name(self) -> str:
+        return 'customer'

business/services.py

@@ -161,6 +161,62 @@ def create_sales_order(
     return sales_order
 
 
+def create_payment_order(
+    *,
+    merchant: basic_info_models.Merchant,
+    supplier: basic_info_models.Supplier,
+    payment_date,
+    amount,
+    operator: basic_info_models.Employee,
+    remarks: str | None = '',
+) -> models.PaymentOrder:
+    """
+    创建付款单（资金流出）。
+    """
+    normalized_date = _normalize_order_date(payment_date)
+    normalized_amount = _ensure_positive_amount(amount, 'amount')
+
+    with transaction.atomic():
+        payment_order = models.PaymentOrder.objects.create(
+            merchant=merchant,
+            supplier=supplier,
+            payment_date=normalized_date,
+            amount=normalized_amount,
+            operator=operator,
+            remarks=remarks,
+        )
+    payment_order.refresh_from_db()
+    return payment_order
+
+
+def create_receipt_order(
+    *,
+    merchant: basic_info_models.Merchant,
+    customer: basic_info_models.Customer,
+    receipt_date,
+    amount,
+    operator: basic_info_models.Employee,
+    remarks: str | None = '',
+) -> models.ReceiptOrder:
+    """
+    创建收款单（资金流入）。
+    """
+    normalized_date = _normalize_order_date(receipt_date)
+    normalized_amount = _ensure_positive_amount(amount, 'amount')
+
+    with transaction.atomic():
+        receipt_order = models.ReceiptOrder.objects.create(
+            merchant=merchant,
+            customer=customer,
+            receipt_date=normalized_date,
+            amount=normalized_amount,
+            operator=operator,
+            remarks=remarks,
+        )
+    receipt_order.refresh_from_db()
+    return receipt_order
+
+
 def review_purchase_order(
     *,
     purchase_order: models.PurchaseOrder | None = None,
@@ -222,6 +278,58 @@ def review_sales_order(
     return _cancel_sales_order(order)
 
 
+def review_payment_order(
+    *,
+    payment_order: models.PaymentOrder | None = None,
+    payment_order_id: int | None = None,
+    target_status: models.PaymentOrderStatusEnum,
+    reviewed_by=None,
+) -> models.PaymentOrder:
+    order = _resolve_payment_order_instance(payment_order, payment_order_id)
+
+    if target_status not in {
+        models.PaymentOrderStatusEnum.APPROVED,
+        models.PaymentOrderStatusEnum.CANCELLED,
+    }:
+        raise ValueError('target_status 只能是 APPROVED 或 CANCELLED')
+
+    if order.status == target_status:
+        return order
+
+    with transaction.atomic():
+        order.status = target_status
+        order.save(update_fields=['status', 'updated_at'])
+
+    order.refresh_from_db(fields=['status', 'updated_at'])
+    return order
+
+
+def review_receipt_order(
+    *,
+    receipt_order: models.ReceiptOrder | None = None,
+    receipt_order_id: int | None = None,
+    target_status: models.ReceiptOrderStatusEnum,
+    reviewed_by=None,
+) -> models.ReceiptOrder:
+    order = _resolve_receipt_order_instance(receipt_order, receipt_order_id)
+
+    if target_status not in {
+        models.ReceiptOrderStatusEnum.APPROVED,
+        models.ReceiptOrderStatusEnum.CANCELLED,
+    }:
+        raise ValueError('target_status 只能是 APPROVED 或 CANCELLED')
+
+    if order.status == target_status:
+        return order
+
+    with transaction.atomic():
+        order.status = target_status
+        order.save(update_fields=['status', 'updated_at'])
+
+    order.refresh_from_db(fields=['status', 'updated_at'])
+    return order
+
+
 def _normalize_order_items(
     *,
     merchant: basic_info_models.Merchant,
@@ -596,6 +704,28 @@ def _resolve_sales_order_instance(
     )
 
 
+def _resolve_payment_order_instance(
+    payment_order: models.PaymentOrder | None,
+    payment_order_id: int | None,
+) -> models.PaymentOrder:
+    if payment_order is None and payment_order_id is None:
+        raise ValueError('必须提供 payment_order 或 payment_order_id')
+    if payment_order is not None:
+        payment_order_id = payment_order.id
+    return models.PaymentOrder.objects.select_related('merchant', 'supplier').get(id=payment_order_id)
+
+
+def _resolve_receipt_order_instance(
+    receipt_order: models.ReceiptOrder | None,
+    receipt_order_id: int | None,
+) -> models.ReceiptOrder:
+    if receipt_order is None and receipt_order_id is None:
+        raise ValueError('必须提供 receipt_order 或 receipt_order_id')
+    if receipt_order is not None:
+        receipt_order_id = receipt_order.id
+    return models.ReceiptOrder.objects.select_related('merchant', 'customer').get(id=receipt_order_id)
+
+
 def _to_decimal(value, field_name: str) -> Decimal:
     try:
         return Decimal(str(value))
@@ -603,6 +733,13 @@ def _to_decimal(value, field_name: str) -> Decimal:
         raise ValueError(f'{field_name} 必须是合法数值') from exc
 
 
+def _ensure_positive_amount(value, field_name: str) -> Decimal:
+    amount = _to_decimal(value, field_name)
+    if amount <= 0:
+        raise ValueError(f'{field_name} 必须大于 0')
+    return amount
+
+
 def _to_positive_int(value, field_name: str) -> int:
     if value is None:
         raise ValueError(f'{field_name} 不能为空')

business/tests.py

@@ -374,6 +374,105 @@ class SalesOrderServiceTestCase(TestCase):
         item = sales_order.items.first()
         self.assertEqual(item.consume_detail_ids, '1,2')
 
+    def test_sales_order_outgoing_missing_consume_ids_raises(self):
+        payload = [{
+            'product_id': self.product.id,
+            'quantity': 30,
+            'price': '25',
+            'unit': '米',
+        }]
+        with self.assertRaises(ValueError):
+            services.create_sales_order(
+                merchant=self.merchant,
+                customer=self.customer,
+                order_date=timezone.now().date(),
+                warehouse=self.warehouse_strict_out,
+                operator=self.operator,
+                items=payload,
+                created_by=self.user,
+            )
+
+
+class PaymentReceiptServiceTestCase(TestCase):
+    def setUp(self):
+        (
+            self.merchant,
+            self.supplier,
+            self.warehouse_strict,
+            self.warehouse_relaxed,
+            self.product,
+            self.operator,
+        ) = create_basic_fixtures()
+        self.customer = basic_models.Customer.objects.create(
+            merchant=self.merchant,
+            name='客户B',
+            mobile='13888888888',
+            created_by=None,
+        )
+
+    def test_create_payment_order_and_approve(self):
+        order = services.create_payment_order(
+            merchant=self.merchant,
+            supplier=self.supplier,
+            payment_date=timezone.now().date(),
+            amount='120.50',
+            operator=self.operator,
+            remarks='付款测试',
+        )
+        self.assertEqual(order.status, business_models.PaymentOrderStatusEnum.PENDING)
+        reviewed = services.review_payment_order(
+            payment_order=order,
+            target_status=business_models.PaymentOrderStatusEnum.APPROVED,
+            reviewed_by=self.operator,
+        )
+        self.assertEqual(reviewed.status, business_models.PaymentOrderStatusEnum.APPROVED)
+
+    def test_create_receipt_order_and_cancel(self):
+        order = services.create_receipt_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            receipt_date=timezone.now().date(),
+            amount='80.00',
+            operator=self.operator,
+            remarks='收款测试',
+        )
+        cancelled = services.review_receipt_order(
+            receipt_order=order,
+            target_status=business_models.ReceiptOrderStatusEnum.CANCELLED,
+            reviewed_by=self.operator,
+        )
+        self.assertEqual(cancelled.status, business_models.ReceiptOrderStatusEnum.CANCELLED)
+
+    def test_payment_amount_must_be_positive(self):
+        with self.assertRaises(ValueError):
+            services.create_payment_order(
+                merchant=self.merchant,
+                supplier=self.supplier,
+                payment_date=timezone.now().date(),
+                amount='-1',
+                operator=self.operator,
+            )
+
+    def test_receipt_approval_is_idempotent(self):
+        order = services.create_receipt_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            receipt_date=timezone.now().date(),
+            amount='10',
+            operator=self.operator,
+        )
+        services.review_receipt_order(
+            receipt_order=order,
+            target_status=business_models.ReceiptOrderStatusEnum.APPROVED,
+            reviewed_by=self.operator,
+        )
+        reviewed_again = services.review_receipt_order(
+            receipt_order=order,
+            target_status=business_models.ReceiptOrderStatusEnum.APPROVED,
+            reviewed_by=self.operator,
+        )
+        self.assertEqual(reviewed_again.status, business_models.ReceiptOrderStatusEnum.APPROVED)
+
 
 class PurchaseOrderStockServiceTestCase(TestCase):
     def setUp(self):
@@ -463,6 +562,36 @@ class SalesOrderStockServiceTestCase(TestCase):
         self.assertEqual(payload['sales_order_id'], self.sales_order.id)
         self.assertEqual(payload['stock_change_record_id'], 654)
 
+    def test_service_calls_stock_out_strict_mode(self):
+        strict_order = business_models.SalesOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            sales_date=timezone.now().date(),
+            operator=self.operator,
+            warehouse=self.warehouse_strict_out,
+        )
+        consume_items = [{'product_id': self.product.id, 'consume_detail_ids': [11, 12], 'quantity': 50}]
+        with patch('business.services.StockFlowService') as mock_flow_cls:
+            mock_instance = mock_flow_cls.return_value
+            mock_instance.stock_out.return_value = (MagicMock(id=987), [], 2)
+
+            payload = services.create_sales_order_stock_entries_sync(
+                sales_order_id=strict_order.id,
+                warehouse_id=self.warehouse_strict_out.id,
+                items=consume_items,
+                created_by_id=self.user.id,
+            )
+
+        mock_flow_cls.assert_called_once_with(merchant=self.merchant, created_by=self.user)
+        mock_instance.stock_out.assert_called_once_with(
+            warehouse_id=self.warehouse_strict_out.id,
+            source_type=stock_models.StockChangeSourceEnum.SALES,
+            source_id=strict_order.id,
+            items=[{'product_id': self.product.id, 'consume_detail_ids': [11, 12], 'quantity': 50}],
+        )
+        self.assertEqual(payload['sales_order_id'], strict_order.id)
+        self.assertEqual(payload['stock_change_record_id'], 987)
+
 
 @override_settings(
     CELERY_TASK_ALWAYS_EAGER=True,

docs/payment_receipt_workflow.md

@@ -0,0 +1,36 @@
+# 付款单 / 收款单流程说明
+
+## 1. 概述
+- `PaymentOrder`：针对供应商的资金支出单据，审批通过后代表“确认付款”。
+- `ReceiptOrder`：针对客户的资金收入单据，审批通过后代表“确认收款”。
+- 两者均位于 `business` 模块，API 路径分别为 `/api/v1/payment-orders/`、`/api/v1/receipt-orders/`。
+- 与采购/销售相比，不涉及产品与库存，仅维护资金方向、对方主体、金额与状态。
+
+## 2. 创建流程
+| 字段 | 付款单 | 收款单 |
+|------|--------|--------|
+| 对方主体 | `supplier` (供应商 ID) | `customer` (客户 ID) |
+| 日期 | `payment_date` | `receipt_date` |
+| 金额 | `amount`，必须 > 0 | `amount`，必须 > 0 |
+| 其他 | `remarks`（可选） | `remarks`（可选） |
+
+创建成功返回 `201`，包含新建单据 ID、状态（默认 `PENDING`）与提示信息。
+
+## 3. 审批 / 作废
+- 接口：`POST /api/v1/<payment|receipt>-orders/<id>/review/`
+- 请求体：`{"action": "approve"}` 或 `{"action": "cancel"}`
+- 审批通过：状态变为 `APPROVED`，后续可用于应付/应收对账。
+- 作废：状态变为 `CANCELLED`；若已是目标状态则返回原状态（幂等）。
+
+## 4. 常见异常
+| 场景 | 响应 |
+|------|------|
+| 缺少主体/日期/金额 | `400 + {"error": "缺少 ... "}` |
+| 金额 ≤ 0 | `400 + {"error": "amount 必须大于 0"}` |
+| 目标单据不存在或非当前商户 | `404` |
+| 无权限（用户非员工） | `403` |
+
+## 5. 与采购/销售单的关系
+- 继承相同的方向抽象（`get_direction()`），可与采购/销售的金额统计组合成统一的应收/应付报表。
+- 不触发库存任务，也没有 `items`、仓库等字段；扩展字段（如付款方式、附件）可在此基础上继续添加。
+