UPDATE

irrigation/views.py

@@ -1,12 +1,15 @@
-from drf_spectacular.utils import (
-    OpenApiExample,
-    OpenApiResponse,
-    extend_schema,
-)
+from drf_spectacular.utils import OpenApiExample, extend_schema
 from rest_framework import status
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
+from config.openapi import (
+    build_envelope_serializer,
+    build_response,
+    build_task_queue_data_serializer,
+    build_task_status_data_serializer,
+)
+
 from .models import IrrigationMethod
 from .serializers import (
     IrrigationMethodSerializer,
@@ -14,6 +17,30 @@ from .serializers import (
 )
 
 
+IrrigationMethodListResponseSerializer = build_envelope_serializer(
+    "IrrigationMethodListResponseSerializer",
+    IrrigationMethodSerializer,
+    many=True,
+)
+IrrigationMethodDetailResponseSerializer = build_envelope_serializer(
+    "IrrigationMethodDetailResponseSerializer",
+    IrrigationMethodSerializer,
+)
+IrrigationValidationErrorSerializer = build_envelope_serializer(
+    "IrrigationValidationErrorSerializer",
+    data_required=False,
+    allow_null=True,
+)
+IrrigationQueueResponseSerializer = build_envelope_serializer(
+    "IrrigationQueueResponseSerializer",
+    build_task_queue_data_serializer("IrrigationQueueDataSerializer"),
+)
+IrrigationStatusResponseSerializer = build_envelope_serializer(
+    "IrrigationStatusResponseSerializer",
+    build_task_status_data_serializer("IrrigationStatusDataSerializer"),
+)
+
+
 class IrrigationMethodListCreateView(APIView):
     """لیست تمام روش‌های آبیاری و ایجاد روش جدید."""
 
@@ -21,7 +48,12 @@ class IrrigationMethodListCreateView(APIView):
         tags=["Irrigation"],
         summary="لیست روش‌های آبیاری",
         description="لیست تمام روش‌های آبیاری ذخیره‌شده را برمی‌گرداند.",
-        responses={200: IrrigationMethodSerializer(many=True)},
+        responses={
+            200: build_response(
+                IrrigationMethodListResponseSerializer,
+                "لیست روش‌های آبیاری ذخیره‌شده.",
+            ),
+        },
     )
     def get(self, request):
         methods = IrrigationMethod.objects.all()
@@ -31,6 +63,52 @@ class IrrigationMethodListCreateView(APIView):
             status=status.HTTP_200_OK,
         )
 
