feat: added shipments list api

api_v1/views/shipment/views.py

@@ -5,6 +5,11 @@ from rest_framework import status
 from rest_framework.views import APIView
 from rest_framework.response import Response
 from rest_framework.permissions import IsAuthenticated
+from rest_framework.generics import GenericAPIView
+from rest_framework.mixins import ListModelMixin, RetrieveModelMixin
+
+from flower.viewsets import LimitedLimitOffsetPagination
+from shipment.models import Shipment
 
 from .serializers import (
     SalesItemSerializer,
@@ -14,11 +19,12 @@ from .serializers import (
 )
 
 
-class ShipmentCreateView(APIView):
+class ShipmentListCreateView(ListModelMixin, GenericAPIView):
     """
-    创建出货单
+    出货单：查询列表 / 创建
     
-    POST /api/v1/shipment/shipments/
+    - GET /api/v1/shipment/shipments/
+    - POST /api/v1/shipment/shipments/
     
     请求体:
     {
@@ -43,6 +49,61 @@ class ShipmentCreateView(APIView):
     }
     """
     permission_classes = [IsAuthenticated]
+    serializer_class = ShipmentSerializer
+    pagination_class = LimitedLimitOffsetPagination
+
+    def get_queryset(self):
+        """
+        仅返回当前用户所属商户的出货单（merchant 隔离）。
+
+        支持过滤参数（可选）：
+        - customer: 客户ID
+        - status: 状态（1/2/3）
+        - external_id: 外部订单号（精确匹配）
+        - shipment_date_from: 出货日期起始（YYYY-MM-DD）
+        - shipment_date_to: 出货日期结束（YYYY-MM-DD，包含整天）
+        """
+        qs = Shipment.objects.all().select_related(
+            'merchant', 'customer', 'created_by', 'cancelled_by'
+        ).prefetch_related(
+            'items',
+            'external_finished_products',
+        )
+
+        user = self.request.user
+        if not getattr(user, 'is_superuser', False):
+            emp = getattr(user, 'employee', None)
+            merchant = getattr(emp, 'merchant', None) if emp else None
+            if not merchant:
+                return Shipment.objects.none()
+            qs = qs.filter(merchant=merchant)
+
+        # optional filters
+        customer_id = self.request.query_params.get('customer')
+        if customer_id:
+            qs = qs.filter(customer_id=customer_id)
+
+        status_val = self.request.query_params.get('status')
+        if status_val:
+            qs = qs.filter(status=status_val)
+
+        external_id = self.request.query_params.get('external_id')
+        if external_id:
+            qs = qs.filter(external_id=external_id)
+
+        date_from = self.request.query_params.get('shipment_date_from')
+        if date_from:
+            qs = qs.filter(shipment_date__gte=date_from)
+
+        date_to = self.request.query_params.get('shipment_date_to')
+        if date_to:
+            # 通过 <= 过滤日期
+            qs = qs.filter(shipment_date__lte=date_to)
+
+        return qs.order_by('-created_at', '-id')
+
+    def get(self, request):
+        return self.list(request)
     
     def post(self, request):
         # 验证请求数据
@@ -70,6 +131,37 @@ class ShipmentCreateView(APIView):
         return Response(response_serializer.data, status=status.HTTP_201_CREATED)
 
 
+class ShipmentDetailView(RetrieveModelMixin, GenericAPIView):
+    """
+    出货单详情
+
+    GET /api/v1/shipment/shipments/<id>/
+    """
+    permission_classes = [IsAuthenticated]
+    serializer_class = ShipmentSerializer
+
+    def get_queryset(self):
+        qs = Shipment.objects.all().select_related(
+            'merchant', 'customer', 'created_by', 'cancelled_by'
+        ).prefetch_related(
+            'items',
+            'external_finished_products',
+        )
+
+        user = self.request.user
+        if getattr(user, 'is_superuser', False):
+            return qs
+
+        emp = getattr(user, 'employee', None)
+        merchant = getattr(emp, 'merchant', None) if emp else None
+        if not merchant:
+            return Shipment.objects.none()
+        return qs.filter(merchant=merchant)
+
+    def get(self, request, pk: int):
+        return self.retrieve(request, pk=pk)
+
+
 class ShipmentExternalCreateView(APIView):
     """
     创建出货单（external 版）