feat: sales return order and purchase return order

api_v1/tests.py

@@ -453,6 +453,242 @@ class SalesOrderAPITestCase(TestCase):
         self.assertEqual(order.status, business_models.SalesOrderStatusEnum.PENDING)
 
 
+@override_settings(
+    CELERY_TASK_ALWAYS_EAGER=True,
+    CELERY_TASK_EAGER_PROPAGATES=True,
+)
+class PurchaseReturnOrderAPITestCase(TestCase):
+    def setUp(self):
+        self.merchant = Merchant.objects.create(name='采退商户', type=MerchantTypeEnum.FACTORY)
+        self.supplier = Supplier.objects.create(merchant=self.merchant, name='供应商B')
+        self.warehouse_strict = WareHouse.objects.create(
+            merchant=self.merchant,
+            name='采退严进仓',
+            mode=WareHouseModeEnum.RESTRICT_IN,
+        )
+        self.warehouse_relaxed = WareHouse.objects.create(
+            merchant=self.merchant,
+            name='采退宽进仓',
+            mode=WareHouseModeEnum.UNRESTRICTED,
+        )
+        self.warehouse_strict_out = WareHouse.objects.create(
+            merchant=self.merchant,
+            name='采退严出仓',
+            mode=WareHouseModeEnum.RESTRICT_IN_OUT,
+        )
+        category = ProductCategory.objects.create(
+            merchant=self.merchant,
+            name='采退品类',
+            product_prefix='RET',
+        )
+        self.product = Product.objects.create(
+            merchant=self.merchant,
+            category=category,
+            name='采退产品',
+            human_id='RET-001',
+            unit=ProductUnitEnum.METER,
+        )
+        self.user = User.objects.create_user(username='return_user', password='pass123')
+        self.employee = Employee.objects.create(
+            merchant=self.merchant,
+            sys_user=self.user,
+            name='仓管员',
+        )
+        self.client = APIClient()
+        self.client.force_authenticate(user=self.user)
+        self.strict_payload = {
+            'supplier': self.supplier.id,
+            'warehouse': self.warehouse_strict.id,
+            'return_date': '2025-11-26',
+            'items': [
+                {
+                    'product_id': self.product.id,
+                    'numbers': [5, 3],
+                    'price': '11.5',
+                    'unit': '米',
+                }
+            ],
+            'remarks': '采退测试',
+        }
+        self.strict_out_payload = {
+            'supplier': self.supplier.id,
+            'warehouse': self.warehouse_strict_out.id,
+            'return_date': '2025-11-26',
+            'items': [
+                {
+                    'product_id': self.product.id,
+                    'consume_detail_ids': [201, 202],
+                    'quantity': 20,
+                    'price': '11.2',
+                    'unit': '米',
+                }
+            ],
+        }
+
+    def _create_purchase_return_order(self, payload):
+        body = copy.deepcopy(payload)
+        response = self.client.post('/api/v1/purchase-return-orders/', body, format='json')
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        return response.data['id']
+
+    def test_create_purchase_return_order_success(self):
+        response = self.client.post('/api/v1/purchase-return-orders/', self.strict_payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertIn('id', response.data)
+        self.assertEqual(response.data['status'], business_models.PurchaseReturnStatusEnum.PENDING)
+
+    def test_create_purchase_return_requires_consume_ids_in_strict_out(self):
+        payload = copy.deepcopy(self.strict_out_payload)
+        payload['items'][0].pop('consume_detail_ids')
+        response = self.client.post('/api/v1/purchase-return-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn('consume_detail_ids', response.data['error'])
+
+    def test_review_purchase_return_order_approve(self):
+        order_id = self._create_purchase_return_order(self.strict_payload)
+        response = self.client.post(
+            f'/api/v1/purchase-return-orders/{order_id}/review/',
+            {'action': 'approve'},
+            format='json',
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data['status'], business_models.PurchaseReturnStatusEnum.APPROVED)
+
+    def test_purchase_return_cancel_blocked_after_stock_exists(self):
+        order_id = self._create_purchase_return_order(self.strict_payload)
+        stock_models.StockChangeRecord.objects.create(
+            merchant=self.merchant,
+            type=stock_models.StockChangeTypeEnum.REMOVE,
+            warehouse=self.warehouse_strict,
+            source_type=stock_models.StockChangeSourceEnum.PURCHASE_RETURN,
+            source_id=order_id,
+        )
+        response = self.client.post(
+            f'/api/v1/purchase-return-orders/{order_id}/review/',
+            {'action': 'cancel'},
+            format='json',
+        )
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        order = business_models.PurchaseReturnOrder.objects.get(id=order_id)
+        self.assertEqual(order.status, business_models.PurchaseReturnStatusEnum.PENDING)
+
+
+@override_settings(
+    CELERY_TASK_ALWAYS_EAGER=True,
+    CELERY_TASK_EAGER_PROPAGATES=True,
+)
+class SalesReturnOrderAPITestCase(TestCase):
+    def setUp(self):
+        self.merchant = Merchant.objects.create(name='销退商户', type=MerchantTypeEnum.FACTORY)
+        self.customer = Customer.objects.create(
+            merchant=self.merchant,
+            name='销退客户',
+            mobile='13900000000',
+            created_by=None,
+        )
+        self.warehouse_strict = WareHouse.objects.create(
+            merchant=self.merchant,
+            name='销退严进仓',
+            mode=WareHouseModeEnum.RESTRICT_IN,
+        )
+        self.warehouse_relaxed = WareHouse.objects.create(
+            merchant=self.merchant,
+            name='销退宽进仓',
+            mode=WareHouseModeEnum.UNRESTRICTED,
+        )
+        category = ProductCategory.objects.create(
+            merchant=self.merchant,
+            name='销退品类',
+            product_prefix='SR',
+        )
+        self.product = Product.objects.create(
+            merchant=self.merchant,
+            category=category,
+            name='销退产品',
+            human_id='SR-001',
+            unit=ProductUnitEnum.METER,
+        )
+        self.user = User.objects.create_user(username='sales_return_user', password='pass123')
+        self.employee = Employee.objects.create(
+            merchant=self.merchant,
+            sys_user=self.user,
+            name='销退员',
+        )
+        self.client = APIClient()
+        self.client.force_authenticate(user=self.user)
+        self.strict_payload = {
+            'customer': self.customer.id,
+            'warehouse': self.warehouse_strict.id,
+            'return_date': '2025-11-26',
+            'items': [
+                {
+                    'product_id': self.product.id,
+                    'numbers': [7, 3],
+                    'price': '14.5',
+                    'unit': '米',
+                }
+            ],
+        }
+        self.relaxed_payload = {
+            'customer': self.customer.id,
+            'warehouse': self.warehouse_relaxed.id,
+            'return_date': '2025-11-26',
+            'items': [
+                {
+                    'product_id': self.product.id,
+                    'quantity': 60,
+                    'num_of_rolls': 2,
+                    'price': '13.8',
+                }
+            ],
+            'remarks': '销退备注',
+        }
+
+    def _create_sales_return_order(self, payload):
+        body = copy.deepcopy(payload)
+        response = self.client.post('/api/v1/sales-return-orders/', body, format='json')
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        return response.data['id']
+
+    def test_create_sales_return_order_success(self):
+        response = self.client.post('/api/v1/sales-return-orders/', self.strict_payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        self.assertEqual(response.data['status'], business_models.SalesReturnStatusEnum.PENDING)
+
+    def test_create_sales_return_order_invalid_customer(self):
+        payload = {**self.strict_payload, 'customer': 999}
+        response = self.client.post('/api/v1/sales-return-orders/', payload, format='json')
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_review_sales_return_order_approve(self):
+        order_id = self._create_sales_return_order(self.relaxed_payload)
+        response = self.client.post(
+            f'/api/v1/sales-return-orders/{order_id}/review/',
+            {'action': 'approve'},
+            format='json',
+        )
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data['status'], business_models.SalesReturnStatusEnum.APPROVED)
+
+    def test_sales_return_cancel_blocked_after_stock_exists(self):
+        order_id = self._create_sales_return_order(self.strict_payload)
+        stock_models.StockChangeRecord.objects.create(
+            merchant=self.merchant,
+            type=stock_models.StockChangeTypeEnum.ADD,
+            warehouse=self.warehouse_strict,
+            source_type=stock_models.StockChangeSourceEnum.SALES_RETURN,
+            source_id=order_id,
+        )
+        response = self.client.post(
+            f'/api/v1/sales-return-orders/{order_id}/review/',
+            {'action': 'cancel'},
+            format='json',
+        )
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        order = business_models.SalesReturnOrder.objects.get(id=order_id)
+        self.assertEqual(order.status, business_models.SalesReturnStatusEnum.PENDING)
+
+
 class PaymentOrderAPITestCase(TestCase):
     def setUp(self):
         self.merchant = Merchant.objects.create(name='付款商户', type=MerchantTypeEnum.FACTORY)

api_v1/urls.py

@@ -15,6 +15,8 @@ from .views.business.sales import views as sales_views
 from .views.business.payment import views as payment_views
 from .views.business.receipt import views as receipt_views
 from .views.business.balance import views as balance_views
+from .views.business.purchase_return import views as purchase_return_views
+from .views.business.sales_return import views as sales_return_views
 from .views.stock_change_views.snapshot import StockSnapshotListView
 from .views.printing.views import PrintingOrderViewSet, PrintingJobViewSet, PlateOrderViewSet
 from .views.upload import UploadFileViewSet
@@ -64,8 +66,12 @@ urlpatterns = [
     path('inventory/', inventory.InventoryAPIView.as_view(), name='inventory'),
     path('purchase-orders/', purchase_views.PurchaseOrderView.as_view(), name='purchase_orders'),
     path('purchase-orders/<int:pk>/review/', purchase_views.PurchaseOrderReviewView.as_view(), name='purchase_order_review'),
+    path('purchase-return-orders/', purchase_return_views.PurchaseReturnOrderView.as_view(), name='purchase_return_orders'),
+    path('purchase-return-orders/<int:pk>/review/', purchase_return_views.PurchaseReturnOrderReviewView.as_view(), name='purchase_return_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('sales-return-orders/', sales_return_views.SalesReturnOrderView.as_view(), name='sales_return_orders'),
+    path('sales-return-orders/<int:pk>/review/', sales_return_views.SalesReturnOrderReviewView.as_view(), name='sales_return_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'),

api_v1/views/business/purchase_return/__init__.py

@@ -0,0 +1,2 @@
+
+

api_v1/views/business/purchase_return/views.py

@@ -0,0 +1,181 @@
+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 PurchaseReturnOrderItemSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = business_models.PurchaseReturnOrderItem
+        fields = [
+            'id', 'product', 'price', 'color', 'quantity', 'unit',
+            'empty_diff_percent', 'quantity_of_rolls', 'num_of_rolls',
+            'consume_detail_ids', 'batch_number', 'remarks',
+            'created_at', 'updated_at', 'spec',
+        ]
+        read_only_fields = [
+            'id', 'created_at', 'updated_at',
+            'total_amount', 'diff_quantity', 'real_quantity',
+        ]
+
+
+class PurchaseReturnOrderSerializer(serializers.ModelSerializer):
+    total_amount = serializers.SerializerMethodField(read_only=True)
+    diff_quantity = serializers.SerializerMethodField(read_only=True)
+    total_quantity = serializers.SerializerMethodField(read_only=True)
+    supplier_name = serializers.CharField(source='supplier.name', read_only=True)
+    operator_name = serializers.CharField(source='operator.name', read_only=True)
+    warehouse_name = serializers.CharField(source='warehouse.name', read_only=True)
+    items = PurchaseReturnOrderItemSerializer(many=True, read_only=True)
+
+    def get_total_amount(self, obj: business_models.PurchaseReturnOrder):
+        return obj.get_total_amount()
+
+    def get_diff_quantity(self, obj: business_models.PurchaseReturnOrder):
+        return obj.get_total_diff_quantity()
+
+    def get_total_quantity(self, obj: business_models.PurchaseReturnOrder):
+        return obj.get_total_quantity()
+
+    class Meta:
+        model = business_models.PurchaseReturnOrder
+        fields = [
+            'id', 'supplier', 'supplier_name', 'purchase_order', 'return_date',
+            'total_amount', 'diff_quantity', 'total_quantity',
+            'operator', 'operator_name', 'warehouse', 'warehouse_name',
+            'status', 'remarks', 'created_at', 'updated_at', 'items',
+        ]
+        read_only_fields = [
+            'id', 'created_at', 'updated_at', 'items',
+            'supplier_name', 'operator_name', 'warehouse_name',
+        ]
+
+
+class PurchaseReturnOrderPagination(pagination.LimitOffsetPagination):
+    default_limit = 20
+    max_limit = 100
+
+
+class PurchaseReturnOrderView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    pagination_class = PurchaseReturnOrderPagination
+
+    def get(self, request):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+
+        merchant = request.user.employee.merchant
+        queryset = business_models.PurchaseReturnOrder.objects.filter(merchant=merchant).prefetch_related(
+            'items', 'supplier', 'operator', 'warehouse'
+        )
+        paginator = self.pagination_class()
+        page = paginator.paginate_queryset(queryset.order_by('-created_at'), request, view=self)
+        serializer = PurchaseReturnOrderSerializer(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')
+        warehouse_id = data.get('warehouse_id') or data.get('warehouse')
+        return_date = data.get('return_date')
+        items = data.get('items', [])
+        remarks = data.get('remarks', '')
+        purchase_order_id = data.get('purchase_order')
+
+        if not supplier_id:
+            return Response({'error': '缺少供应商 ID'}, status=status.HTTP_400_BAD_REQUEST)
+        if not warehouse_id:
+            return Response({'error': '缺少仓库 ID'}, status=status.HTTP_400_BAD_REQUEST)
+        if not return_date:
+            return Response({'error': '缺少 return_date'}, status=status.HTTP_400_BAD_REQUEST)
+        if not isinstance(items, list) or not items:
+            return Response({'error': 'items 需要为非空数组'}, 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)
+
+        try:
+            warehouse = basic_models.WareHouse.objects.get(id=warehouse_id, merchant=merchant)
+        except basic_models.WareHouse.DoesNotExist:
+            return Response({'error': f'仓库 {warehouse_id} 不存在'}, status=status.HTTP_400_BAD_REQUEST)
+
+        operator = request.user.employee
+
+        try:
+            purchase_return = business_services.create_purchase_return_order(
+                merchant=merchant,
+                supplier=supplier,
+                return_date=return_date,
+                warehouse=warehouse,
+                operator=operator,
+                items=items,
+                remarks=remarks,
+                purchase_order_id=purchase_order_id,
+                created_by=request.user,
+            )
+        except ValueError as exc:
+            return Response({'error': str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+        return Response(
+            {
+                'id': purchase_return.id,
+                'status': purchase_return.status,
+                'message': '采购退货单创建成功，等待审批',
+            },
+            status=status.HTTP_201_CREATED,
+        )
+
+
+class PurchaseReturnOrderReviewSerializer(serializers.Serializer):
+    action = serializers.ChoiceField(choices=[('approve', '审批通过'), ('cancel', '作废')])
+
+
+class PurchaseReturnOrderReviewView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    ACTION_STATUS_MAP = {
+        'approve': business_models.PurchaseReturnStatusEnum.APPROVED,
+        'cancel': business_models.PurchaseReturnStatusEnum.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:
+            purchase_return_order = business_models.PurchaseReturnOrder.objects.select_related(
+                'supplier', 'operator', 'warehouse'
+            ).prefetch_related('items').get(id=pk, merchant=merchant)
+        except business_models.PurchaseReturnOrder.DoesNotExist:
+            return self.not_found_response('采购退货单不存在')
+
+        serializer = PurchaseReturnOrderReviewSerializer(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_purchase_return_order(
+                purchase_return_order=purchase_return_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_order = business_models.PurchaseReturnOrder.objects.select_related(
+            'supplier', 'operator', 'warehouse'
+        ).prefetch_related('items').get(id=purchase_return_order.id)
+        return Response(PurchaseReturnOrderSerializer(refreshed_order).data, status=status.HTTP_200_OK)
+

api_v1/views/business/sales_return/__init__.py

@@ -0,0 +1,2 @@
+
+

api_v1/views/business/sales_return/views.py

@@ -0,0 +1,180 @@
+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 SalesReturnOrderItemSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = business_models.SalesReturnOrderItem
+        fields = [
+            'id', 'product', 'price', 'color', 'quantity', 'unit',
+            'empty_diff_percent', 'quantity_of_rolls', 'num_of_rolls',
+            'batch_number', 'remarks', 'created_at', 'updated_at', 'spec',
+        ]
+        read_only_fields = [
+            'id', 'created_at', 'updated_at',
+            'total_amount', 'diff_quantity', 'real_quantity',
+        ]
+
+
+class SalesReturnOrderSerializer(serializers.ModelSerializer):
+    total_amount = serializers.SerializerMethodField(read_only=True)
+    diff_quantity = serializers.SerializerMethodField(read_only=True)
+    total_quantity = serializers.SerializerMethodField(read_only=True)
+    customer_name = serializers.CharField(source='customer.name', read_only=True)
+    operator_name = serializers.CharField(source='operator.name', read_only=True)
+    warehouse_name = serializers.CharField(source='warehouse.name', read_only=True)
+    items = SalesReturnOrderItemSerializer(many=True, read_only=True)
+
+    def get_total_amount(self, obj: business_models.SalesReturnOrder):
+        return obj.get_total_amount()
+
+    def get_diff_quantity(self, obj: business_models.SalesReturnOrder):
+        return obj.get_total_diff_quantity()
+
+    def get_total_quantity(self, obj: business_models.SalesReturnOrder):
+        return obj.get_total_quantity()
+
+    class Meta:
+        model = business_models.SalesReturnOrder
+        fields = [
+            'id', 'customer', 'customer_name', 'sales_order', 'return_date',
+            'total_amount', 'diff_quantity', 'total_quantity',
+            'operator', 'operator_name', 'warehouse', 'warehouse_name',
+            'status', 'remarks', 'created_at', 'updated_at', 'items',
+        ]
+        read_only_fields = [
+            'id', 'created_at', 'updated_at', 'items',
+            'customer_name', 'operator_name', 'warehouse_name',
+        ]
+
+
+class SalesReturnOrderPagination(pagination.LimitOffsetPagination):
+    default_limit = 20
+    max_limit = 100
+
+
+class SalesReturnOrderView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    pagination_class = SalesReturnOrderPagination
+
+    def get(self, request):
+        if not self.check_employee_permission(request):
+            return self.permission_error_response('无权限访问')
+
+        merchant = request.user.employee.merchant
+        queryset = business_models.SalesReturnOrder.objects.filter(merchant=merchant).prefetch_related(
+            'items', 'customer', 'operator', 'warehouse'
+        )
+        paginator = self.pagination_class()
+        page = paginator.paginate_queryset(queryset.order_by('-created_at'), request, view=self)
+        serializer = SalesReturnOrderSerializer(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')
+        warehouse_id = data.get('warehouse_id') or data.get('warehouse')
+        return_date = data.get('return_date')
+        items = data.get('items', [])
+        remarks = data.get('remarks', '')
+        sales_order_id = data.get('sales_order')
+
+        if not customer_id:
+            return Response({'error': '缺少客户 ID'}, status=status.HTTP_400_BAD_REQUEST)
+        if not warehouse_id:
+            return Response({'error': '缺少仓库 ID'}, status=status.HTTP_400_BAD_REQUEST)
+        if not return_date:
+            return Response({'error': '缺少 return_date'}, status=status.HTTP_400_BAD_REQUEST)
+        if not isinstance(items, list) or not items:
+            return Response({'error': 'items 需要为非空数组'}, 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)
+
+        try:
+            warehouse = basic_models.WareHouse.objects.get(id=warehouse_id, merchant=merchant)
+        except basic_models.WareHouse.DoesNotExist:
+            return Response({'error': f'仓库 {warehouse_id} 不存在'}, status=status.HTTP_400_BAD_REQUEST)
+
+        operator = request.user.employee
+
+        try:
+            sales_return = business_services.create_sales_return_order(
+                merchant=merchant,
+                customer=customer,
+                return_date=return_date,
+                warehouse=warehouse,
+                operator=operator,
+                items=items,
+                remarks=remarks,
+                sales_order_id=sales_order_id,
+                created_by=request.user,
+            )
+        except ValueError as exc:
+            return Response({'error': str(exc)}, status=status.HTTP_400_BAD_REQUEST)
+
+        return Response(
+            {
+                'id': sales_return.id,
+                'status': sales_return.status,
+                'message': '销售退货单创建成功，等待审批',
+            },
+            status=status.HTTP_201_CREATED,
+        )
+
+
+class SalesReturnOrderReviewSerializer(serializers.Serializer):
+    action = serializers.ChoiceField(choices=[('approve', '审批通过'), ('cancel', '作废')])
+
+
+class SalesReturnOrderReviewView(StockChangeViewMixin, views.APIView):
+    permission_classes = [IsAuthenticated]
+    ACTION_STATUS_MAP = {
+        'approve': business_models.SalesReturnStatusEnum.APPROVED,
+        'cancel': business_models.SalesReturnStatusEnum.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:
+            sales_return_order = business_models.SalesReturnOrder.objects.select_related(
+                'customer', 'operator', 'warehouse'
+            ).prefetch_related('items').get(id=pk, merchant=merchant)
+        except business_models.SalesReturnOrder.DoesNotExist:
+            return self.not_found_response('销售退货单不存在')
+
+        serializer = SalesReturnOrderReviewSerializer(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_sales_return_order(
+                sales_return_order=sales_return_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_order = business_models.SalesReturnOrder.objects.select_related(
+            'customer', 'operator', 'warehouse'
+        ).prefetch_related('items').get(id=sales_return_order.id)
+        return Response(SalesReturnOrderSerializer(refreshed_order).data, status=status.HTTP_200_OK)
+

business/ARCHITECTURE.md

@@ -37,6 +37,8 @@
 
 - **PurchaseOrder**（采购单）：`direction=1`，`counterparty=supplier`，含库存明细。
 - **SalesOrder**（销售单）：`direction=-1`，`counterparty=customer`，含库存明细；严进严出模式需记录 `consume_detail_ids`。
+- **PurchaseReturnOrder**（采购退货单）：`direction=-1`，`counterparty=supplier`，仓库出库、供应商欠款减少，可选关联原采购单。
+- **SalesReturnOrder**（销售退货单）：`direction=1`，`counterparty=customer`，仓库入库、客户欠款减少，可选关联原销售单。
 - **PaymentOrder**（付款单）：`direction=-1`，`counterparty=supplier`，仅金额字段，不触发库存。
 - **ReceiptOrder**（收款单）：`direction=-1`，`counterparty=customer`，仅金额字段，不触发库存。
 - **SupplierBalance / CustomerBalance**：实时维护供应商应付、客户应收余额，所有审批通过的带金额单据都会写入，供查询接口和报表使用。

business/admin.py

@@ -49,6 +49,82 @@ class PurchaseOrderItemAdmin(admin.ModelAdmin):
         return obj.total_amount()
 
 
+@admin.register(models.PurchaseReturnOrder)
+class PurchaseReturnOrderAdmin(admin.ModelAdmin):
+    list_display = ('id', 'supplier', 'return_date', 'operator', 'status', '_total_amount', 'created_at')
+    search_fields = ('supplier__name',)
+    list_filter = ('operator', 'warehouse', 'status', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='总价')
+    def _total_amount(self, obj: models.PurchaseReturnOrder):
+        return obj.get_total_amount()
+
+
+@admin.register(models.PurchaseReturnOrderItem)
+class PurchaseReturnOrderItemAdmin(admin.ModelAdmin):
+    list_display = (
+        'id', 'purchase_return_order', 'product',
+        'quantity', 'unit', 'price', 'batch_number',
+        '_total_amount', 'empty_diff_percent',
+        '_real_quantity', '_diff_quantity',
+        'num_of_rolls',
+    )
+    search_fields = ('purchase_return_order__id', 'product__name')
+    list_filter = ('purchase_return_order__operator', 'purchase_return_order__warehouse', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='实际数量')
+    def _real_quantity(self, obj: models.PurchaseReturnOrderItem):
+        return obj.real_quantity()
+
+    @admin.display(description='差异数量')
+    def _diff_quantity(self, obj: models.PurchaseReturnOrderItem):
+        return obj.diff_quantity()
+
+    @admin.display(description='总金额')
+    def _total_amount(self, obj: models.PurchaseReturnOrderItem):
+        return obj.total_amount()
+
+
+@admin.register(models.SalesReturnOrder)
+class SalesReturnOrderAdmin(admin.ModelAdmin):
+    list_display = ('id', 'customer', 'return_date', 'operator', 'status', '_total_amount', 'created_at')
+    search_fields = ('customer__name',)
+    list_filter = ('operator', 'warehouse', 'status', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='总价')
+    def _total_amount(self, obj: models.SalesReturnOrder):
+        return obj.get_total_amount()
+
+
+@admin.register(models.SalesReturnOrderItem)
+class SalesReturnOrderItemAdmin(admin.ModelAdmin):
+    list_display = (
+        'id', 'sales_return_order', 'product',
+        'quantity', 'unit', 'price', 'batch_number',
+        '_total_amount', 'empty_diff_percent',
+        '_real_quantity', '_diff_quantity',
+        'num_of_rolls',
+    )
+    search_fields = ('sales_return_order__id', 'product__name')
+    list_filter = ('sales_return_order__operator', 'sales_return_order__warehouse', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='实际数量')
+    def _real_quantity(self, obj: models.SalesReturnOrderItem):
+        return obj.real_quantity()
+
+    @admin.display(description='差异数量')
+    def _diff_quantity(self, obj: models.SalesReturnOrderItem):
+        return obj.diff_quantity()
+
+    @admin.display(description='总金额')
+    def _total_amount(self, obj: models.SalesReturnOrderItem):
+        return obj.total_amount()
+
+
 @admin.register(models.CustomerBalance)
 class CustomerBalancemAdmin(admin.ModelAdmin):
     list_display = ('id', 'customer', 'balance', 'created_at')

business/migrations/0014_alter_balancechangerecord_source_type_and_more.py

@@ -0,0 +1,113 @@
+# Generated by Django 5.2.7 on 2025-12-01 08:22
+
+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', '0013_balancechangerecord'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='balancechangerecord',
+            name='source_type',
+            field=models.IntegerField(choices=[(1, '采购单'), (2, '销售单'), (3, '付款单'), (4, '收款单'), (5, '采购退货单'), (6, '销售退货单')], verbose_name='来源业务类型'),
+        ),
+        migrations.CreateModel(
+            name='PurchaseReturnOrder',
+            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)),
+                ('return_date', models.DateField(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='purchase_return_orders', to='basic_info.merchant', verbose_name='所属商户')),
+                ('operator', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_orders', to='basic_info.employee', verbose_name='经办人')),
+                ('purchase_order', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='return_orders', to='business.purchaseorder', verbose_name='原采购单')),
+                ('supplier', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_orders', to='basic_info.supplier', verbose_name='供应商')),
+                ('warehouse', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_orders', to='basic_info.warehouse', verbose_name='仓库')),
+            ],
+            options={
+                'verbose_name': '采购退货单',
+                'verbose_name_plural': '采购退货单',
+            },
+            bases=(business.models.OrderItemsAggregationMixin, business.models.OrderDirectionMixin, business.models.OrderCounterpartyMixin, models.Model),
+        ),
+        migrations.CreateModel(
+            name='PurchaseReturnOrderItem',
+            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)),
+                ('price', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='单价')),
+                ('color', models.CharField(blank=True, max_length=50, null=True, verbose_name='颜色')),
+                ('quantity', models.DecimalField(decimal_places=2, max_digits=10, verbose_name='数量')),
+                ('unit', models.CharField(max_length=50, verbose_name='单位')),
+                ('spec', models.CharField(blank=True, max_length=100, null=True, verbose_name='规格')),
+                ('empty_diff_percent', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='空差百分比')),
+                ('quantity_of_rolls', models.CharField(blank=True, max_length=255, null=True, verbose_name='各条数数量')),
+                ('num_of_rolls', models.PositiveIntegerField(default=1, verbose_name='条数')),
+                ('consume_detail_ids', models.CharField(blank=True, max_length=255, null=True, verbose_name='关联入库明细ID')),
+                ('batch_number', models.CharField(blank=True, max_length=100, null=True, verbose_name='批次号')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('product', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_order_items', to='basic_info.product', verbose_name='产品')),
+                ('purchase_return_order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='business.purchasereturnorder', verbose_name='采购退货单')),
+            ],
+            options={
+                'verbose_name': '采购退货明细',
+                'verbose_name_plural': '采购退货明细',
+            },
+        ),
+        migrations.CreateModel(
+            name='SalesReturnOrder',
+            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)),
+                ('return_date', models.DateField(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='sales_return_orders', to='basic_info.customer', verbose_name='客户')),
+                ('merchant', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_orders', to='basic_info.merchant', verbose_name='所属商户')),
+                ('operator', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_orders', to='basic_info.employee', verbose_name='经办人')),
+                ('sales_order', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='return_orders', to='business.salesorder', verbose_name='原销售单')),
+                ('warehouse', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_orders', to='basic_info.warehouse', verbose_name='仓库')),
+            ],
+            options={
+                'verbose_name': '销售退货单',
+                'verbose_name_plural': '销售退货单',
+            },
+            bases=(business.models.OrderItemsAggregationMixin, business.models.OrderDirectionMixin, business.models.OrderCounterpartyMixin, models.Model),
+        ),
+        migrations.CreateModel(
+            name='SalesReturnOrderItem',
+            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)),
+                ('price', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='单价')),
+                ('color', models.CharField(blank=True, max_length=50, null=True, verbose_name='颜色')),
+                ('quantity', models.DecimalField(decimal_places=2, max_digits=10, verbose_name='数量')),
+                ('unit', models.CharField(max_length=50, verbose_name='单位')),
+                ('spec', models.CharField(blank=True, max_length=100, null=True, verbose_name='规格')),
+                ('empty_diff_percent', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='空差百分比')),
+                ('quantity_of_rolls', models.CharField(blank=True, max_length=255, null=True, verbose_name='各条数数量')),
+                ('num_of_rolls', models.PositiveIntegerField(default=1, verbose_name='条数')),
+                ('consume_detail_ids', models.CharField(blank=True, max_length=255, null=True, verbose_name='关联入库明细ID')),
+                ('batch_number', models.CharField(blank=True, max_length=100, null=True, verbose_name='批次号')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('product', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_order_items', to='basic_info.product', verbose_name='产品')),
+                ('sales_return_order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='business.salesreturnorder', verbose_name='销售退货单')),
+            ],
+            options={
+                'verbose_name': '销售退货明细',
+                'verbose_name_plural': '销售退货明细',
+            },
+        ),
+    ]

business/models.py

@@ -318,6 +318,224 @@ class SalesOrderItem(ModelBase):
         return round(self.price * self.real_quantity(), 2)
 
 
+class PurchaseReturnStatusEnum(models.IntegerChoices):
+    PENDING = 1, '审批中'
+    APPROVED = 2, '审批通过'
+    CANCELLED = 3, '作废'
+
+
+class PurchaseReturnOrder(OrderItemsAggregationMixin, OrderDirectionMixin, OrderCounterpartyMixin, ModelBase):
+    """采购退货单（库存出库 + 供应商应付减少）"""
+
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.ForeignKey(
+        basic_info_models.Merchant,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='所属商户',
+    )
+    supplier = models.ForeignKey(
+        basic_info_models.Supplier,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='供应商',
+    )
+    purchase_order = models.ForeignKey(
+        'PurchaseOrder',
+        on_delete=models.SET_NULL,
+        related_name='return_orders',
+        null=True,
+        blank=True,
+        verbose_name='原采购单',
+    )
+    return_date = models.DateField(verbose_name='退货日期')
+    operator = models.ForeignKey(
+        basic_info_models.Employee,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='经办人',
+    )
+    warehouse = models.ForeignKey(
+        basic_info_models.WareHouse,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='仓库',
+    )
+    status = models.IntegerField(
+        choices=PurchaseReturnStatusEnum.choices,
+        default=PurchaseReturnStatusEnum.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_direction(self) -> int:
+        return -1
+
+    def get_counterparty_field_name(self) -> str:
+        return 'supplier'
+
+
+class PurchaseReturnOrderItem(ModelBase):
+    id = models.BigAutoField(primary_key=True)
+    purchase_return_order = models.ForeignKey(
+        PurchaseReturnOrder,
+        on_delete=models.CASCADE,
+        related_name='items',
+        verbose_name='采购退货单',
+    )
+    product = models.ForeignKey(
+        basic_info_models.Product,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_order_items',
+        verbose_name='产品',
+    )
+    price = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='单价')
+    color = models.CharField(max_length=50, null=True, blank=True, verbose_name='颜色')
+    quantity = models.DecimalField(max_digits=10, decimal_places=2, verbose_name='数量')
+    unit = models.CharField(max_length=50, verbose_name='单位')
+    spec = models.CharField(max_length=100, null=True, blank=True, verbose_name='规格')
+    empty_diff_percent = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='空差百分比')
+    quantity_of_rolls = models.CharField(max_length=255, null=True, blank=True, verbose_name='各条数数量')
+    num_of_rolls = models.PositiveIntegerField(default=1, verbose_name='条数')
+    consume_detail_ids = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        verbose_name='关联入库明细ID',
+    )
+    batch_number = models.CharField(null=True, blank=True, max_length=100, verbose_name='批次号')
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '采购退货明细'
+        verbose_name_plural = '采购退货明细'
+
+    def real_quantity(self):
+        return round(self.quantity * (1 - self.empty_diff_percent / 100), 2)
+
+    def diff_quantity(self):
+        return round(self.quantity * (self.empty_diff_percent / 100), 2)
+
+    def total_amount(self):
+        return round(self.price * self.real_quantity(), 2)
+
+
+class SalesReturnStatusEnum(models.IntegerChoices):
+    PENDING = 1, '审批中'
+    APPROVED = 2, '审批通过'
+    CANCELLED = 3, '作废'
+
+
+class SalesReturnOrder(OrderItemsAggregationMixin, OrderDirectionMixin, OrderCounterpartyMixin, ModelBase):
+    """销售退货单（库存入库 + 客户应收减少）"""
+
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.ForeignKey(
+        basic_info_models.Merchant,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='所属商户',
+    )
+    customer = models.ForeignKey(
+        basic_info_models.Customer,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='客户',
+    )
+    sales_order = models.ForeignKey(
+        'SalesOrder',
+        on_delete=models.SET_NULL,
+        related_name='return_orders',
+        null=True,
+        blank=True,
+        verbose_name='原销售单',
+    )
+    return_date = models.DateField(verbose_name='退货日期')
+    operator = models.ForeignKey(
+        basic_info_models.Employee,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='经办人',
+    )
+    warehouse = models.ForeignKey(
+        basic_info_models.WareHouse,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='仓库',
+    )
+    status = models.IntegerField(
+        choices=SalesReturnStatusEnum.choices,
+        default=SalesReturnStatusEnum.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_direction(self) -> int:
+        return 1
+
+    def get_counterparty_field_name(self) -> str:
+        return 'customer'
+
+
+class SalesReturnOrderItem(ModelBase):
+    id = models.BigAutoField(primary_key=True)
+    sales_return_order = models.ForeignKey(
+        SalesReturnOrder,
+        on_delete=models.CASCADE,
+        related_name='items',
+        verbose_name='销售退货单',
+    )
+    product = models.ForeignKey(
+        basic_info_models.Product,
+        on_delete=models.PROTECT,
+        related_name='sales_return_order_items',
+        verbose_name='产品',
+    )
+    price = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='单价')
+    color = models.CharField(max_length=50, null=True, blank=True, verbose_name='颜色')
+    quantity = models.DecimalField(max_digits=10, decimal_places=2, verbose_name='数量')
+    unit = models.CharField(max_length=50, verbose_name='单位')
+    spec = models.CharField(max_length=100, null=True, blank=True, verbose_name='规格')
+    empty_diff_percent = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='空差百分比')
+    quantity_of_rolls = models.CharField(max_length=255, null=True, blank=True, verbose_name='各条数数量')
+    num_of_rolls = models.PositiveIntegerField(default=1, verbose_name='条数')
+    consume_detail_ids = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        verbose_name='关联入库明细ID',
+    )
+    batch_number = models.CharField(null=True, blank=True, max_length=100, verbose_name='批次号')
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '销售退货明细'
+        verbose_name_plural = '销售退货明细'
+
+    def real_quantity(self):
+        return round(self.quantity * (1 - self.empty_diff_percent / 100), 2)
+
+    def diff_quantity(self):
+        return round(self.quantity * (self.empty_diff_percent / 100), 2)
+
+    def total_amount(self):
+        return round(self.price * self.real_quantity(), 2)
+
+
 class PaymentOrderStatusEnum(models.IntegerChoices):
     PENDING = 1, '审批中'
     APPROVED = 2, '审批通过'
@@ -474,6 +692,8 @@ class BalanceChangeSourceEnum(models.IntegerChoices):
     SALES_ORDER = 2, '销售单'
     PAYMENT_ORDER = 3, '付款单'
     RECEIPT_ORDER = 4, '收款单'
+    PURCHASE_RETURN_ORDER = 5, '采购退货单'
+    SALES_RETURN_ORDER = 6, '销售退货单'
 
 
 class BalanceChangeDirectionEnum(models.IntegerChoices):

business/services.py

@@ -17,6 +17,8 @@ from . import models
 from .tasks import (
     create_purchase_order_stock_entries,
     create_sales_order_stock_entries,
+    create_purchase_return_order_stock_entries,
+    create_sales_return_order_stock_entries,
 )
 class BalanceService:
     @staticmethod
@@ -292,6 +294,150 @@ def create_sales_order(
     return sales_order
 
 
+def create_purchase_return_order(
+    *,
+    merchant: basic_info_models.Merchant,
+    supplier: basic_info_models.Supplier,
+    return_date,
+    warehouse: basic_info_models.WareHouse,
+    operator: basic_info_models.Employee,
+    items: List[Dict[str, Any]],
+    remarks: str | None = '',
+    purchase_order: models.PurchaseOrder | None = None,
+    purchase_order_id: int | None = None,
+    created_by=None,
+) -> models.PurchaseReturnOrder:
+    """
+    创建采购退货单，出库并冲减供应商欠款。
+    """
+    if not items:
+        raise ValueError('items 不能为空')
+
+    normalized_date = _normalize_order_date(return_date)
+    normalized_items, _ = _normalize_order_items(
+        merchant=merchant,
+        warehouse=warehouse,
+        items=items,
+        is_outgoing=True,
+    )
+
+    resolved_purchase_order = purchase_order
+    if resolved_purchase_order is None and purchase_order_id:
+        resolved_purchase_order = models.PurchaseOrder.objects.filter(
+            id=purchase_order_id,
+            merchant=merchant,
+        ).first()
+        if resolved_purchase_order is None:
+            raise ValueError('关联的采购单不存在或不属于当前商户')
+    if resolved_purchase_order and resolved_purchase_order.supplier_id != supplier.id:
+        raise ValueError('采购退货单的供应商必须与原采购单一致')
+
+    with transaction.atomic():
+        return_order = models.PurchaseReturnOrder.objects.create(
+            merchant=merchant,
+            supplier=supplier,
+            purchase_order=resolved_purchase_order,
+            return_date=normalized_date,
+            operator=operator,
+            warehouse=warehouse,
+            remarks=remarks,
+        )
+        bulk_objects = [
+            models.PurchaseReturnOrderItem(
+                purchase_return_order=return_order,
+                product=item_data['product'],
+                price=item_data['price'],
+                color=item_data.get('color'),
+                quantity=item_data['quantity'],
+                unit=item_data['unit'],
+                spec=item_data.get('spec'),
+                empty_diff_percent=item_data['empty_diff_percent'],
+                quantity_of_rolls=item_data.get('quantity_of_rolls'),
+                num_of_rolls=item_data['num_of_rolls'],
+                consume_detail_ids=item_data.get('consume_detail_ids'),
+                batch_number=item_data.get('batch_number'),
+                remarks=item_data.get('remarks'),
+            )
+            for item_data in normalized_items
+        ]
+        models.PurchaseReturnOrderItem.objects.bulk_create(bulk_objects)
+
+    return_order.refresh_from_db()
+    return return_order
+
+
+def create_sales_return_order(
+    *,
+    merchant: basic_info_models.Merchant,
+    customer: basic_info_models.Customer,
+    return_date,
+    warehouse: basic_info_models.WareHouse,
+    operator: basic_info_models.Employee,
+    items: List[Dict[str, Any]],
+    remarks: str | None = '',
+    sales_order: models.SalesOrder | None = None,
+    sales_order_id: int | None = None,
+    created_by=None,
+) -> models.SalesReturnOrder:
+    """
+    创建销售退货单，入库并冲减客户欠款。
+    """
+    if not items:
+        raise ValueError('items 不能为空')
+
+    normalized_date = _normalize_order_date(return_date)
+    normalized_items, _ = _normalize_order_items(
+        merchant=merchant,
+        warehouse=warehouse,
+        items=items,
+        is_outgoing=False,
+    )
+
+    resolved_sales_order = sales_order
+    if resolved_sales_order is None and sales_order_id:
+        resolved_sales_order = models.SalesOrder.objects.filter(
+            id=sales_order_id,
+            merchant=merchant,
+        ).first()
+        if resolved_sales_order is None:
+            raise ValueError('关联的销售单不存在或不属于当前商户')
+    if resolved_sales_order and resolved_sales_order.customer_id != customer.id:
+        raise ValueError('销售退货单的客户必须与原销售单一致')
+
+    with transaction.atomic():
+        return_order = models.SalesReturnOrder.objects.create(
+            merchant=merchant,
+            customer=customer,
+            sales_order=resolved_sales_order,
+            return_date=normalized_date,
+            operator=operator,
+            warehouse=warehouse,
+            remarks=remarks,
+        )
+        bulk_objects = [
+            models.SalesReturnOrderItem(
+                sales_return_order=return_order,
+                product=item_data['product'],
+                price=item_data['price'],
+                color=item_data.get('color'),
+                quantity=item_data['quantity'],
+                unit=item_data['unit'],
+                spec=item_data.get('spec'),
+                empty_diff_percent=item_data['empty_diff_percent'],
+                quantity_of_rolls=item_data.get('quantity_of_rolls'),
+                num_of_rolls=item_data['num_of_rolls'],
+                consume_detail_ids=item_data.get('consume_detail_ids'),
+                batch_number=item_data.get('batch_number'),
+                remarks=item_data.get('remarks'),
+            )
+            for item_data in normalized_items
+        ]
+        models.SalesReturnOrderItem.objects.bulk_create(bulk_objects)
+
+    return_order.refresh_from_db()
+    return return_order
+
+
 def create_payment_order(
     *,
     merchant: basic_info_models.Merchant,
@@ -409,6 +555,58 @@ def review_sales_order(
     return _cancel_sales_order(order)
 
 
+def review_purchase_return_order(
+    *,
+    purchase_return_order: models.PurchaseReturnOrder | None = None,
+    purchase_return_order_id: int | None = None,
+    target_status: models.PurchaseReturnStatusEnum,
+    reviewed_by=None,
+) -> models.PurchaseReturnOrder:
+    order = _resolve_purchase_return_order_instance(purchase_return_order, purchase_return_order_id)
+
+    if target_status not in {
+        models.PurchaseReturnStatusEnum.APPROVED,
+        models.PurchaseReturnStatusEnum.CANCELLED,
+    }:
+        raise ValueError('target_status 只能是 APPROVED 或 CANCELLED')
+
+    if order.status == target_status:
+        return order
+
+    if target_status == models.PurchaseReturnStatusEnum.APPROVED:
+        if order.status == models.PurchaseReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的采购退货单无法再次审批')
+        return _approve_purchase_return_order(order, reviewed_by)
+
+    return _cancel_purchase_return_order(order)
+
+
+def review_sales_return_order(
+    *,
+    sales_return_order: models.SalesReturnOrder | None = None,
+    sales_return_order_id: int | None = None,
+    target_status: models.SalesReturnStatusEnum,
+    reviewed_by=None,
+) -> models.SalesReturnOrder:
+    order = _resolve_sales_return_order_instance(sales_return_order, sales_return_order_id)
+
+    if target_status not in {
+        models.SalesReturnStatusEnum.APPROVED,
+        models.SalesReturnStatusEnum.CANCELLED,
+    }:
+        raise ValueError('target_status 只能是 APPROVED 或 CANCELLED')
+
+    if order.status == target_status:
+        return order
+
+    if target_status == models.SalesReturnStatusEnum.APPROVED:
+        if order.status == models.SalesReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的销售退货单无法再次审批')
+        return _approve_sales_return_order(order, reviewed_by)
+
+    return _cancel_sales_return_order(order)
+
+
 def review_payment_order(
     *,
     payment_order: models.PaymentOrder | None = None,
@@ -746,6 +944,128 @@ def _cancel_sales_order(sales_order: models.SalesOrder) -> models.SalesOrder:
     return locked
 
 
+def _approve_purchase_return_order(
+    purchase_return_order: models.PurchaseReturnOrder,
+    reviewed_by,
+) -> models.PurchaseReturnOrder:
+    with transaction.atomic():
+        locked_order = models.PurchaseReturnOrder.objects.select_related(
+            'merchant', 'warehouse', 'supplier'
+        ).prefetch_related('items').select_for_update().get(id=purchase_return_order.id)
+
+        if locked_order.status == models.PurchaseReturnStatusEnum.APPROVED:
+            return locked_order
+        if locked_order.status == models.PurchaseReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的采购退货单无法再次审批')
+
+        stock_flow_items = _build_stock_flow_items_from_order(locked_order)
+
+        locked_order.status = models.PurchaseReturnStatusEnum.APPROVED
+        locked_order.save(update_fields=['status', 'updated_at'])
+        BalanceService.adjust_supplier_balance(
+            merchant=locked_order.merchant,
+            supplier=locked_order.supplier,
+            delta=-locked_order.get_total_amount(),
+            source_type=models.BalanceChangeSourceEnum.PURCHASE_RETURN_ORDER,
+            source_id=locked_order.id,
+        )
+
+    created_by_id = getattr(reviewed_by, 'id', None)
+    if _auto_stock_task_enabled(locked_order.merchant):
+        logger.info('审批通过采购退货单 %s，触发出库任务', locked_order.id)
+        create_purchase_return_order_stock_entries.delay(
+            purchase_return_order_id=locked_order.id,
+            warehouse_id=locked_order.warehouse_id,
+            items=stock_flow_items,
+            created_by_id=created_by_id,
+        )
+
+    locked_order.refresh_from_db(fields=['status', 'updated_at'])
+    return locked_order
+
+
+def _cancel_purchase_return_order(
+    purchase_return_order: models.PurchaseReturnOrder,
+) -> models.PurchaseReturnOrder:
+    with transaction.atomic():
+        locked = models.PurchaseReturnOrder.objects.select_related('merchant').select_for_update().get(
+            id=purchase_return_order.id
+        )
+        if locked.status == models.PurchaseReturnStatusEnum.APPROVED:
+            raise ValueError('已审批的采购退货单无法作废')
+        if _order_has_stock_records(
+            merchant_id=locked.merchant_id,
+            source_type=stock_models.StockChangeSourceEnum.PURCHASE_RETURN,
+            source_id=locked.id,
+        ):
+            raise ValueError('采购退货单已生成出入库记录，无法作废')
+        locked.status = models.PurchaseReturnStatusEnum.CANCELLED
+        locked.save(update_fields=['status', 'updated_at'])
+    locked.refresh_from_db(fields=['status', 'updated_at'])
+    return locked
+
+
+def _approve_sales_return_order(
+    sales_return_order: models.SalesReturnOrder,
+    reviewed_by,
+) -> models.SalesReturnOrder:
+    with transaction.atomic():
+        locked_order = models.SalesReturnOrder.objects.select_related(
+            'merchant', 'warehouse', 'customer'
+        ).prefetch_related('items').select_for_update().get(id=sales_return_order.id)
+
+        if locked_order.status == models.SalesReturnStatusEnum.APPROVED:
+            return locked_order
+        if locked_order.status == models.SalesReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的销售退货单无法再次审批')
+
+        stock_flow_items = _build_stock_flow_items_from_order(locked_order)
+
+        locked_order.status = models.SalesReturnStatusEnum.APPROVED
+        locked_order.save(update_fields=['status', 'updated_at'])
+        BalanceService.adjust_customer_balance(
+            merchant=locked_order.merchant,
+            customer=locked_order.customer,
+            delta=-locked_order.get_total_amount(),
+            source_type=models.BalanceChangeSourceEnum.SALES_RETURN_ORDER,
+            source_id=locked_order.id,
+        )
+
+    created_by_id = getattr(reviewed_by, 'id', None)
+    if _auto_stock_task_enabled(locked_order.merchant):
+        logger.info('审批通过销售退货单 %s，触发入库任务', locked_order.id)
+        create_sales_return_order_stock_entries.delay(
+            sales_return_order_id=locked_order.id,
+            warehouse_id=locked_order.warehouse_id,
+            items=stock_flow_items,
+            created_by_id=created_by_id,
+        )
+
+    locked_order.refresh_from_db(fields=['status', 'updated_at'])
+    return locked_order
+
+
+def _cancel_sales_return_order(
+    sales_return_order: models.SalesReturnOrder,
+) -> models.SalesReturnOrder:
+    with transaction.atomic():
+        locked = models.SalesReturnOrder.objects.select_related('merchant').select_for_update().get(
+            id=sales_return_order.id
+        )
+        if locked.status == models.SalesReturnStatusEnum.APPROVED:
+            raise ValueError('已审批的销售退货单无法作废')
+        if _order_has_stock_records(
+            merchant_id=locked.merchant_id,
+            source_type=stock_models.StockChangeSourceEnum.SALES_RETURN,
+            source_id=locked.id,
+        ):
+            raise ValueError('销售退货单已生成出入库记录，无法作废')
+        locked.status = models.SalesReturnStatusEnum.CANCELLED
+        locked.save(update_fields=['status', 'updated_at'])
+    locked.refresh_from_db(fields=['status', 'updated_at'])
+    return locked
+
+
 def create_purchase_order_stock_entries_sync(
     *,
     purchase_order_id: int,
@@ -826,6 +1146,90 @@ def create_sales_order_stock_entries_sync(
     return payload
 
 
+def create_purchase_return_order_stock_entries_sync(
+    *,
+    purchase_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    """
+    根据采购退货单生成出库记录。
+    """
+    try:
+        purchase_return_order = models.PurchaseReturnOrder.objects.select_related('merchant').get(
+            id=purchase_return_order_id
+        )
+    except models.PurchaseReturnOrder.DoesNotExist:
+        logger.error('PurchaseReturnOrder %s 不存在，无法创建出库单', purchase_return_order_id)
+        return {'error': 'purchase_return_order_not_found', 'purchase_return_order_id': purchase_return_order_id}
+
+    merchant = purchase_return_order.merchant
+
+    created_by = None
+    if created_by_id:
+        UserModel = get_user_model()
+        created_by = UserModel.objects.filter(id=created_by_id).first()
+
+    service = StockFlowService(merchant=merchant, created_by=created_by)
+    record, details, created_count = service.stock_out(
+        warehouse_id=warehouse_id,
+        source_type=stock_models.StockChangeSourceEnum.PURCHASE_RETURN,
+        source_id=purchase_return_order.id,
+        items=items,
+    )
+
+    payload = {
+        'purchase_return_order_id': purchase_return_order.id,
+        'stock_change_record_id': getattr(record, 'id', None),
+        'created_details_count': created_count,
+    }
+    logger.info('采购退货单 %s 出库任务完成: %s', purchase_return_order.id, payload)
+    return payload
+
+
+def create_sales_return_order_stock_entries_sync(
+    *,
+    sales_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    """
+    根据销售退货单生成入库记录。
+    """
+    try:
+        sales_return_order = models.SalesReturnOrder.objects.select_related('merchant').get(
+            id=sales_return_order_id
+        )
+    except models.SalesReturnOrder.DoesNotExist:
+        logger.error('SalesReturnOrder %s 不存在，无法创建入库单', sales_return_order_id)
+        return {'error': 'sales_return_order_not_found', 'sales_return_order_id': sales_return_order_id}
+
+    merchant = sales_return_order.merchant
+
+    created_by = None
+    if created_by_id:
+        UserModel = get_user_model()
+        created_by = UserModel.objects.filter(id=created_by_id).first()
+
+    service = StockFlowService(merchant=merchant, created_by=created_by)
+    record, details, created_count = service.stock_in(
+        warehouse_id=warehouse_id,
+        source_type=stock_models.StockChangeSourceEnum.SALES_RETURN,
+        source_id=sales_return_order.id,
+        items=items,
+    )
+
+    payload = {
+        'sales_return_order_id': sales_return_order.id,
+        'stock_change_record_id': getattr(record, 'id', None),
+        'created_details_count': created_count,
+    }
+    logger.info('销售退货单 %s 入库任务完成: %s', sales_return_order.id, payload)
+    return payload
+
+
 def _build_stock_flow_items_from_order(order) -> List[Dict[str, Any]]:
     """
     根据订单明细还原 StockFlowService 所需的 items 结构。
@@ -925,6 +1329,36 @@ def _resolve_sales_order_instance(
     )
 
 
+def _resolve_purchase_return_order_instance(
+    purchase_return_order: models.PurchaseReturnOrder | None,
+    purchase_return_order_id: int | None,
+) -> models.PurchaseReturnOrder:
+    if purchase_return_order is None and purchase_return_order_id is None:
+        raise ValueError('必须提供 purchase_return_order 或 purchase_return_order_id')
+
+    if purchase_return_order is not None:
+        purchase_return_order_id = purchase_return_order.id
+
+    return models.PurchaseReturnOrder.objects.select_related('merchant', 'warehouse').prefetch_related('items').get(
+        id=purchase_return_order_id
+    )
+
+
+def _resolve_sales_return_order_instance(
+    sales_return_order: models.SalesReturnOrder | None,
+    sales_return_order_id: int | None,
+) -> models.SalesReturnOrder:
+    if sales_return_order is None and sales_return_order_id is None:
+        raise ValueError('必须提供 sales_return_order 或 sales_return_order_id')
+
+    if sales_return_order is not None:
+        sales_return_order_id = sales_return_order.id
+
+    return models.SalesReturnOrder.objects.select_related('merchant', 'warehouse').prefetch_related('items').get(
+        id=sales_return_order_id
+    )
+
+
 def _resolve_payment_order_instance(
     payment_order: models.PaymentOrder | None,
     payment_order_id: int | None,

business/tasks.py

@@ -42,3 +42,41 @@ def create_sales_order_stock_entries(
     payload['task_id'] = self.request.id
     return payload
 
+
+@shared_task(bind=True)
+def create_purchase_return_order_stock_entries(
+    self,
+    *,
+    purchase_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    payload = business_services.create_purchase_return_order_stock_entries_sync(
+        purchase_return_order_id=purchase_return_order_id,
+        warehouse_id=warehouse_id,
+        items=items,
+        created_by_id=created_by_id,
+    )
+    payload['task_id'] = self.request.id
+    return payload
+
+
+@shared_task(bind=True)
+def create_sales_return_order_stock_entries(
+    self,
+    *,
+    sales_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    payload = business_services.create_sales_return_order_stock_entries_sync(
+        sales_return_order_id=sales_return_order_id,
+        warehouse_id=warehouse_id,
+        items=items,
+        created_by_id=created_by_id,
+    )
+    payload['task_id'] = self.request.id
+    return payload
+

business/tests.py

@@ -437,6 +437,202 @@ class SalesOrderServiceTestCase(TestCase):
                 created_by=self.user,
             )
 
+
+class PurchaseReturnServiceTestCase(TestCase):
+    def setUp(self):
+        (
+            self.merchant,
+            self.supplier,
+            self.warehouse_strict,
+            self.warehouse_relaxed,
+            self.product,
+            self.operator,
+        ) = create_basic_fixtures()
+        self.warehouse_strict_out = basic_models.WareHouse.objects.create(
+            merchant=self.merchant,
+            name='采退严出仓',
+            mode=basic_models.WareHouseModeEnum.RESTRICT_IN_OUT,
+        )
+        User = get_user_model()
+        self.user = User.objects.create_user(username='purchase-return', password='pass123')
+        self.strict_items = [
+            {'product_id': self.product.id, 'numbers': [4, 2], 'price': '11.5', 'unit': '米'}
+        ]
+        self.strict_out_items = [
+            {
+                'product_id': self.product.id,
+                'consume_detail_ids': [10, 11],
+                'quantity': 30,
+                'price': '12.0',
+                'unit': '米',
+            }
+        ]
+
+    def test_create_purchase_return_order_success(self):
+        order = services.create_purchase_return_order(
+            merchant=self.merchant,
+            supplier=self.supplier,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_strict,
+            operator=self.operator,
+            items=self.strict_items,
+            created_by=self.user,
+        )
+        self.assertEqual(order.status, business_models.PurchaseReturnStatusEnum.PENDING)
+        self.assertEqual(order.items.count(), 1)
+
+    def test_review_purchase_return_order_triggers_task_and_balance(self):
+        order = services.create_purchase_return_order(
+            merchant=self.merchant,
+            supplier=self.supplier,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 40, 'num_of_rolls': 2, 'price': '10.0'}],
+            created_by=self.user,
+        )
+        with patch('business.services.create_purchase_return_order_stock_entries.delay') as mock_delay:
+            reviewed = services.review_purchase_return_order(
+                purchase_return_order=order,
+                target_status=business_models.PurchaseReturnStatusEnum.APPROVED,
+                reviewed_by=self.user,
+            )
+        self.assertEqual(reviewed.status, business_models.PurchaseReturnStatusEnum.APPROVED)
+        mock_delay.assert_called_once()
+        balance = business_models.SupplierBalance.objects.get(
+            merchant=self.merchant,
+            supplier=self.supplier,
+        )
+        self.assertEqual(balance.balance, Decimal('-400.00'))
+        record = business_models.BalanceChangeRecord.objects.get(
+            merchant=self.merchant,
+            source_type=business_models.BalanceChangeSourceEnum.PURCHASE_RETURN_ORDER,
+            source_id=order.id,
+        )
+        self.assertEqual(record.direction, business_models.BalanceChangeDirectionEnum.DECREASE)
+
+    def test_purchase_return_cancel_blocked_after_stock_created(self):
+        order = services.create_purchase_return_order(
+            merchant=self.merchant,
+            supplier=self.supplier,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 20, 'num_of_rolls': 2, 'price': '9.5'}],
+        )
+        stock_models.StockChangeRecord.objects.create(
+            merchant=self.merchant,
+            type=stock_models.StockChangeTypeEnum.REMOVE,
+            warehouse=self.warehouse_relaxed,
+            source_type=stock_models.StockChangeSourceEnum.PURCHASE_RETURN,
+            source_id=order.id,
+        )
+        with self.assertRaises(ValueError):
+            services.review_purchase_return_order(
+                purchase_return_order=order,
+                target_status=business_models.PurchaseReturnStatusEnum.CANCELLED,
+            )
+
+    def test_purchase_return_strict_out_requires_consume_ids(self):
+        payload = [
+            {
+                'product_id': self.product.id,
+                'quantity': 10,
+                'price': '8.5',
+                'unit': '米',
+            }
+        ]
+        with self.assertRaises(ValueError):
+            services.create_purchase_return_order(
+                merchant=self.merchant,
+                supplier=self.supplier,
+                return_date=timezone.now().date(),
+                warehouse=self.warehouse_strict_out,
+                operator=self.operator,
+                items=payload,
+            )
+
+
+class SalesReturnServiceTestCase(TestCase):
+    def setUp(self):
+        (
+            self.merchant,
+            self.customer,
+            self.warehouse_strict,
+            self.warehouse_relaxed,
+            self.warehouse_strict_out,
+            self.product,
+            self.operator,
+        ) = create_sales_fixtures()
+        User = get_user_model()
+        self.user = User.objects.create_user(username='sales-return', password='pass123')
+        self.strict_items = [
+            {'product_id': self.product.id, 'numbers': [6, 2], 'price': '20.0', 'unit': '米'}
+        ]
+
+    def test_create_sales_return_order_success(self):
+        order = services.create_sales_return_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 50, 'num_of_rolls': 2, 'price': '19.5'}],
+        )
+        self.assertEqual(order.status, business_models.SalesReturnStatusEnum.PENDING)
+
+    def test_review_sales_return_order_updates_balance(self):
+        order = services.create_sales_return_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_strict,
+            operator=self.operator,
+            items=self.strict_items,
+            created_by=self.user,
+        )
+        with patch('business.services.create_sales_return_order_stock_entries.delay') as mock_delay:
+            reviewed = services.review_sales_return_order(
+                sales_return_order=order,
+                target_status=business_models.SalesReturnStatusEnum.APPROVED,
+                reviewed_by=self.user,
+            )
+        self.assertEqual(reviewed.status, business_models.SalesReturnStatusEnum.APPROVED)
+        mock_delay.assert_called_once()
+        balance = business_models.CustomerBalance.objects.get(
+            merchant=self.merchant,
+            customer=self.customer,
+        )
+        self.assertLess(balance.balance, Decimal('0'))
+        record = business_models.BalanceChangeRecord.objects.get(
+            merchant=self.merchant,
+            source_type=business_models.BalanceChangeSourceEnum.SALES_RETURN_ORDER,
+            source_id=order.id,
+        )
+        self.assertEqual(record.direction, business_models.BalanceChangeDirectionEnum.DECREASE)
+
+    def test_sales_return_cancel_blocked_after_stock_created(self):
+        order = services.create_sales_return_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 15, 'num_of_rolls': 1, 'price': '18.0'}],
+        )
+        stock_models.StockChangeRecord.objects.create(
+            merchant=self.merchant,
+            type=stock_models.StockChangeTypeEnum.ADD,
+            warehouse=self.warehouse_relaxed,
+            source_type=stock_models.StockChangeSourceEnum.SALES_RETURN,
+            source_id=order.id,
+        )
+        with self.assertRaises(ValueError):
+            services.review_sales_return_order(
+                sales_return_order=order,
+                target_status=business_models.SalesReturnStatusEnum.CANCELLED,
+            )
+
 class PaymentReceiptServiceTestCase(TestCase):
     def setUp(self):
         (

docs/business_api_reference.md

@@ -21,7 +21,7 @@
 
 ---
 
-## 2. 采购单（PurchaseOrder）
+## 2. 采购相关：采购单 + 采购退货单
 
 | API | 方法 | 描述 |
 |-----|------|------|
@@ -59,9 +59,21 @@
 
 成功返回最新的采购单序列化（含 `items`、`total_amount`、`status_name` 等）。
 
+### 2.3 采购退货单（PurchaseReturnOrder）
+
+| API | 方法 | 描述 |
+|-----|------|------|
+| `/purchase-return-orders/` | GET/POST | 与采购单相同的查询/创建接口，字段改为 `return_date`。 |
+| `/purchase-return-orders/<id>/review/` | POST | 审批或作废，流程与采购单一致。 |
+
+- **创建字段**：`supplier`、`warehouse`、`return_date`、`items`、可选 `purchase_order`。`items` 结构沿用采购单；当仓库 `mode=RESTRICT_IN_OUT` 时必须提供 `consume_detail_ids`，指明要冲销的入库明细。
+- **审批逻辑**：
+  - `approve`：在事务内锁单、构建 `stock_flow_items`，状态置为 `APPROVED`，调用 `StockFlowService.stock_out`（source=`PURCHASE_RETURN`），并向 `BalanceService` 写入 **负值** 以减少供应商应付。
+  - `cancel`：仅允许 `PENDING` 且尚未生成 `StockChangeRecord` 的单据；审批完成后禁止作废。
+
 ---
 
-## 3. 销售单（SalesOrder）
+## 3. 销售相关：销售单 + 销售退货单
 
 | API | 方法 | 描述 |
 |-----|------|------|
@@ -107,6 +119,18 @@
 - `approve`：写入客户余额（正向欠款），若商户配置自动出库则触发 `create_sales_order_stock_entries`。
 - `cancel`：如果已存在 `StockChangeRecord`（source=`SALES`）则拒绝。
 
+### 3.3 销售退货单（SalesReturnOrder）
+
+| API | 方法 | 描述 |
+|-----|------|------|
+| `/sales-return-orders/` | GET/POST | 创建 / 列表接口。 |
+| `/sales-return-orders/<id>/review/` | POST | 审批或作废。 |
+
+- **创建字段**：`customer`、`warehouse`、`return_date`、`items`、可选 `sales_order`。因退货为入库动作，严出仓不再需要 `consume_detail_ids`。
+- **审批逻辑**：
+  - `approve`：状态置为 `APPROVED`，调用 `StockFlowService.stock_in`（source=`SALES_RETURN`），并向 `BalanceService` 写入 **负值** 以冲减客户欠款，同时写 `BalanceChangeRecord`。
+  - `cancel`：仅允许 `PENDING` 且未生成 `StockChangeRecord` 的单据；审批通过后不可作废。
+
 ---
 
 ## 4. 付款单（PaymentOrder）

docs/payment_receipt_workflow.md

@@ -34,4 +34,4 @@
 ## 5. 与采购/销售单的关系
 - 继承相同的方向抽象（`get_direction()`），可与采购/销售的金额统计组合成统一的应收/应付报表。
 - 不触发库存任务，也没有 `items`、仓库等字段；扩展字段（如付款方式、附件）可在此基础上继续添加。
-
+- 采购退货 / 销售退货等复合单据在审批时会**同时**触发库存与余额写入，可视为采购/销售单 + 资金单据的组合；资金类单据仍需保持独立，以便单独统计资金流水。

docs/purchase_order_approval_and_red_flush.md

@@ -45,7 +45,23 @@
 - 作废时已有出入库记录：`ValueError('采购单已生成出入库记录，无法作废')` -> API 返回 `400`。
 - ID 不存在或不属于当前商户：API 返回 `404`。
 
-## 6. 下一阶段：库存红冲（对冲）方案规划
+## 6. 采购退货（采退）流程补充
+
+- API：`POST /api/v1/purchase-return-orders/` 创建，`POST /api/v1/purchase-return-orders/<id>/review/` 审批。
+- 创建阶段与采购单一致，只是字段改为 `return_date`，并允许传入 `purchase_order` 以关联原单。
+- 审批通过：
+  1. 在事务内锁单、生成 `stock_flow_items`。
+  2. 状态置为 `APPROVED`。
+  3. 调用 `BalanceService.adjust_supplier_balance(delta=-总金额，source=PURCHASE_RETURN_ORDER)`，写入 `BalanceChangeRecord`。
+  4. 触发 `create_purchase_return_order_stock_entries`，底层调用 `StockFlowService.stock_out`（source=`PURCHASE_RETURN`），受仓库 mode 约束：
+     - 宽进仓：传递 `value + num_of_rolls`
+     - 严进仓：传递 `numbers`
+     - 严进严出：必须提供 `consume_detail_ids`
+- 作废逻辑沿用采购单：只有 `PENDING` 且未产生 `StockChangeRecord` 时才允许取消，一旦审批成功便禁止。
+
+---
+
+## 7. 下一阶段：库存红冲（对冲）方案规划
 
 ### 6.1 目标与原则
 

docs/sales_order_approval_and_red_flush.md

@@ -43,7 +43,20 @@
 - 作废时已有出库记录：`ValueError('销售单已生成出入库记录，无法作废')` -> `400`。
 - ID 不存在或不属于当前商户：`404`。
 
-## 6. 创建接口参数约定
+## 6. 销售退货（销退）流程补充
+
+- API：`/api/v1/sales-return-orders/`（创建、列表）与 `/review/` 审批接口，与销售单保持完全一致的认证/权限。
+- 创建时字段改为 `return_date`，其余 `items` 结构与销售单一致（根据仓库 mode 填写 `numbers` 或 `quantity` / `num_of_rolls`）。严进严出仓在退货场景下视为“入库”，故无需 `consume_detail_ids`。
+- 审批通过：
+  1. 事务锁定单据与明细。
+  2. 状态置为 `APPROVED`。
+  3. 调用 `BalanceService.adjust_customer_balance(delta=-total_amount, source=SALES_RETURN_ORDER)`，写 `BalanceChangeRecord`，减少客户欠款。
+  4. 根据商户设置触发 `create_sales_return_order_stock_entries`，底层走 `StockFlowService.stock_in`（source=`SALES_RETURN`）。
+- 作废：同销售单，只允许 `PENDING` 且未生成 `StockChangeRecord` 的单据作废；审批后不可逆。
+
+---
+
+## 7. 创建接口参数约定
 
 销售单创建接口沿用采购单的参数格式，根据仓库模式填写 `items`：
 
@@ -55,7 +68,7 @@
 
 > 说明：在严出模式下，`consume_detail_ids` 列表中的 ID 必须为同仓库、同商户且未被消耗的入库明细 ID。系统会在审批通过时逐条扣减对应库存。
 
-## 6. 红冲（对冲）规划
+## 8. 红冲（对冲）规划
 
 与采购单一致，后续将通过库存红冲入口（`StockFlowService.offset_stock_change` 占位方法）实现销售单出库的反向抵销。关键原则：