From fae33809aca8daf3ebf258459100bbe5d5da0b73 Mon Sep 17 00:00:00 2001 From: colaftc Date: Mon, 1 Dec 2025 16:52:59 +0800 Subject: [PATCH] feat: sales return order and purchase return order --- api_v1/tests.py | 236 ++++++++++ api_v1/urls.py | 6 + .../business/purchase_return/__init__.py | 2 + .../views/business/purchase_return/views.py | 181 ++++++++ .../views/business/sales_return/__init__.py | 2 + api_v1/views/business/sales_return/views.py | 180 ++++++++ business/ARCHITECTURE.md | 2 + business/admin.py | 76 +++ ...alancechangerecord_source_type_and_more.py | 113 +++++ business/models.py | 220 +++++++++ business/services.py | 434 ++++++++++++++++++ business/tasks.py | 38 ++ business/tests.py | 196 ++++++++ docs/business_api_reference.md | 28 +- docs/payment_receipt_workflow.md | 2 +- docs/purchase_order_approval_and_red_flush.md | 18 +- docs/sales_order_approval_and_red_flush.md | 17 +- 17 files changed, 1745 insertions(+), 6 deletions(-) create mode 100644 api_v1/views/business/purchase_return/__init__.py create mode 100644 api_v1/views/business/purchase_return/views.py create mode 100644 api_v1/views/business/sales_return/__init__.py create mode 100644 api_v1/views/business/sales_return/views.py create mode 100644 business/migrations/0014_alter_balancechangerecord_source_type_and_more.py diff --git a/api_v1/tests.py b/api_v1/tests.py index 6b5a16a..484dd3f 100644 --- a/api_v1/tests.py +++ b/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) diff --git a/api_v1/urls.py b/api_v1/urls.py index 04fdce7..9c6b6b7 100644 --- a/api_v1/urls.py +++ b/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//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//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//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//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//review/', payment_views.PaymentOrderReviewView.as_view(), name='payment_order_review'), path('receipt-orders/', receipt_views.ReceiptOrderView.as_view(), name='receipt_orders'), diff --git a/api_v1/views/business/purchase_return/__init__.py b/api_v1/views/business/purchase_return/__init__.py new file mode 100644 index 0000000..139597f --- /dev/null +++ b/api_v1/views/business/purchase_return/__init__.py @@ -0,0 +1,2 @@ + + diff --git a/api_v1/views/business/purchase_return/views.py b/api_v1/views/business/purchase_return/views.py new file mode 100644 index 0000000..62b7381 --- /dev/null +++ b/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) + diff --git a/api_v1/views/business/sales_return/__init__.py b/api_v1/views/business/sales_return/__init__.py new file mode 100644 index 0000000..139597f --- /dev/null +++ b/api_v1/views/business/sales_return/__init__.py @@ -0,0 +1,2 @@ + + diff --git a/api_v1/views/business/sales_return/views.py b/api_v1/views/business/sales_return/views.py new file mode 100644 index 0000000..33ca63b --- /dev/null +++ b/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) + diff --git a/business/ARCHITECTURE.md b/business/ARCHITECTURE.md index c3647dd..c4ddb92 100644 --- a/business/ARCHITECTURE.md +++ b/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**：实时维护供应商应付、客户应收余额，所有审批通过的带金额单据都会写入，供查询接口和报表使用。 diff --git a/business/admin.py b/business/admin.py index 49be32c..da0e21f 100644 --- a/business/admin.py +++ b/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') diff --git a/business/migrations/0014_alter_balancechangerecord_source_type_and_more.py b/business/migrations/0014_alter_balancechangerecord_source_type_and_more.py new file mode 100644 index 0000000..c0d28ca --- /dev/null +++ b/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': '销售退货明细', + }, + ), + ] diff --git a/business/models.py b/business/models.py index b63cef4..18c10e8 100644 --- a/business/models.py +++ b/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): diff --git a/business/services.py b/business/services.py index bc6118e..405a903 100644 --- a/business/services.py +++ b/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, diff --git a/business/tasks.py b/business/tasks.py index 3447969..4c76df3 100644 --- a/business/tasks.py +++ b/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 + diff --git a/business/tests.py b/business/tests.py index 4774ed4..e502284 100644 --- a/business/tests.py +++ b/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): ( diff --git a/docs/business_api_reference.md b/docs/business_api_reference.md index 5bd0b48..fd7b679 100644 --- a/docs/business_api_reference.md +++ b/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//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//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） diff --git a/docs/payment_receipt_workflow.md b/docs/payment_receipt_workflow.md index 1d6ce0a..4144fa2 100644 --- a/docs/payment_receipt_workflow.md +++ b/docs/payment_receipt_workflow.md @@ -34,4 +34,4 @@ ## 5. 与采购/销售单的关系 - 继承相同的方向抽象（`get_direction()`），可与采购/销售的金额统计组合成统一的应收/应付报表。 - 不触发库存任务，也没有 `items`、仓库等字段；扩展字段（如付款方式、附件）可在此基础上继续添加。 - +- 采购退货 / 销售退货等复合单据在审批时会**同时**触发库存与余额写入，可视为采购/销售单 + 资金单据的组合；资金类单据仍需保持独立，以便单独统计资金流水。 diff --git a/docs/purchase_order_approval_and_red_flush.md b/docs/purchase_order_approval_and_red_flush.md index 5dfa21e..4e7141f 100644 --- a/docs/purchase_order_approval_and_red_flush.md +++ b/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//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 目标与原则 diff --git a/docs/sales_order_approval_and_red_flush.md b/docs/sales_order_approval_and_red_flush.md index bf6c861..5e10bd5 100644 --- a/docs/sales_order_approval_and_red_flush.md +++ b/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` 占位方法）实现销售单出库的反向抵销。关键原则：