UPDATE

Modules/Backend/pest_detection/__init__.py

@@ -0,0 +1 @@
+

Modules/Backend/pest_detection/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class PestDetectionConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "pest_detection"
+    verbose_name = "Pest Detection"

Modules/Backend/pest_detection/mock_data.py

@@ -0,0 +1,54 @@
+"""
+Static mock data for Pest Detection API.
+No database, no dynamic values. Used for analyze and risk-summary endpoint responses.
+"""
+
+ANALYZE_RESPONSE_DATA = {
+    "pest": "شپشک",
+    "confidence": 92,
+    "description": "حشرات کوچک مکنده شیره که باعث پیچ خوردگی برگ می‌شوند.",
+    "treatment": "یک بار در هفته از اسپری روغن نیم استفاده کنید.",
+}
+
+RISK_SUMMARY_RESPONSE_DATA = {
+    "disease_risk": {
+        "id": "disease_risk",
+        "title": "ریسک بیماری",
+        "subtitle": "۷ روز اخیر",
+        "stats": "پایین",
+        "avatarColor": "success",
+        "avatarIcon": "tabler-bug",
+        "chipText": "5%",
+        "chipColor": "success",
+        "details": {
+            "risk_level": "low",
+            "risk_percentage": 5,
+            "detected_diseases": [],
+            "last_assessed_at": "2025-07-10T06:00:00Z",
+            "recommendation": "شرایط فعلی مناسب است. پایش هفتگی توصیه می‌شود.",
+        },
+    },
+    "pest_risk": {
+        "id": "pest_risk",
+        "title": "ریسک آفات",
+        "subtitle": "پیش‌بینی هوشمند",
+        "stats": "15%",
+        "avatarColor": "warning",
+        "avatarIcon": "tabler-bug-off",
+        "chipText": "تحت نظر",
+        "chipColor": "warning",
+        "details": {
+            "risk_level": "moderate",
+            "risk_percentage": 15,
+            "detected_pests": [
+                {
+                    "name": "شپشک",
+                    "confidence": 0.72,
+                    "affected_area_percent": 8,
+                }
+            ],
+            "last_assessed_at": "2025-07-10T06:00:00Z",
+            "recommendation": "بازرسی مزرعه هر ۳ روز یک بار انجام شود. در صورت افزایش، اسپری روغن نیم توصیه می‌شود.",
+        },
+    },
+}

Modules/Backend/pest_detection/pest_disease_urls.py

@@ -0,0 +1,9 @@
+from django.urls import path
+
+from .views import AnalyzeView, RiskSummaryView, RiskView
+
+urlpatterns = [
+    path("detect/", AnalyzeView.as_view(), name="pest-disease-detect"),
+    path("risk/", RiskView.as_view(), name="pest-disease-risk"),
+    path("risk-summary/", RiskSummaryView.as_view(), name="pest-disease-risk-summary"),
+]

Modules/Backend/pest_detection/postman/pest_detection.json

@@ -0,0 +1 @@
+{"info":{"name":"Pest Detection","schema":"https://schema.getpostman.com/json/collection/v2.1.0/collection.json","description":"Pest Detection API. POST analyze (optional body). Returns static pest result. No database."},"item":[{"name":"Analyze image (POST)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{}"},"url":"{{baseUrl}}/api/pest-detection/analyze/","description":"POST with optional body (e.g. image reference). Returns static pest, confidence, description, treatment. Input not processed."},"response":[{"name":"Success","status":"OK","code":200,"body":"{\n  \"status\": \"success\",\n  \"data\": {\n    \"pest\": \"شپشک\",\n    \"confidence\": 92,\n    \"description\": \"حشرات کوچک مکنده شیره که باعث پیچ خوردگی برگ می‌شوند.\",\n    \"treatment\": \"یک بار در هفته از اسپری روغن نیم استفاده کنید.\"\n  }\n}"}]}],"variable":[{"key":"baseUrl","value":"http://localhost:8000"}]}

