feat: balance api

api_v1/tests.py

@@ -22,7 +22,7 @@ from basic_info.models import (
     WareHouse,
     WareHouseModeEnum,
 )
-from business import models as business_models
+from business import models as business_models, services
 from stock import models as stock_models
 from api_v1 import tasks
 
@@ -494,8 +494,7 @@ class PaymentOrderAPITestCase(TestCase):
             {'action': 'cancel'},
             format='json',
         )
-        self.assertEqual(response_cancel.status_code, status.HTTP_200_OK)
-        self.assertEqual(response_cancel.data['status'], business_models.PaymentOrderStatusEnum.CANCELLED)
+        self.assertEqual(response_cancel.status_code, status.HTTP_400_BAD_REQUEST)
 
     def test_payment_order_requires_amount(self):
         payload = {**self.payload}
@@ -569,6 +568,81 @@ class ReceiptOrderAPITestCase(TestCase):
         response = self.client.post('/api/v1/receipt-orders/', payload, format='json')
         self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
         self.assertIn('amount 必须大于 0', response.data['error'])
+
+
+class CustomerBalanceAPITestCase(TestCase):
+    def setUp(self):
+        self.merchant = Merchant.objects.create(name='余额商户', type=MerchantTypeEnum.FACTORY)
+        self.customer = Customer.objects.create(
+            merchant=self.merchant,
+            name='余额客户',
+            mobile='13800000000',
+            created_by=None,
+        )
+        self.user = User.objects.create_user(username='balance_user', password='pass123')
+        self.employee = Employee.objects.create(
+            merchant=self.merchant,
+            sys_user=self.user,
+            name='财务查询',
+            status=EmployeeStatusEnum.ACTIVE,
+        )
+        self.client = APIClient()
+        self.client.force_authenticate(user=self.user)
+
+    def test_customer_balance_defaults_to_zero(self):
+        response = self.client.get(f'/api/v1/customers/{self.customer.id}/balance/')
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data['balance'], '0')
+
+    def test_customer_balance_reflects_sales_and_receipts(self):
+        # 创建销售单
+        product_category = ProductCategory.objects.create(
+            merchant=self.merchant,
+            name='余额品类',
+            product_prefix='BAL',
+        )
+        product = Product.objects.create(
+            merchant=self.merchant,
+            category=product_category,
+            name='余额产品',
+            human_id='BAL-001',
+            unit=ProductUnitEnum.METER,
+        )
+        warehouse = WareHouse.objects.create(
+            merchant=self.merchant,
+            name='余额仓',
+            mode=WareHouseModeEnum.RESTRICT_IN,
+        )
+        order = services.create_sales_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            order_date='2025-11-26',
+            warehouse=warehouse,
+            operator=self.employee,
+            items=[{'product_id': product.id, 'numbers': [5], 'price': '10', 'unit': '米'}],
+        )
+        services.review_sales_order(
+            sales_order=order,
+            target_status=business_models.SalesOrderStatusEnum.APPROVED,
+            reviewed_by=self.user,
+        )
+        response = self.client.get(f'/api/v1/customers/{self.customer.id}/balance/')
+        self.assertEqual(response.data['balance'], '50.00')
+
+        receipt = services.create_receipt_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            receipt_date='2025-11-27',
+            amount='20',
+            operator=self.employee,
+        )
+        services.review_receipt_order(
+            receipt_order=receipt,
+            target_status=business_models.ReceiptOrderStatusEnum.APPROVED,
+            reviewed_by=self.user,
+        )
+        response = self.client.get(f'/api/v1/customers/{self.customer.id}/balance/')
+        self.assertEqual(response.data['balance'], '30.00')
 @override_settings(
     CELERY_TASK_ALWAYS_EAGER=True,
     CELERY_TASK_EAGER_PROPAGATES=True,