+    @extend_schema(
+        tags=["Irrigation"],
+        summary="ایجاد روش آبیاری جدید",
+        description="یک روش آبیاری جدید ایجاد می‌کند.",
+        request=IrrigationMethodSerializer,
+        responses={
+            201: build_response(
+                IrrigationMethodDetailResponseSerializer,
+                "روش آبیاری جدید با موفقیت ایجاد شد.",
+            ),
+            400: build_response(
+                IrrigationValidationErrorSerializer,
+                "داده ورودی نامعتبر است.",
+            ),
+        },
+        examples=[
+            OpenApiExample(
+                "نمونه درخواست",
+                value={
+                    "name": "آبیاری قطره‌ای",
+                    "category": "موضعی",
+                    "description": "آبیاری با دبی کم و فشار مناسب",
+                    "water_efficiency_percent": 90.0,
+                    "water_pressure_required": "۱-۲ اتمسفر",
+                    "flow_rate": "۲-۸ لیتر در ساعت",
+                    "coverage_area": "بسته به طراحی سیستم",
+                    "soil_type": "تمام انواع خاک",
+                    "climate_suitability": "گرم و خشک",
+                },
+                request_only=True,
+            ),
+        ],
+    )
+    def post(self, request):
+        serializer = IrrigationMethodSerializer(data=request.data)
+        if not serializer.is_valid():
+            return Response(
+                {"code": 400, "msg": "داده نامعتبر.", "data": serializer.errors},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        serializer.save()
+        return Response(
+            {"code": 201, "msg": "success", "data": serializer.data},
+            status=status.HTTP_201_CREATED,
+        )
+
 
 class IrrigationRecommendView(APIView):
     """
@@ -50,8 +128,14 @@ class IrrigationRecommendView(APIView):
         ),
         request=IrrigationRecommendRequestSerializer,
         responses={
-            202: OpenApiResponse(description="تسک در صف قرار گرفت"),
-            400: OpenApiResponse(description="پارامتر ورودی نامعتبر"),
+            202: build_response(
+                IrrigationQueueResponseSerializer,
+                "تسک توصیه آبیاری در صف قرار گرفت.",
+            ),
+            400: build_response(
+                IrrigationValidationErrorSerializer,
+                "پارامتر ورودی نامعتبر است.",
+            ),
         },
         examples=[
             OpenApiExample(
@@ -111,7 +195,10 @@ class IrrigationRecommendStatusView(APIView):
         summary="وضعیت تسک توصیه آبیاری",
         description="وضعیت تسک Celery توصیه آبیاری را برمی‌گرداند.",
         responses={
-            200: OpenApiResponse(description="وضعیت تسک"),
+            200: build_response(
+                IrrigationStatusResponseSerializer,
+                "وضعیت فعلی تسک توصیه آبیاری.",
+            ),
         },
     )
     def get(self, request, task_id):
@@ -132,46 +219,6 @@ class IrrigationRecommendStatusView(APIView):
             status=status.HTTP_200_OK,
         )
 
-    @extend_schema(
-        tags=["Irrigation"],
-        summary="ایجاد روش آبیاری جدید",
-        description="یک روش آبیاری جدید ایجاد می‌کند.",
-        request=IrrigationMethodSerializer,
-        responses={
-            201: IrrigationMethodSerializer,
-            400: OpenApiResponse(description="داده نامعتبر"),
-        },
-        examples=[
-            OpenApiExample(
-                "نمونه درخواست",
-                value={
-                    "name": "آبیاری قطره‌ای",
-                    "category": "موضعی",
-                    "description": "آبیاری با دبی کم و فشار مناسب",
-                    "water_efficiency_percent": 90.0,
-                    "water_pressure_required": "۱-۲ اتمسفر",
-                    "flow_rate": "۲-۸ لیتر در ساعت",
-                    "coverage_area": "بسته به طراحی سیستم",
-                    "soil_type": "تمام انواع خاک",
-                    "climate_suitability": "گرم و خشک",
-                },
-                request_only=True,
-            ),
-        ],
-    )
-    def post(self, request):
-        serializer = IrrigationMethodSerializer(data=request.data)
-        if not serializer.is_valid():
-            return Response(
-                {"code": 400, "msg": "داده نامعتبر.", "data": serializer.errors},
-                status=status.HTTP_400_BAD_REQUEST,
-            )
-        serializer.save()
-        return Response(
-            {"code": 201, "msg": "success", "data": serializer.data},
-            status=status.HTTP_201_CREATED,
-        )
-
 
 class IrrigationMethodDetailView(APIView):
     """دریافت، ویرایش و حذف یک روش آبیاری."""
@@ -184,8 +231,14 @@ class IrrigationMethodDetailView(APIView):
         summary="جزئیات روش آبیاری",
         description="مشخصات یک روش آبیاری را بر اساس شناسه برمی‌گرداند.",
         responses={
-            200: IrrigationMethodSerializer,
-            404: OpenApiResponse(description="روش آبیاری یافت نشد"),
+            200: build_response(
+                IrrigationMethodDetailResponseSerializer,
+                "جزئیات روش آبیاری.",
+            ),
+            404: build_response(
+                IrrigationValidationErrorSerializer,
+                "روش آبیاری یافت نشد.",
+            ),
         },
     )
     def get(self, request, pk):
@@ -207,9 +260,18 @@ class IrrigationMethodDetailView(APIView):
         description="تمام فیلدهای یک روش آبیاری را آپدیت می‌کند.",
         request=IrrigationMethodSerializer,
         responses={
-            200: IrrigationMethodSerializer,
-            400: OpenApiResponse(description="داده نامعتبر"),
-            404: OpenApiResponse(description="روش آبیاری یافت نشد"),
+            200: build_response(
+                IrrigationMethodDetailResponseSerializer,
+                "روش آبیاری با موفقیت به‌روزرسانی شد.",
+            ),
+            400: build_response(
+                IrrigationValidationErrorSerializer,
+                "داده ورودی نامعتبر است.",
+            ),
+            404: build_response(
+                IrrigationValidationErrorSerializer,
+                "روش آبیاری یافت نشد.",
+            ),
         },
     )
     def put(self, request, pk):
@@ -237,9 +299,18 @@ class IrrigationMethodDetailView(APIView):
         description="فقط فیلدهای ارسال‌شده آپدیت می‌شوند.",
         request=IrrigationMethodSerializer,
         responses={
-            200: IrrigationMethodSerializer,
-            400: OpenApiResponse(description="داده نامعتبر"),
-            404: OpenApiResponse(description="روش آبیاری یافت نشد"),
+            200: build_response(
+                IrrigationMethodDetailResponseSerializer,
+                "روش آبیاری با موفقیت به‌روزرسانی شد.",
+            ),
+            400: build_response(
+                IrrigationValidationErrorSerializer,
+                "داده ورودی نامعتبر است.",
+            ),
+            404: build_response(
+                IrrigationValidationErrorSerializer,
+                "روش آبیاری یافت نشد.",
+            ),
         },
     )
     def patch(self, request, pk):
@@ -266,8 +337,14 @@ class IrrigationMethodDetailView(APIView):
         summary="حذف روش آبیاری",
         description="یک روش آبیاری را حذف می‌کند.",
         responses={
-            200: OpenApiResponse(description="حذف موفق"),
-            404: OpenApiResponse(description="روش آبیاری یافت نشد"),
+            200: build_response(
+                IrrigationValidationErrorSerializer,
+                "روش آبیاری با موفقیت حذف شد.",
+            ),
+            404: build_response(
+                IrrigationValidationErrorSerializer,
+                "روش آبیاری یافت نشد.",
+            ),
         },
     )
     def delete(self, request, pk):