Modules/Backend/pest_detection/serializers.py

@@ -0,0 +1,82 @@
+from rest_framework import serializers
+
+
+class PestDetectionAnalyzeRequestSerializer(serializers.Serializer):
+    farm_uuid = serializers.UUIDField(required=True, help_text="UUID مزرعه برای تحلیل آفت/بیماری.")
+    sensor_uuid = serializers.UUIDField(required=False, help_text="UUID سنسور مرتبط در صورت وجود.")
+    plant_name = serializers.CharField(required=False, allow_blank=True, default="", help_text="نام گیاه یا محصول.")
+    query = serializers.CharField(required=False, allow_blank=True, default="", help_text="پرسش یا توضیح متنی کاربر.")
+    image_urls = serializers.ListField(
+        child=serializers.CharField(),
+        required=False,
+        default=list,
+    )
+    image = serializers.CharField(required=False, allow_blank=True, default="")
+    images = serializers.ListField(
+        child=serializers.CharField(),
+        required=False,
+        default=list,
+    )
+
+    def validate(self, attrs):
+        attrs["query"] = (attrs.get("query") or "").strip()
+        attrs["plant_name"] = (attrs.get("plant_name") or "").strip()
+        return attrs
+
+
+class PestDetectionAnalyzeResponseSerializer(serializers.Serializer):
+    has_issue = serializers.BooleanField(required=False)
+    category = serializers.CharField(required=False, allow_blank=True)
+    confidence = serializers.FloatField(required=False)
+    severity = serializers.CharField(required=False, allow_blank=True)
+    summary = serializers.CharField(required=False, allow_blank=True)
+    detected_signs = serializers.ListField(child=serializers.CharField(), required=False)
+    possible_causes = serializers.ListField(child=serializers.CharField(), required=False)
+    immediate_actions = serializers.ListField(child=serializers.CharField(), required=False)
+    reasoning = serializers.ListField(child=serializers.CharField(), required=False)
+
+
+class PestDetectionRiskRequestSerializer(serializers.Serializer):
+    farm_uuid = serializers.UUIDField(default="11111111-1111-1111-1111-111111111111", help_text="UUID مزرعه برای تحلیل ریسک آفت/بیماری.")
+    plant_name = serializers.CharField(required=False, allow_blank=True, default="پیاز", help_text="نام محصول یا گیاه.")
+    growth_stage = serializers.CharField(required=False, allow_blank=True, default="گلدهی", help_text="مرحله رشد گیاه.")
+
+
+class PestDetectionRiskSummaryRequestSerializer(serializers.Serializer):
+    farm_uuid = serializers.UUIDField(required=True, help_text="UUID مزرعه برای خلاصه ریسک آفت/بیماری.")
+
+
+class RiskBreakdownSerializer(serializers.Serializer):
+    score = serializers.FloatField(required=False)
+    level = serializers.CharField(required=False, allow_blank=True)
+    likely_conditions = serializers.ListField(child=serializers.CharField(), required=False)
+    reasoning = serializers.ListField(child=serializers.CharField(), required=False)
+
+
+class PestDetectionRiskResponseSerializer(serializers.Serializer):
+    summary = serializers.CharField(required=False, allow_blank=True)
+    forecast_window = serializers.CharField(required=False, allow_blank=True)
+    overall_risk = serializers.CharField(required=False, allow_blank=True)
+    disease_risk = RiskBreakdownSerializer(required=False)
+    pest_risk = RiskBreakdownSerializer(required=False)
+    key_drivers = serializers.ListField(child=serializers.CharField(), required=False)
+    recommended_actions = serializers.ListField(child=serializers.CharField(), required=False)
+
+
+class RiskCardSerializer(serializers.Serializer):
+    id = serializers.CharField(required=False, allow_blank=True)
+    title = serializers.CharField(required=False, allow_blank=True)
+    subtitle = serializers.CharField(required=False, allow_blank=True)
+    stats = serializers.CharField(required=False, allow_blank=True)
+    avatarColor = serializers.CharField(required=False, allow_blank=True)
+    avatarIcon = serializers.CharField(required=False, allow_blank=True)
+    chipText = serializers.CharField(required=False, allow_blank=True)
+    chipColor = serializers.CharField(required=False, allow_blank=True)
+    details = serializers.DictField(required=False)
+
+
+class PestDetectionRiskSummaryResponseSerializer(serializers.Serializer):
+    farm_uuid = serializers.UUIDField(required=False, allow_null=True)
+    diseaseRisk = RiskCardSerializer(required=False)
+    pestRisk = RiskCardSerializer(required=False)
+    drivers = serializers.DictField(required=False)

Modules/Backend/pest_detection/services.py

@@ -0,0 +1,7 @@
+from copy import deepcopy
+
+from .mock_data import RISK_SUMMARY_RESPONSE_DATA
+
+
+def get_risk_summary_data(farm=None):
+    return deepcopy(RISK_SUMMARY_RESPONSE_DATA)

Modules/Backend/pest_detection/tests.py

@@ -0,0 +1,405 @@
+from unittest.mock import patch
+
+from django.core.cache import cache
+from django.contrib.auth import get_user_model
+from django.test import TestCase, override_settings
+from django.urls import resolve
+from rest_framework.test import APIRequestFactory, force_authenticate
+
+from external_api_adapter.adapter import AdapterResponse
+from farm_hub.models import FarmHub, FarmType, Product
+
+from .views import AnalyzeView, RiskSummaryView, RiskView
+
+
+TEST_CACHES = {
+    "default": {
+        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+        "LOCATION": "pest-detection-tests",
+    }
+}
+
+TEST_RISK_SUMMARY_CACHE_TTL = 14400
+
+
+@override_settings(
+    CACHES=TEST_CACHES,
+    PEST_DISEASE_RISK_SUMMARY_CACHE_TTL=TEST_RISK_SUMMARY_CACHE_TTL,
+)
+class PestDetectionViewTests(TestCase):
+    def setUp(self):
+        cache.clear()
+        self.factory = APIRequestFactory()
+        self.user = get_user_model().objects.create_user(
+            username="farmer",
+            password="secret123",
+            email="farmer@example.com",
+            phone_number="09120000000",
+        )
+        self.other_user = get_user_model().objects.create_user(
+            username="other-farmer",
+            password="secret123",
+            email="other@example.com",
+            phone_number="09120000001",
+        )
+        self.farm_type = FarmType.objects.create(name="زراعی")
+        self.farm = FarmHub.objects.create(owner=self.user, farm_type=self.farm_type, name="Farm 1")
+        self.product = Product.objects.create(farm_type=self.farm_type, name="پیاز")
+        self.farm.products.add(self.product)
+        self.other_farm = FarmHub.objects.create(owner=self.other_user, farm_type=self.farm_type, name="Farm 2")
+
+    @patch("pest_detection.views.external_api_request")
+    def test_analyze_proxies_to_ai_service(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "data": {
+                    "result": {
+                        "has_issue": True,
+                        "category": "disease",
+                        "confidence": 0.93,
+                        "severity": "medium",
+                        "summary": "Leaf spot symptoms detected.",
+                        "detected_signs": ["Brown leaf spots"],
+                        "possible_causes": ["Fungal pressure"],
+                        "immediate_actions": ["Isolate affected plants"],
+                        "reasoning": ["Pattern matched common fungal lesions"],
+                    }
+                }
+            },
+        )
+
+        request = self.factory.post(
+            "/api/pest-detection/analyze/",
+            {"farm_uuid": str(self.farm.farm_uuid), "image_urls": ["https://example.com/leaf.jpg"]},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = AnalyzeView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["code"], 200)
+        self.assertEqual(response.data["data"]["category"], "disease")
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/pest-disease/detect/",
+            method="POST",
+            payload={
+                "farm_uuid": str(self.farm.farm_uuid),
+                "plant_name": "",
+                "query": "",
+                "image_urls": ["https://example.com/leaf.jpg"],
+            },
+        )
+
+    def test_analyze_requires_at_least_one_image(self):
+        request = self.factory.post(
+            "/api/pest-detection/analyze/",
+            {"farm_uuid": str(self.farm.farm_uuid)},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = AnalyzeView.as_view()(request)
+
+        self.assertEqual(response.status_code, 400)
+        self.assertEqual(response.data["code"], 400)
+        self.assertIn("images", response.data["data"])
+
+    @patch("pest_detection.views.external_api_request")
+    def test_risk_proxies_to_ai_service(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "data": {
+                    "result": {
+                        "summary": "Warm humidity raises fungal pressure.",
+                        "forecast_window": "72h",
+                        "overall_risk": "medium",
+                        "disease_risk": {"score": 0.7, "level": "medium", "likely_conditions": [], "reasoning": []},
+                        "pest_risk": {"score": 0.4, "level": "low", "likely_conditions": [], "reasoning": []},
+                        "key_drivers": ["High humidity"],
+                        "recommended_actions": ["Scout vulnerable rows"],
+                    }
+                }
+            },
+        )
+
+        request = self.factory.post(
+            "/api/pest-detection/risk/",
+            {"farm_uuid": str(self.farm.farm_uuid), "plant_name": "wheat"},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RiskView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["data"]["overall_risk"], "medium")
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/pest-disease/risk/",
+            method="POST",
+            payload={
+                "farm_uuid": str(self.farm.farm_uuid),
+                "plant_name": "wheat",
+                "growth_stage": "",
+            },
+        )
+
+    @patch("pest_detection.views.external_api_request")
+    def test_risk_summary_maps_response_shape(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "data": {
+                    "result": {
+                        "disease_risk": {"title": "Disease"},
+                        "pest_risk": {"title": "Pest"},
+                        "drivers": {"humidity": "high"},
+                    }
+                }
+            },
+        )
+
+        request = self.factory.post(
+            "/api/pest-disease/risk-summary/",
+            {"farm_uuid": str(self.farm.farm_uuid)},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RiskSummaryView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["code"], 200)
+        self.assertEqual(response.data["data"]["farm_uuid"], str(self.farm.farm_uuid))
+        self.assertEqual(response.data["data"]["diseaseRisk"]["title"], "Disease")
+        self.assertEqual(response.data["data"]["pestRisk"]["title"], "Pest")
+        self.assertEqual(response.data["data"]["drivers"], {"humidity": "high"})
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/pest-disease/risk/",
+            method="POST",
+            payload={
+                "farm_uuid": str(self.farm.farm_uuid),
+                "plant_name": "پیاز",
+                "growth_stage": "گلدهی",
+            },
+        )
+
+    @patch("pest_detection.views.external_api_request")
+    def test_risk_summary_post_uses_pest_disease_route(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "data": {
+                    "result": {
+                        "disease_risk": {"title": "Disease"},
+                        "pest_risk": {"title": "Pest"},
+                        "drivers": {"humidity": "high"},
+                    }
+                }
+            },
+        )
+
+        request = self.factory.post(
+            "/api/pest-disease/risk-summary/",
+            {"farm_uuid": str(self.farm.farm_uuid)},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RiskSummaryView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["data"]["farm_uuid"], str(self.farm.farm_uuid))
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/pest-disease/risk/",
+            method="POST",
+            payload={
+                "farm_uuid": str(self.farm.farm_uuid),
+                "plant_name": "پیاز",
+                "growth_stage": "گلدهی",
+            },
+        )
+
+    @patch("pest_detection.views.external_api_request")
+    def test_risk_summary_uses_blank_plant_name_when_farm_has_no_products(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "data": {
+                    "result": {
+                        "disease_risk": {"title": "Disease"},
+                        "pest_risk": {"title": "Pest"},
+                        "drivers": {},
+                    }
+                }
+            },
+        )
+        farm_without_products = FarmHub.objects.create(owner=self.user, farm_type=self.farm_type, name="Farm 3")
+
+        request = self.factory.post(
+            "/api/pest-disease/risk-summary/",
+            {"farm_uuid": str(farm_without_products.farm_uuid)},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RiskSummaryView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/pest-disease/risk/",
+            method="POST",
+            payload={
+                "farm_uuid": str(farm_without_products.farm_uuid),
+                "plant_name": "",
+                "growth_stage": "گلدهی",
+            },
+        )
+
+    @patch("pest_detection.views.external_api_request")
+    def test_risk_summary_caches_last_four_responses(self, mock_external_api_request):
+        for index in range(5):
+            product = Product.objects.create(farm_type=self.farm_type, name=f"Product {index}")
+            farm = FarmHub.objects.create(owner=self.user, farm_type=self.farm_type, name=f"Farm {index + 10}")
+            farm.products.add(product)
+            mock_external_api_request.return_value = AdapterResponse(
+                status_code=200,
+                data={
+                    "data": {
+                        "result": {
+                            "disease_risk": {"title": f"Disease {index}"},
+                            "pest_risk": {"title": f"Pest {index}"},
+                            "drivers": {"index": index},
+                        }
+                    }
+                },
+            )
+
+            request = self.factory.post(
+                "/api/pest-disease/risk-summary/",
+                {"farm_uuid": str(farm.farm_uuid)},
+                format="json",
+            )
+            force_authenticate(request, user=self.user)
+            response = RiskSummaryView.as_view()(request)
+
+            self.assertEqual(response.status_code, 200)
+
+        cached_items = cache.get(RiskSummaryView.RISK_SUMMARY_CACHE_KEY)
+
+        self.assertEqual(len(cached_items), 4)
+        self.assertEqual(cached_items[0]["drivers"], {"index": 4})
+        self.assertEqual(cached_items[-1]["drivers"], {"index": 1})
+
+    @patch("pest_detection.views.external_api_request")
+    def test_risk_summary_returns_cached_response_for_same_farm(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "data": {
+                    "result": {
+                        "disease_risk": {"title": "Disease"},
+                        "pest_risk": {"title": "Pest"},
+                        "drivers": {"humidity": "high"},
+                    }
+                }
+            },
+        )
+
+        for _ in range(2):
+            request = self.factory.post(
+                "/api/pest-disease/risk-summary/",
+                {"farm_uuid": str(self.farm.farm_uuid)},
+                format="json",
+            )
+            force_authenticate(request, user=self.user)
+            response = RiskSummaryView.as_view()(request)
+
+            self.assertEqual(response.status_code, 200)
+            self.assertEqual(response.data["data"]["drivers"], {"humidity": "high"})
+
+        cache_key = RiskSummaryView._build_risk_summary_cache_key(self.user.id, self.farm.farm_uuid)
+        self.assertEqual(cache.get(cache_key)["farm_uuid"], str(self.farm.farm_uuid))
+        mock_external_api_request.assert_called_once()
+
+    @patch("pest_detection.views.cache.set")
+    @patch("pest_detection.views.external_api_request")
+    def test_risk_summary_uses_env_ttl_for_cache(self, mock_external_api_request, mock_cache_set):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "data": {
+                    "result": {
+                        "disease_risk": {"title": "Disease"},
+                        "pest_risk": {"title": "Pest"},
+                        "drivers": {},
+                    }
+                }
+            },
+        )
+
+        request = self.factory.post(
+            "/api/pest-disease/risk-summary/",
+            {"farm_uuid": str(self.farm.farm_uuid)},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RiskSummaryView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(
+            any(call.kwargs.get("timeout") == TEST_RISK_SUMMARY_CACHE_TTL for call in mock_cache_set.call_args_list)
+        )
+
+    def test_risk_summary_rejects_extra_fields(self):
+        request = self.factory.post(
+            "/api/pest-disease/risk-summary/",
+            {
+                "farm_uuid": str(self.farm.farm_uuid),
+                "plant_name": "گندم",
+                "growth_stage": "رشد رویشی",
+            },
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RiskSummaryView.as_view()(request)
+
+        self.assertEqual(response.status_code, 400)
+        self.assertEqual(response.data["code"], 400)
+        self.assertIn("non_field_errors", response.data["data"])
+
+    def test_risk_summary_rejects_foreign_farm_uuid(self):
+        request = self.factory.post(
+            "/api/pest-disease/risk-summary/",
+            {"farm_uuid": str(self.other_farm.farm_uuid)},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RiskSummaryView.as_view()(request)
+
+        self.assertEqual(response.status_code, 404)
+        self.assertEqual(response.data["code"], 404)
+        self.assertEqual(response.data["data"]["farm_uuid"][0], "Farm not found.")
+
+    def test_risk_summary_get_is_not_allowed(self):
+        request = self.factory.get(f"/api/pest-disease/risk-summary/?farm_uuid={self.farm.farm_uuid}")
+        force_authenticate(request, user=self.user)
+
+        response = RiskSummaryView.as_view()(request)
+
+        self.assertEqual(response.status_code, 405)
+
+    def test_pest_disease_alias_routes_exist(self):
+        self.assertIs(resolve("/api/pest-disease/detect/").func.view_class, AnalyzeView)
+        self.assertIs(resolve("/api/pest-disease/risk/").func.view_class, RiskView)
+        self.assertIs(resolve("/api/pest-disease/risk-summary/").func.view_class, RiskSummaryView)

Modules/Backend/pest_detection/urls.py

@@ -0,0 +1 @@
+urlpatterns = []

Modules/Backend/pest_detection/views.py

@@ -0,0 +1,293 @@
+"""
+Pest detection API views.
+"""
+
+import json
+
+from django.conf import settings
+from django.core.cache import cache
+from drf_spectacular.utils import extend_schema
+from rest_framework import status
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from config.swagger import status_response
+from external_api_adapter import request as external_api_request
+from farm_hub.models import FarmHub
+from .serializers import (
+    PestDetectionAnalyzeRequestSerializer,
+    PestDetectionAnalyzeResponseSerializer,
+    PestDetectionRiskRequestSerializer,
+    PestDetectionRiskResponseSerializer,
+    PestDetectionRiskSummaryResponseSerializer,
+    PestDetectionRiskSummaryRequestSerializer,
+)
+
+
+class PestDetectionFarmMixin:
+    RISK_SUMMARY_CACHE_KEY = "pest-disease:risk-summary:recent"
+    RISK_SUMMARY_CACHE_LIMIT = 4
+
+    @classmethod
+    def _store_recent_risk_summary(cls, payload):
+        cached_items = cache.get(cls.RISK_SUMMARY_CACHE_KEY, [])
+        if not isinstance(cached_items, list):
+            cached_items = []
+
+        cached_items.insert(0, payload)
+        cache.set(cls.RISK_SUMMARY_CACHE_KEY, cached_items[:cls.RISK_SUMMARY_CACHE_LIMIT], timeout=None)
+
+    @staticmethod
+    def _build_risk_summary_cache_key(user_id, farm_uuid):
+        return f"pest-disease:risk-summary:{user_id}:{farm_uuid}"
+
+    @staticmethod
+    def _get_farm(request, farm_uuid):
+        if not farm_uuid:
+            return None, Response(
+                {"code": 400, "msg": "error", "data": {"farm_uuid": ["This field is required."]}},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        try:
+            return FarmHub.objects.get(farm_uuid=farm_uuid, owner=request.user), None
+        except FarmHub.DoesNotExist:
+            return None, Response(
+                {"code": 404, "msg": "error", "data": {"farm_uuid": ["Farm not found."]}},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+
+    @staticmethod
+    def _parse_json_array(value):
+        if not isinstance(value, str):
+            return None
+        try:
+            parsed = json.loads(value)
+        except (TypeError, ValueError):
+            return None
+        return parsed if isinstance(parsed, list) else None
+
+    def _collect_uploaded_images(self, request):
+        uploaded_images = []
+        single_image = request.FILES.get("image")
+        if single_image is not None:
+            uploaded_images.append(single_image)
+        uploaded_images.extend(request.FILES.getlist("images"))
+        return uploaded_images
+
+    def _prepare_image_urls(self, request):
+        image_urls = request.data.get("image_urls", [])
+        if isinstance(image_urls, str):
+            parsed = self._parse_json_array(image_urls)
+            image_urls = parsed if parsed is not None else [image_urls]
+        return [str(item) for item in image_urls if str(item).strip()]
+
+    @staticmethod
+    def _get_first_farm_product_name(farm):
+        first_product = farm.products.order_by("id").first()
+        if first_product is None:
+            return ""
+        return (first_product.name or "").strip()
+
+    @staticmethod
+    def _attach_uploaded_files(payload, uploaded_images):
+        if not uploaded_images:
+            return payload
+
+        files = []
+        for uploaded_image in uploaded_images:
+            files.append(
+                (
+                    "images",
+                    (
+                        uploaded_image.name,
+                        uploaded_image,
+                        getattr(uploaded_image, "content_type", "application/octet-stream"),
+                    ),
+                )
+            )
+
+        multipart_payload = dict(payload)
+        multipart_payload["image_urls"] = json.dumps(payload.get("image_urls", []), ensure_ascii=False)
+        multipart_payload["__files__"] = files
+        return multipart_payload
+
+    @staticmethod
+    def _extract_result_payload(adapter_data):
+        if not isinstance(adapter_data, dict):
+            return {}
+
+        data = adapter_data.get("data")
+        if isinstance(data, dict) and isinstance(data.get("result"), dict):
+            return data.get("result", {})
+        if isinstance(data, dict):
+            return data
+
+        result = adapter_data.get("result")
+        if isinstance(result, dict):
+            return result
+
+        return adapter_data
+
+    @staticmethod
+    def _error_response(adapter_response):
+        response_data = (
+            adapter_response.data
+            if isinstance(adapter_response.data, dict)
+            else {"message": str(adapter_response.data)}
+        )
+        return Response(
+            {"code": adapter_response.status_code, "msg": "error", "data": response_data},
+            status=adapter_response.status_code,
+        )
+
+
+class AnalyzeView(PestDetectionFarmMixin, APIView):
+    @extend_schema(
+        tags=["Pest Detection"],
+        request=PestDetectionAnalyzeRequestSerializer,
+        responses={200: status_response("PestDetectionAnalyzeResponse", data=PestDetectionAnalyzeResponseSerializer())},
+    )
+    def post(self, request):
+        serializer = PestDetectionAnalyzeRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        payload = serializer.validated_data.copy()
+
+        farm, error_response = self._get_farm(request, payload.get("farm_uuid"))
+        if error_response is not None:
+            return error_response
+
+        image_urls = self._prepare_image_urls(request)
+        uploaded_images = self._collect_uploaded_images(request)
+        if not image_urls and not uploaded_images:
+            return Response(
+                {
+                    "code": 400,
+                    "msg": "error",
+                    "data": {
+                        "images": ["At least one image must be provided via image_urls, image, or images."],
+                    },
+                },
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        ai_payload = {
+            "farm_uuid": str(farm.farm_uuid),
+            "plant_name": payload.get("plant_name", ""),
+            "query": payload.get("query", ""),
+            "image_urls": image_urls,
+        }
+        sensor_uuid = payload.get("sensor_uuid")
+        if sensor_uuid:
+            ai_payload["sensor_uuid"] = str(sensor_uuid)
+
+        ai_payload = self._attach_uploaded_files(ai_payload, uploaded_images)
+
+        adapter_response = external_api_request(
+            "ai",
+            "/api/pest-disease/detect/",
+            method="POST",
+            payload=ai_payload,
+        )
+
+        if adapter_response.status_code >= 400:
+            return self._error_response(adapter_response)
+
+        return Response(
+            {"code": 200, "msg": "success", "data": self._extract_result_payload(adapter_response.data)},
+            status=status.HTTP_200_OK,
+        )
+
+
+class RiskView(PestDetectionFarmMixin, APIView):
+    @extend_schema(
+        tags=["Pest Detection"],
+        request=PestDetectionRiskRequestSerializer,
+        responses={200: status_response("PestDetectionRiskResponse", data=PestDetectionRiskResponseSerializer())},
+    )
+    def post(self, request):
+        serializer = PestDetectionRiskRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        payload = serializer.validated_data.copy()
+
+        farm, error_response = self._get_farm(request, payload.get("farm_uuid"))
+        if error_response is not None:
+            return error_response
+
+        plant_name = self._get_first_farm_product_name(farm)
+        ai_payload = {
+            "farm_uuid": str(farm.farm_uuid),
+            "plant_name": plant_name,
+            "growth_stage": "گلدهی",
+        }
+
+        adapter_response = external_api_request(
+            "ai",
+            "/api/pest-disease/risk/",
+            method="POST",
+            payload=ai_payload,
+        )
+
+        if adapter_response.status_code >= 400:
+            return self._error_response(adapter_response)
+
+        return Response(
+            {"code": 200, "msg": "success", "data": self._extract_result_payload(adapter_response.data)},
+            status=status.HTTP_200_OK,
+        )
+
+
+class RiskSummaryView(PestDetectionFarmMixin, APIView):
+    @extend_schema(
+        tags=["Pest Detection"],
+        request=PestDetectionRiskSummaryRequestSerializer,
+        responses={200: status_response("PestDetectionRiskSummaryResponse", data=PestDetectionRiskSummaryResponseSerializer())},
+    )
+    def post(self, request):
+        serializer = PestDetectionRiskSummaryRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        payload = serializer.validated_data
+
+        farm_uuid = payload.get("farm_uuid")
+
+        farm, error_response = self._get_farm(request, farm_uuid)
+        if error_response is not None:
+            return error_response
+
+        cache_key = self._build_risk_summary_cache_key(request.user.id, farm.farm_uuid)
+        cached_response = cache.get(cache_key)
+        if isinstance(cached_response, dict):
+            return Response(
+                {"code": 200, "msg": "success", "data": cached_response},
+                status=status.HTTP_200_OK,
+            )
+
+        plant_name = self._get_first_farm_product_name(farm)
+        ai_payload = {
+            "farm_uuid": str(farm.farm_uuid),
+            "plant_name": plant_name,
+            "growth_stage": "گلدهی",
+        }
+
+        adapter_response = external_api_request(
+            "ai",
+            "/api/pest-disease/risk/",
+            method="POST",
+            payload=ai_payload,
+        )
+
+        if adapter_response.status_code >= 400:
+            return self._error_response(adapter_response)
+
+        result = self._extract_result_payload(adapter_response.data)
+        response_payload = {
+            "farm_uuid": str(farm.farm_uuid),
+            "diseaseRisk": result.get("diseaseRisk") or result.get("disease_risk") or {},
+            "pestRisk": result.get("pestRisk") or result.get("pest_risk") or {},
+            "drivers": result.get("drivers") if isinstance(result.get("drivers"), dict) else {},
+        }
+        cache.set(cache_key, response_payload, timeout=settings.PEST_DISEASE_RISK_SUMMARY_CACHE_TTL)
+        self._store_recent_risk_summary(response_payload)
+        return Response(
+            {"code": 200, "msg": "success", "data": response_payload},
+            status=status.HTTP_200_OK,
+        )