UPDATE

fertilization/__init__.py

@@ -0,0 +1 @@
+

fertilization/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class FertilizationConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "fertilization"
+    label = "fertilization_recommendation"
+    verbose_name = "Fertilization Recommendation & Plan Parser"

fertilization/migrations/0001_initial.py

@@ -0,0 +1,41 @@
+import django.db.models.deletion
+import uuid
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("farm_hub", "0002_seed_default_catalog"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="FertilizationRecommendationRequest",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
+                ("uuid", models.UUIDField(db_index=True, default=uuid.uuid4, editable=False, unique=True)),
+                ("crop_id", models.CharField(blank=True, default="", max_length=255)),
+                ("growth_stage", models.CharField(blank=True, default="", max_length=255)),
+                ("task_id", models.CharField(blank=True, db_index=True, default="", max_length=255)),
+                ("status", models.CharField(blank=True, default="", max_length=64)),
+                ("request_payload", models.JSONField(blank=True, default=dict)),
+                ("response_payload", models.JSONField(blank=True, default=dict)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "farm",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="fertilizations",
+                        to="farm_hub.farmhub",
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "fertilization_requests",
+                "ordering": ["-created_at", "-id"],
+            },
+        ),
+    ]

fertilization/migrations/0002_recommendation_status_lifecycle.py

@@ -0,0 +1,37 @@
+from django.db import migrations, models
+
+
+PENDING_STATUS = "pending_confirmation"
+OLD_STATUSES = {"", "success", "error", None}
+
+
+def migrate_existing_statuses(apps, schema_editor):
+    Recommendation = apps.get_model("fertilization", "FertilizationRecommendationRequest")
+    Recommendation.objects.filter(status__in=[status for status in OLD_STATUSES if status is not None]).update(
+        status=PENDING_STATUS
+    )
+    Recommendation.objects.filter(status__isnull=True).update(status=PENDING_STATUS)
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("fertilization", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="fertilizationrecommendationrequest",
+            name="status",
+            field=models.CharField(
+                choices=[
+                    ("in_progress", "در حال مصرف"),
+                    ("pending_confirmation", "منتظر تایید"),
+                    ("completed", "پایان یافته"),
+                ],
+                db_index=True,
+                default="pending_confirmation",
+                max_length=64,
+            ),
+        ),
+        migrations.RunPython(migrate_existing_statuses, migrations.RunPython.noop),
+    ]

fertilization/mock_data.py

@@ -0,0 +1,44 @@
+"""
+Static mock data for Fertilization Recommendation API.
+No database, no dynamic values.
+"""
+
+CONFIG_RESPONSE_DATA = {
+    "farmData": {
+        "soilType": "Loamy",
+        "organicMatter": "Medium (2.5%)",
+        "waterEC": "1.2 dS/m",
+    },
+    "growthStages": [
+        {"id": "prePlanting", "icon": "tabler-seedling"},
+        {"id": "earlyGrowth", "icon": "tabler-leaf"},
+        {"id": "flowering", "icon": "tabler-flower"},
+        {"id": "fruiting", "icon": "tabler-apple"},
+        {"id": "postHarvest", "icon": "tabler-basket"},
+    ],
+    "cropOptions": [
+        {"id": "wheat", "labelKey": "wheat", "icon": "tabler-wheat"},
+        {"id": "corn", "labelKey": "corn", "icon": "tabler-plant-2"},
+        {"id": "cotton", "labelKey": "cotton", "icon": "tabler-flower"},
+        {"id": "saffron", "labelKey": "saffron", "icon": "tabler-flower-2"},
+        {"id": "canola", "labelKey": "canola", "icon": "tabler-leaf"},
+        {"id": "vegetables", "labelKey": "vegetables", "icon": "tabler-carrot"},
+    ],
+}
+
+RECOMMEND_RESPONSE_DATA = {
+    "plan": {
+        "npkRatio": "20-20-20 (NPK)",
+        "amountPerHectare": "150 kg/ha",
+        "applicationMethod": "Foliar spray + soil broadcast",
+        "applicationInterval": "Every 14 days",
+        "reasoning": "Your loamy soil with medium organic matter (2.5%) provides good nutrient retention. Water EC of 1.2 dS/m indicates low salinity—suitable for most crops. At the flowering stage, increased phosphorus supports bloom development. We recommend a balanced NPK to maintain nitrogen for vegetative growth while boosting phosphorous for flowering.",
+    },
+}
+
+FERTILIZATION_DASHBOARD_RECOMMENDATION = {
+    "title": "کود: 20-20-20 (NPK)",
+    "subtitle": "150 kg/ha، با روش Foliar spray + soil broadcast و هر 14 روز.",
+    "avatarIcon": "tabler-leaf",
+    "avatarColor": "success",
+}

fertilization/models.py

@@ -0,0 +1,43 @@
+import uuid
+
+from django.db import models
+
+from farm_hub.models import FarmHub
+
+
+class FertilizationRecommendationRequest(models.Model):
+    STATUS_IN_PROGRESS = "in_progress"
+    STATUS_PENDING_CONFIRMATION = "pending_confirmation"
+    STATUS_COMPLETED = "completed"
+    STATUS_CHOICES = (
+        (STATUS_IN_PROGRESS, "در حال مصرف"),
+        (STATUS_PENDING_CONFIRMATION, "منتظر تایید"),
+        (STATUS_COMPLETED, "پایان یافته"),
+    )
+
+    uuid = models.UUIDField(default=uuid.uuid4, unique=True, editable=False, db_index=True)
+    farm = models.ForeignKey(
+        FarmHub,
+        on_delete=models.CASCADE,
+        related_name="fertilizations",
+    )
+    crop_id = models.CharField(max_length=255, blank=True, default="")
+    growth_stage = models.CharField(max_length=255, blank=True, default="")
+    task_id = models.CharField(max_length=255, blank=True, default="", db_index=True)
+    status = models.CharField(
+        max_length=64,
+        choices=STATUS_CHOICES,
+        default=STATUS_PENDING_CONFIRMATION,
+        db_index=True,
+    )
+    request_payload = models.JSONField(default=dict, blank=True)
+    response_payload = models.JSONField(default=dict, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "fertilization_requests"
+        ordering = ["-created_at", "-id"]
+
+    def __str__(self):
+        return self.task_id or str(self.uuid)

fertilization/postman/fertilization_recommendation.json

@@ -0,0 +1 @@
+{"info":{"name":"Fertilization Recommendation","schema":"https://schema.getpostman.com/json/collection/v2.1.0/collection.json","description":"Fertilization Recommendation API. GET config (farm data, growth stages, crop options). POST recommend (optional body). Returns static plan. No database."},"item":[{"name":"Get config (GET)","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"{{baseUrl}}/api/fertilization-recommendation/config/","description":"Returns static farmData, growthStages, cropOptions."},"response":[{"name":"Success","status":"OK","code":200,"body":"{\n  \"status\": \"success\",\n  \"data\": {\n    \"farmData\": {\n      \"soilType\": \"Loamy\",\n      \"organicMatter\": \"Medium (2.5%)\",\n      \"waterEC\": \"1.2 dS/m\"\n    },\n    \"growthStages\": [\n      {\"id\": \"prePlanting\", \"icon\": \"tabler-seedling\"},\n      {\"id\": \"earlyGrowth\", \"icon\": \"tabler-leaf\"},\n      {\"id\": \"flowering\", \"icon\": \"tabler-flower\"},\n      {\"id\": \"fruiting\", \"icon\": \"tabler-apple\"},\n      {\"id\": \"postHarvest\", \"icon\": \"tabler-basket\"}\n    ],\n    \"cropOptions\": [\n      {\"id\": \"wheat\", \"labelKey\": \"wheat\", \"icon\": \"tabler-wheat\"},\n      {\"id\": \"corn\", \"labelKey\": \"corn\", \"icon\": \"tabler-plant-2\"},\n      {\"id\": \"cotton\", \"labelKey\": \"cotton\", \"icon\": \"tabler-flower\"},\n      {\"id\": \"saffron\", \"labelKey\": \"saffron\", \"icon\": \"tabler-flower-2\"},\n      {\"id\": \"canola\", \"labelKey\": \"canola\", \"icon\": \"tabler-leaf\"},\n      {\"id\": \"vegetables\", \"labelKey\": \"vegetables\", \"icon\": \"tabler-carrot\"}\n    ]\n  }\n}"}]},{"name":"Get recommendation (POST)","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n  \"crop_id\": \"wheat\",\n  \"growth_stage\": \"flowering\",\n  \"soilType\": \"Loamy\",\n  \"organicMatter\": \"Medium (2.5%)\",\n  \"waterEC\": \"1.2 dS/m\"\n}"},"url":"{{baseUrl}}/api/fertilization-recommendation/recommend/","description":"Optional body: crop_id, growth_stage, farm_data. Returns static plan. Input not processed."},"response":[{"name":"Success","status":"OK","code":200,"body":"{\n  \"status\": \"success\",\n  \"data\": {\n    \"plan\": {\n      \"npkRatio\": \"20-20-20 (NPK)\",\n      \"amountPerHectare\": \"150 kg/ha\",\n      \"applicationMethod\": \"Foliar spray + soil broadcast\",\n      \"applicationInterval\": \"Every 14 days\",\n      \"reasoning\": \"Your loamy soil with medium organic matter (2.5%) provides good nutrient retention. Water EC of 1.2 dS/m indicates low salinity—suitable for most crops. At the flowering stage, increased phosphorus supports bloom development. We recommend a balanced NPK to maintain nitrogen for vegetative growth while boosting phosphorous for flowering.\"\n    }\n  }\n}"}]}],"variable":[{"key":"baseUrl","value":"http://localhost:8000"}]}

fertilization/serializers.py

@@ -0,0 +1,169 @@
+from rest_framework import serializers
+
+
+class FertilizationFarmDataSerializer(serializers.Serializer):
+    soilType = serializers.CharField(required=False, allow_blank=True)
+    organicMatter = serializers.CharField(required=False, allow_blank=True)
+    waterEC = serializers.CharField(required=False, allow_blank=True)
+
+
+class FertilizationRecommendRequestSerializer(serializers.Serializer):
+    farm_uuid = serializers.UUIDField(required=True, help_text="UUID مزرعه برای دریافت توصیه کودی.")
+    crop_id = serializers.CharField(required=False, allow_blank=True, help_text="شناسه یا نام محصول. این فیلد همان plant_name است.")
+    plant_name = serializers.CharField(required=False, allow_blank=True, help_text="نام محصول یا گیاه. این فیلد همان crop_id است.")
+    growth_stage = serializers.CharField(required=False, allow_blank=True, help_text="مرحله رشد گیاه.")
+
+
+class FertilizationRecommendationListQuerySerializer(serializers.Serializer):
+    farm_uuid = serializers.UUIDField(required=True, help_text="UUID مزرعه برای دریافت لیست توصیه های کودی.")
+    page = serializers.IntegerField(required=False, min_value=1)
+    page_size = serializers.IntegerField(required=False, min_value=1, max_value=100)
+
+
+class FertilizationSectionSerializer(serializers.Serializer):
+    type = serializers.ChoiceField(choices=["text", "list", "recommendation", "warning"])
+    title = serializers.CharField(required=False, allow_blank=True)
+    icon = serializers.CharField(required=False, allow_blank=True)
+    content = serializers.CharField(required=False, allow_blank=True)
+    items = serializers.ListField(child=serializers.CharField(), required=False)
+    fertilizerType = serializers.CharField(required=False, allow_blank=True)
+    amount = serializers.CharField(required=False, allow_blank=True)
+    applicationMethod = serializers.CharField(required=False, allow_blank=True)
+    timing = serializers.CharField(required=False, allow_blank=True)
+    validityPeriod = serializers.CharField(required=False, allow_blank=True)
+    expandableExplanation = serializers.CharField(required=False, allow_blank=True)
+
+
+class NpkRatioSerializer(serializers.Serializer):
+    n = serializers.FloatField(required=False)
+    p = serializers.FloatField(required=False)
+    k = serializers.FloatField(required=False)
+    label = serializers.CharField(required=False, allow_blank=True)
+
+
+class ApplicationMethodSerializer(serializers.Serializer):
+    id = serializers.CharField(required=False, allow_blank=True)
+    label = serializers.CharField(required=False, allow_blank=True)
+
+
+class ApplicationIntervalSerializer(serializers.Serializer):
+    value = serializers.FloatField(required=False)
+    unit = serializers.CharField(required=False, allow_blank=True)
+    label = serializers.CharField(required=False, allow_blank=True)
+
+
+class DosageSerializer(serializers.Serializer):
+    base_amount_per_hectare = serializers.FloatField(required=False)
+    base_amount_per_square_meter = serializers.FloatField(required=False)
+    unit = serializers.CharField(required=False, allow_blank=True)
+    label = serializers.CharField(required=False, allow_blank=True)
+    calculation_basis = serializers.CharField(required=False, allow_blank=True)
+
+
+class PrimaryRecommendationSerializer(serializers.Serializer):
+    fertilizer_code = serializers.CharField(required=False, allow_blank=True)
+    fertilizer_name = serializers.CharField(required=False, allow_blank=True)
+    display_title = serializers.CharField(required=False, allow_blank=True)
+    fertilizer_type = serializers.CharField(required=False, allow_blank=True)
+    npk_ratio = NpkRatioSerializer(required=False)
+    application_method = ApplicationMethodSerializer(required=False)
+    application_interval = ApplicationIntervalSerializer(required=False)
+    dosage = DosageSerializer(required=False)
+    reasoning = serializers.CharField(required=False, allow_blank=True)
+    summary = serializers.CharField(required=False, allow_blank=True)
+
+
+class NutrientItemSerializer(serializers.Serializer):
+    key = serializers.CharField(required=False, allow_blank=True)
+    name = serializers.CharField(required=False, allow_blank=True)
+    value = serializers.FloatField(required=False)
+    unit = serializers.CharField(required=False, allow_blank=True)
+    description = serializers.CharField(required=False, allow_blank=True)
+
+
+class NutrientAnalysisSerializer(serializers.Serializer):
+    macro = NutrientItemSerializer(many=True, read_only=True)
+    micro = NutrientItemSerializer(many=True, read_only=True)
+
+
+class ApplicationGuideStepSerializer(serializers.Serializer):
+    step_number = serializers.IntegerField(required=False)
+    title = serializers.CharField(required=False, allow_blank=True)
+    description = serializers.CharField(required=False, allow_blank=True)
+
+
+class ApplicationGuideSerializer(serializers.Serializer):
+    safety_warning = serializers.CharField(required=False, allow_blank=True)
+    steps = ApplicationGuideStepSerializer(many=True, read_only=True)
+
+
+class AlternativeRecommendationSerializer(serializers.Serializer):
+    fertilizer_code = serializers.CharField(required=False, allow_blank=True)
+    fertilizer_name = serializers.CharField(required=False, allow_blank=True)
+    fertilizer_type = serializers.CharField(required=False, allow_blank=True)
+    usage_method = serializers.CharField(required=False, allow_blank=True)
+    description = serializers.CharField(required=False, allow_blank=True)
+
+
+class FertilizationRecommendationListItemSerializer(serializers.Serializer):
+    recommendation_uuid = serializers.UUIDField(source="uuid", read_only=True)
+    crop_id = serializers.CharField(read_only=True)
+    plant_name = serializers.CharField(source="crop_id", read_only=True)
+    growth_stage = serializers.CharField(read_only=True)
+    fertilizer_type = serializers.CharField(read_only=True, allow_blank=True)
+    status = serializers.CharField(read_only=True)
+    status_label = serializers.CharField(source="get_status_display", read_only=True)
+    requested_at = serializers.DateTimeField(source="created_at", read_only=True)
+
+
+class FreeTextPlanParserRequestSerializer(serializers.Serializer):
+    message = serializers.CharField(required=False, allow_blank=True, help_text="متن آزاد کاربر.")
+    answers = serializers.DictField(required=False, help_text="پاسخ های تکمیلی کاربر.")
+    partial_plan = serializers.DictField(required=False, help_text="داده استخراج شده از مرحله قبل.")
+    farm_uuid = serializers.UUIDField(
+        required=False,
+        allow_null=True,
+        initial="11111111-1111-1111-1111-111111111111",
+        help_text="UUID مزرعه برای context اختیاری.",
+    )
+
+    def validate(self, attrs):
+        has_message = bool((attrs.get("message") or "").strip())
+        has_answers = isinstance(attrs.get("answers"), dict) and bool(attrs.get("answers"))
+        has_partial_plan = isinstance(attrs.get("partial_plan"), dict) and bool(attrs.get("partial_plan"))
+        if not (has_message or has_answers or has_partial_plan):
+            raise serializers.ValidationError(
+                {"non_field_errors": ["حداقل یکی از message، answers یا partial_plan باید ارسال شود."]}
+            )
+        return attrs
+
+
+class PlanParserQuestionSerializer(serializers.Serializer):
+    id = serializers.CharField(required=False, allow_blank=True)
+    field = serializers.CharField(required=False, allow_blank=True)
+    question = serializers.CharField(required=False, allow_blank=True)
+    rationale = serializers.CharField(required=False, allow_blank=True)
+
+
+class FreeTextPlanParserResponseDataSerializer(serializers.Serializer):
+    status = serializers.CharField(required=False, allow_blank=True)
+    status_fa = serializers.CharField(required=False, allow_blank=True)
+    summary = serializers.CharField(required=False, allow_blank=True)
+    missing_fields = serializers.ListField(child=serializers.CharField(), required=False)
+    questions = PlanParserQuestionSerializer(many=True, required=False)
+    collected_data = serializers.DictField(required=False)
+    final_plan = serializers.DictField(required=False, allow_null=True)
+
+
+class FertilizationRecommendResponseDataSerializer(serializers.Serializer):
+    recommendation_uuid = serializers.UUIDField(read_only=True, required=False)
+    crop_id = serializers.CharField(read_only=True, required=False, allow_blank=True)
+    plant_name = serializers.CharField(read_only=True, required=False, allow_blank=True)
+    growth_stage = serializers.CharField(read_only=True, required=False, allow_blank=True)
+    status = serializers.CharField(read_only=True, required=False)
+    status_label = serializers.CharField(read_only=True, required=False)
+    primary_recommendation = PrimaryRecommendationSerializer(read_only=True)
+    nutrient_analysis = NutrientAnalysisSerializer(read_only=True)
+    application_guide = ApplicationGuideSerializer(read_only=True)
+    alternative_recommendations = AlternativeRecommendationSerializer(many=True, read_only=True)
+    sections = FertilizationSectionSerializer(many=True, read_only=True)

fertilization/services.py

@@ -0,0 +1,50 @@
+from copy import deepcopy
+
+from .mock_data import FERTILIZATION_DASHBOARD_RECOMMENDATION, RECOMMEND_RESPONSE_DATA
+from .models import FertilizationRecommendationRequest
+
+
+def _extract_result(response_payload):
+    if not isinstance(response_payload, dict):
+        return {}
+
+    data = response_payload.get("data")
+    if isinstance(data, dict) and isinstance(data.get("result"), dict):
+        return data["result"]
+
+    result = response_payload.get("result")
+    if isinstance(result, dict):
+        return result
+
+    return {}
+
+
+def _get_latest_result(farm):
+    if farm is None:
+        return {}
+
+    for request in FertilizationRecommendationRequest.objects.filter(farm=farm):
+        result = _extract_result(request.response_payload)
+        if result:
+            return result
+
+    return {}
+
+
+def get_fertilization_dashboard_recommendation(farm=None):
+    default_item = deepcopy(FERTILIZATION_DASHBOARD_RECOMMENDATION)
+    result = _get_latest_result(farm)
+    plan = result.get("plan") or RECOMMEND_RESPONSE_DATA.get("plan", {})
+
+    npk_ratio = plan.get("npkRatio") or "20-20-20 (NPK)"
+    amount = plan.get("amountPerHectare")
+    method = plan.get("applicationMethod")
+    interval = plan.get("applicationInterval")
+
+    subtitle_parts = [part for part in [amount, method, interval] if part]
+
+    default_item["title"] = f"کود: {npk_ratio}"
+    if subtitle_parts:
+        default_item["subtitle"] = "، ".join(subtitle_parts)
+
+    return default_item

fertilization/tests.py

@@ -0,0 +1,320 @@
+from django.contrib.auth import get_user_model
+from django.test import TestCase
+from rest_framework.test import APIRequestFactory, force_authenticate
+from unittest.mock import patch
+
+from external_api_adapter.adapter import AdapterResponse
+from farm_hub.models import FarmHub, FarmType
+from .models import FertilizationRecommendationRequest
+from .views import PlanFromTextView, RecommendationDetailView, RecommendationListView, RecommendView
+
+
+class FertilizationRecommendViewTests(TestCase):
+    def setUp(self):
+        self.factory = APIRequestFactory()
+        self.user = get_user_model().objects.create_user(
+            username="fert-user",
+            password="secret123",
+            email="fert@example.com",
+            phone_number="09125556677",
+        )
+        self.farm_type = FarmType.objects.create(name="زراعی")
+        self.farm = FarmHub.objects.create(owner=self.user, farm_type=self.farm_type, name="fert-farm")
+
+    @patch("fertilization.views.external_api_request")
+    def test_plan_from_text_proxies_to_ai_service(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "code": 200,
+                "msg": "موفق",
+                "data": {
+                    "status": "needs_clarification",
+                    "status_fa": "نیازمند پرسش تکمیلی",
+                    "summary": "need more",
+                    "missing_fields": ["growth_stage"],
+                    "questions": [{"id": "growth_stage", "field": "growth_stage", "question": "?", "rationale": "!"}],
+                    "collected_data": {"crop_name": "گندم"},
+                    "final_plan": None,
+                },
+            },
+        )
+
+        request = self.factory.post(
+            "/api/fertilization/plan-from-text/",
+            {"message": "متن کودهی", "farm_uuid": str(self.farm.farm_uuid)},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = PlanFromTextView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["data"]["status"], "needs_clarification")
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/fertilization/plan-from-text/",
+            method="POST",
+            payload={"message": "متن کودهی", "farm_uuid": str(self.farm.farm_uuid)},
+        )
+
+    def test_plan_from_text_requires_message_or_answers_or_partial_plan(self):
+        request = self.factory.post("/api/fertilization/plan-from-text/", {}, format="json")
+        force_authenticate(request, user=self.user)
+
+        response = PlanFromTextView.as_view()(request)
+
+        self.assertEqual(response.status_code, 400)
+        self.assertIn("non_field_errors", response.data)
+
+    @patch("fertilization.views.external_api_request")
+    def test_recommend_returns_updated_response_shape(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(
+            status_code=200,
+            data={
+                "code": 200,
+                "msg": "success",
+                "data": {
+                    "primary_recommendation": {
+                        "fertilizer_code": "npk-202020",
+                        "fertilizer_name": "NPK 20-20-20",
+                        "display_title": "کود کامل متعادل",
+                        "fertilizer_type": "NPK",
+                        "npk_ratio": {"n": 20, "p": 20, "k": 20, "label": "20-20-20"},
+                        "application_method": {"id": "fertigation", "label": "کودآبیاری"},
+                        "application_interval": {"value": 14, "unit": "day", "label": "هر 14 روز"},
+                        "dosage": {
+                            "base_amount_per_hectare": 65,
+                            "base_amount_per_square_meter": 0.0065,
+                            "unit": "kg",
+                            "label": "65 کیلوگرم در هکتار",
+                            "calculation_basis": "engine-v2",
+                        },
+                        "reasoning": "متعادل برای فاز رشد",
+                        "summary": "مصرف منظم در این مرحله توصیه می شود",
+                    },
+                    "nutrient_analysis": {
+                        "macro": [
+                            {"key": "n", "name": "Nitrogen", "value": 20, "unit": "percent", "description": "تقویت رشد رویشی"}
+                        ],
+                        "micro": [
+                            {"key": "zn", "name": "Zinc", "value": 2.5, "unit": "percent", "description": "بهبود رشد"}
+                        ],
+                    },
+                    "application_guide": {
+                        "safety_warning": "در ساعات خنک مصرف شود",
+                        "steps": [
+                            {"step_number": 1, "title": "حل کردن", "description": "کود را در آب حل کنید"}
+                        ],
+                    },
+                    "alternative_recommendations": [
+                        {
+                            "fertilizer_code": "npk-121236",
+                            "fertilizer_name": "NPK 12-12-36",
+                            "fertilizer_type": "NPK",
+                            "usage_method": "fertigation",
+                            "description": "برای نیاز پتاس بالا",
+                        }
+                    ],
+                    "sections": [
+                        {"type": "recommendation", "title": "پیشنهاد اصلی", "icon": "leaf", "content": "NPK 20-20-20"}
+                    ],
+                },
+            },
+        )
+
+        request = self.factory.post(
+            "/api/fertilization/recommend/",
+            {"farm_uuid": str(self.farm.farm_uuid), "crop_id": "گندم", "growth_stage": "vegetative"},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RecommendView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["code"], 200)
+        self.assertIn("primary_recommendation", response.data["data"])
+        self.assertIn("nutrient_analysis", response.data["data"])
+        self.assertIn("application_guide", response.data["data"])
+        self.assertIn("alternative_recommendations", response.data["data"])
+        self.assertEqual(response.data["data"]["primary_recommendation"]["fertilizer_code"], "npk-202020")
+        self.assertEqual(response.data["data"]["primary_recommendation"]["application_interval"]["value"], 14.0)
+        self.assertEqual(response.data["data"]["alternative_recommendations"][0]["usage_method"], "fertigation")
+        self.assertEqual(response.data["data"]["sections"][0]["type"], "recommendation")
+        self.assertEqual(FertilizationRecommendationRequest.objects.count(), 1)
+        saved_request = FertilizationRecommendationRequest.objects.get()
+        self.assertEqual(saved_request.crop_id, "گندم")
+        self.assertEqual(saved_request.growth_stage, "vegetative")
+        self.assertEqual(
+            saved_request.status,
+            FertilizationRecommendationRequest.STATUS_PENDING_CONFIRMATION,
+        )
+        self.assertEqual(
+            saved_request.response_payload["data"]["primary_recommendation"]["fertilizer_code"],
+            "npk-202020",
+        )
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/fertilization/recommend/",
+            method="POST",
+            payload={
+                "farm_uuid": str(self.farm.farm_uuid),
+                "crop_id": "گندم",
+                "plant_name": "گندم",
+                "growth_stage": "vegetative",
+            },
+        )
+
+    @patch("fertilization.views.external_api_request")
+    def test_recommend_accepts_plant_name_and_passes_it_directly_to_ai(self, mock_external_api_request):
+        mock_external_api_request.return_value = AdapterResponse(status_code=200, data={"data": {}})
+
+        request = self.factory.post(
+            "/api/fertilization/recommend/",
+            {"farm_uuid": str(self.farm.farm_uuid), "plant_name": "جو", "growth_stage": "flowering"},
+            format="json",
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RecommendView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        saved_request = FertilizationRecommendationRequest.objects.latest("created_at")
+        self.assertEqual(saved_request.crop_id, "جو")
+        mock_external_api_request.assert_called_once_with(
+            "ai",
+            "/api/fertilization/recommend/",
+            method="POST",
+            payload={
+                "farm_uuid": str(self.farm.farm_uuid),
+                "crop_id": "جو",
+                "plant_name": "جو",
+                "growth_stage": "flowering",
+            },
+        )
+
+    def test_recommendation_list_returns_paginated_summary_items(self):
+        first = FertilizationRecommendationRequest.objects.create(
+            farm=self.farm,
+            crop_id="گندم",
+            growth_stage="vegetative",
+            status=FertilizationRecommendationRequest.STATUS_PENDING_CONFIRMATION,
+            response_payload={
+                "data": {
+                    "primary_recommendation": {
+                        "fertilizer_type": "NPK",
+                    }
+                }
+            },
+        )
+        second = FertilizationRecommendationRequest.objects.create(
+            farm=self.farm,
+            crop_id="ذرت",
+            growth_stage="flowering",
+            status=FertilizationRecommendationRequest.STATUS_PENDING_CONFIRMATION,
+            response_payload={
+                "data": {
+                    "primary_recommendation": {
+                        "fertilizer_type": "Micronutrient",
+                    }
+                }
+            },
+        )
+
+        request = self.factory.get(
+            f"/api/fertilization/recommendations/?farm_uuid={self.farm.farm_uuid}&page=1&page_size=1"
+        )
+        force_authenticate(request, user=self.user)
+
+        response = RecommendationListView.as_view()(request)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["code"], 200)
+        self.assertEqual(len(response.data["data"]), 1)
+        self.assertEqual(response.data["pagination"]["page"], 1)
+        self.assertEqual(response.data["pagination"]["page_size"], 1)
+        self.assertEqual(response.data["pagination"]["total_pages"], 2)
+        self.assertEqual(response.data["pagination"]["total_items"], 2)
+        self.assertTrue(response.data["pagination"]["has_next"])
+        self.assertFalse(response.data["pagination"]["has_previous"])
+        self.assertEqual(response.data["data"][0]["recommendation_uuid"], str(second.uuid))
+        self.assertEqual(response.data["data"][0]["plant_name"], "ذرت")
+        self.assertEqual(response.data["data"][0]["growth_stage"], "flowering")
+        self.assertEqual(response.data["data"][0]["fertilizer_type"], "Micronutrient")
+        self.assertEqual(response.data["data"][0]["status"], "pending_confirmation")
+        self.assertEqual(response.data["data"][0]["status_label"], "منتظر تایید")
+        self.assertIn("requested_at", response.data["data"][0])
+        self.assertNotEqual(response.data["data"][0]["recommendation_uuid"], str(first.uuid))
+
+    def test_recommendation_detail_returns_same_shape_as_recommend_endpoint(self):
+        recommendation = FertilizationRecommendationRequest.objects.create(
+            farm=self.farm,
+            crop_id="گندم",
+            growth_stage="vegetative",
+            status=FertilizationRecommendationRequest.STATUS_PENDING_CONFIRMATION,
+            response_payload={
+                "data": {
+                    "primary_recommendation": {
+                        "fertilizer_code": "npk-202020",
+                        "fertilizer_type": "NPK",
+                        "summary": "خلاصه توصیه",
+                    },
+                    "nutrient_analysis": {
+                        "macro": [{"key": "n", "name": "Nitrogen", "value": 20, "unit": "percent"}],
+                        "micro": [],
+                    },
+                    "application_guide": {
+                        "safety_warning": "در هوای خنک استفاده شود",
+                        "steps": [{"step_number": 1, "title": "آماده سازی", "description": "در آب حل شود"}],
+                    },
+                    "alternative_recommendations": [
+                        {"fertilizer_code": "alt-1", "fertilizer_name": "Alt", "fertilizer_type": "NPK"}
+                    ],
+                    "sections": [{"type": "warning", "title": "هشدار", "content": "اختلاط نشود"}],
+                }
+            },
+        )
+
+        request = self.factory.get(f"/api/fertilization/recommendations/{recommendation.uuid}/")
+        force_authenticate(request, user=self.user)
+
+        response = RecommendationDetailView.as_view()(request, recommendation_uuid=recommendation.uuid)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["code"], 200)
+        self.assertEqual(response.data["data"]["primary_recommendation"]["fertilizer_code"], "npk-202020")
+        self.assertEqual(response.data["data"]["primary_recommendation"]["fertilizer_type"], "NPK")
+        self.assertEqual(response.data["data"]["nutrient_analysis"]["macro"][0]["value"], 20.0)
+        self.assertEqual(response.data["data"]["application_guide"]["steps"][0]["step_number"], 1)
+        self.assertEqual(response.data["data"]["sections"][0]["type"], "warning")
+        self.assertEqual(response.data["data"]["recommendation_uuid"], str(recommendation.uuid))
+        self.assertEqual(response.data["data"]["crop_id"], "گندم")
+        self.assertEqual(response.data["data"]["plant_name"], "گندم")
+        self.assertEqual(response.data["data"]["status"], "pending_confirmation")
+        self.assertEqual(response.data["data"]["status_label"], "منتظر تایید")
+
+    def test_recommendation_detail_falls_back_to_top_level_fertilizer_code(self):
+        recommendation = FertilizationRecommendationRequest.objects.create(
+            farm=self.farm,
+            crop_id="گندم",
+            growth_stage="vegetative",
+            status=FertilizationRecommendationRequest.STATUS_PENDING_CONFIRMATION,
+            response_payload={
+                "data": {
+                    "fertilizer_code": "legacy-code-101",
+                    "fertilizer_type": "NPK",
+                }
+            },
+        )
+
+        request = self.factory.get(f"/api/fertilization/recommendations/{recommendation.uuid}/")
+        force_authenticate(request, user=self.user)
+
+        response = RecommendationDetailView.as_view()(request, recommendation_uuid=recommendation.uuid)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(
+            response.data["data"]["primary_recommendation"]["fertilizer_code"],
+            "legacy-code-101",
+        )

fertilization/urls.py

@@ -0,0 +1,11 @@
+from django.urls import path
+
+from .views import ConfigView, PlanFromTextView, RecommendationDetailView, RecommendationListView, RecommendView
+
+urlpatterns = [
+    path("config/", ConfigView.as_view(), name="fertilization-recommendation-config"),
+    path("recommendations/<uuid:recommendation_uuid>/", RecommendationDetailView.as_view(), name="fertilization-recommendation-detail"),
+    path("recommendations/", RecommendationListView.as_view(), name="fertilization-recommendation-list"),
+    path("recommend/", RecommendView.as_view(), name="fertilization-recommendation-recommend"),
+    path("plan-from-text/", PlanFromTextView.as_view(), name="fertilization-plan-from-text"),
+]

fertilization/views.py

@@ -0,0 +1,525 @@
+"""
+Fertilization Recommendation API views.
+"""
+
+import logging
+
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import OpenApiParameter
+from rest_framework import serializers, status
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.response import Response
+from rest_framework.views import APIView
+from drf_spectacular.utils import extend_schema
+
+from config.swagger import code_response, status_response
+from external_api_adapter import request as external_api_request
+from farm_hub.models import FarmHub
+from .mock_data import CONFIG_RESPONSE_DATA
+from .models import FertilizationRecommendationRequest
+from .serializers import (
+    FreeTextPlanParserRequestSerializer,
+    FreeTextPlanParserResponseDataSerializer,
+    FertilizationRecommendationListItemSerializer,
+    FertilizationRecommendationListQuerySerializer,
+    FertilizationRecommendRequestSerializer,
+    FertilizationRecommendResponseDataSerializer,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class FertilizationRecommendationPagination(PageNumberPagination):
+    page_size = 10
+    page_size_query_param = "page_size"
+    max_page_size = 100
+
+    def get_paginated_response(self, data):
+        page_size = self.get_page_size(self.request) or self.page.paginator.per_page
+        return Response(
+            {
+                "code": 200,
+                "msg": "success",
+                "data": data,
+                "pagination": {
+                    "page": self.page.number,
+                    "page_size": page_size,
+                    "total_pages": self.page.paginator.num_pages,
+                    "total_items": self.page.paginator.count,
+                    "has_next": self.page.has_next(),
+                    "has_previous": self.page.has_previous(),
+                    "next": self.get_next_link(),
+                    "previous": self.get_previous_link(),
+                },
+            },
+            status=status.HTTP_200_OK,
+        )
+
+
+class FarmAccessMixin:
+    @staticmethod
+    def _get_farm(request, farm_uuid):
+        if not farm_uuid:
+            raise serializers.ValidationError({"farm_uuid": ["This field is required."]})
+        try:
+            return FarmHub.objects.get(farm_uuid=farm_uuid, owner=request.user)
+        except FarmHub.DoesNotExist as exc:
+            raise serializers.ValidationError({"farm_uuid": ["Farm not found."]}) from exc
+
+
+class ConfigView(FarmAccessMixin, APIView):
+    @extend_schema(
+        tags=["Fertilization Recommendation"],
+        responses={200: status_response("FertilizationConfigResponse", data=serializers.JSONField())},
+    )
+    def get(self, request):
+        farm = self._get_farm(request, request.query_params.get("farm_uuid"))
+        data = dict(CONFIG_RESPONSE_DATA)
+        data["farm_uuid"] = str(farm.farm_uuid)
+        return Response({"status": "success", "data": data}, status=status.HTTP_200_OK)
+
+
+class RecommendView(FarmAccessMixin, APIView):
+    @staticmethod
+    def _to_string(value):
+        if value is None:
+            return ""
+        return str(value)
+
+    @staticmethod
+    def _to_float(value):
+        if value in (None, ""):
+            return None
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return None
+
+    @staticmethod
+    def _to_int(value):
+        if value in (None, ""):
+            return None
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    @staticmethod
+    def _normalize_sections(raw_sections):
+        if not isinstance(raw_sections, list):
+            return []
+
+        allowed_keys = {
+            "type",
+            "title",
+            "icon",
+            "content",
+            "items",
+            "fertilizerType",
+            "amount",
+            "applicationMethod",
+            "timing",
+            "validityPeriod",
+            "expandableExplanation",
+        }
+
+        normalized_sections = []
+        for section in raw_sections:
+            if not isinstance(section, dict) or not section.get("type"):
+                continue
+
+            normalized_section = {}
+            for key in allowed_keys:
+                value = section.get(key)
+                if value is None:
+                    continue
+                if key == "items":
+                    if not isinstance(value, list):
+                        continue
+                    normalized_section[key] = [str(item) for item in value]
+                    continue
+                normalized_section[key] = str(value) if key != "type" else value
+
+            normalized_sections.append(normalized_section)
+        return normalized_sections
+
+    @staticmethod
+    def _extract_public_payload(adapter_data):
+        if not isinstance(adapter_data, dict):
+            return {}
+
+        data = adapter_data.get("data")
+        if isinstance(data, dict):
+            result = data.get("result")
+            if isinstance(result, dict):
+                return result
+            return data
+
+        result = adapter_data.get("result")
+        if isinstance(result, dict):
+            return result
+
+        return adapter_data
+
+    def _normalize_npk_ratio(self, raw_ratio):
+        if not isinstance(raw_ratio, dict):
+            return {}
+
+        normalized = {}
+        for key in ("n", "p", "k"):
+            numeric_value = self._to_float(raw_ratio.get(key))
+            if numeric_value is not None:
+                normalized[key] = numeric_value
+
+        label = self._to_string(raw_ratio.get("label")).strip()
+        if label:
+            normalized["label"] = label
+
+        return normalized
+
+    def _normalize_named_object(self, raw_object):
+        if not isinstance(raw_object, dict):
+            return {}
+
+        normalized = {}
+        for key in ("id", "label", "unit", "calculation_basis"):
+            value = self._to_string(raw_object.get(key)).strip()
+            if value:
+                normalized[key] = value
+
+        for key in ("value", "base_amount_per_hectare", "base_amount_per_square_meter"):
+            numeric_value = self._to_float(raw_object.get(key))
+            if numeric_value is not None:
+                normalized[key] = numeric_value
+
+        return normalized
+
+    @staticmethod
+    def _first_non_empty(*values):
+        for value in values:
+            if value is None:
+                continue
+            text = str(value).strip()
+            if text:
+                return text
+        return ""
+
+    def _normalize_primary_recommendation(self, payload):
+        raw_data = payload.get("primary_recommendation")
+        if not isinstance(raw_data, dict):
+            raw_data = {}
+
+        normalized = {}
+        scalar_fields = {
+            "fertilizer_code": (
+                raw_data.get("fertilizer_code"),
+                payload.get("fertilizer_code"),
+            ),
+            "fertilizer_name": (
+                raw_data.get("fertilizer_name"),
+                payload.get("fertilizer_name"),
+            ),
+            "display_title": (
+                raw_data.get("display_title"),
+                payload.get("display_title"),
+            ),
+            "fertilizer_type": (
+                raw_data.get("fertilizer_type"),
+                payload.get("fertilizer_type"),
+            ),
+            "reasoning": (
+                raw_data.get("reasoning"),
+                payload.get("reasoning"),
+            ),
+            "summary": (
+                raw_data.get("summary"),
+                payload.get("summary"),
+            ),
+        }
+        for key, values in scalar_fields.items():
+            value = self._first_non_empty(*values)
+            if value:
+                normalized[key] = value
+
+        npk_ratio = self._normalize_npk_ratio(raw_data.get("npk_ratio"))
+        if npk_ratio:
+            normalized["npk_ratio"] = npk_ratio
+
+        application_method = self._normalize_named_object(raw_data.get("application_method"))
+        if application_method:
+            normalized["application_method"] = {
+                key: value for key, value in application_method.items() if key in {"id", "label"}
+            }
+
+        application_interval = self._normalize_named_object(raw_data.get("application_interval"))
+        if application_interval:
+            normalized["application_interval"] = {
+                key: value for key, value in application_interval.items() if key in {"value", "unit", "label"}
+            }
+
+        dosage = self._normalize_named_object(raw_data.get("dosage"))
+        if dosage:
+            dosage_label = self._to_string(raw_data.get("dosage", {}).get("label")).strip()
+            if dosage_label:
+                dosage["label"] = dosage_label
+            normalized["dosage"] = {
+                key: value
+                for key, value in dosage.items()
+                if key in {"base_amount_per_hectare", "base_amount_per_square_meter", "unit", "label", "calculation_basis"}
+            }
+
+        return normalized
+
+    def _normalize_nutrient_items(self, items):
+        if not isinstance(items, list):
+            return []
+
+        normalized_items = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            normalized_item = {}
+            for key in ("key", "name", "unit", "description"):
+                value = self._to_string(item.get(key)).strip()
+                if value:
+                    normalized_item[key] = value
+            numeric_value = self._to_float(item.get("value"))
+            if numeric_value is not None:
+                normalized_item["value"] = numeric_value
+            if normalized_item:
+                normalized_items.append(normalized_item)
+        return normalized_items
+
+    def _normalize_application_guide(self, payload):
+        raw_data = payload.get("application_guide")
+        if not isinstance(raw_data, dict):
+            return {}
+
+        normalized = {}
+        safety_warning = self._to_string(raw_data.get("safety_warning")).strip()
+        if safety_warning:
+            normalized["safety_warning"] = safety_warning
+
+        raw_steps = raw_data.get("steps")
+        if isinstance(raw_steps, list):
+            steps = []
+            for step in raw_steps:
+                if not isinstance(step, dict):
+                    continue
+                normalized_step = {}
+                step_number = self._to_int(step.get("step_number"))
+                if step_number is not None:
+                    normalized_step["step_number"] = step_number
+                for key in ("title", "description"):
+                    value = self._to_string(step.get(key)).strip()
+                    if value:
+                        normalized_step[key] = value
+                if normalized_step:
+                    steps.append(normalized_step)
+            normalized["steps"] = steps
+
+        return normalized
+
+    def _normalize_alternatives(self, payload):
+        raw_items = payload.get("alternative_recommendations")
+        if not isinstance(raw_items, list):
+            return []
+
+        alternatives = []
+        for item in raw_items:
+            if not isinstance(item, dict):
+                continue
+            normalized_item = {}
+            for key in ("fertilizer_code", "fertilizer_name", "fertilizer_type", "usage_method", "description"):
+                value = self._to_string(item.get(key)).strip()
+                if value:
+                    normalized_item[key] = value
+            if normalized_item:
+                alternatives.append(normalized_item)
+        return alternatives
+
+    def _normalize_response_payload(self, adapter_data):
+        payload = self._extract_public_payload(adapter_data)
+        if not isinstance(payload, dict):
+            payload = {}
+
+        normalized_sections = self._normalize_sections(payload.get("sections"))
+        nutrient_analysis = payload.get("nutrient_analysis") if isinstance(payload.get("nutrient_analysis"), dict) else {}
+
+        return {
+            "primary_recommendation": self._normalize_primary_recommendation(payload),
+            "nutrient_analysis": {
+                "macro": self._normalize_nutrient_items(nutrient_analysis.get("macro")),
+                "micro": self._normalize_nutrient_items(nutrient_analysis.get("micro")),
+            },
+            "application_guide": self._normalize_application_guide(payload),
+            "alternative_recommendations": self._normalize_alternatives(payload),
+            "sections": normalized_sections,
+        }
+
+    @extend_schema(
+        tags=["Fertilization Recommendation"],
+        request=FertilizationRecommendRequestSerializer,
+        responses={200: code_response("FertilizationRecommendResponse", data=FertilizationRecommendResponseDataSerializer())},
+    )
+    def post(self, request):
+        serializer = FertilizationRecommendRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        payload = serializer.validated_data.copy()
+        farm = self._get_farm(request, payload.get("farm_uuid"))
+        crop_id = self._first_non_empty(payload.get("crop_id"), payload.get("plant_name"))
+        plant_name = self._first_non_empty(payload.get("plant_name"), payload.get("crop_id"))
+        payload["farm_uuid"] = str(farm.farm_uuid)
+        payload["crop_id"] = crop_id
+        payload["plant_name"] = plant_name
+        payload["growth_stage"] = payload.get("growth_stage", "")
+
+        adapter_response = external_api_request(
+            "ai",
+            "/api/fertilization/recommend/",
+            method="POST",
+            payload=payload,
+        )
+
+        response_data = adapter_response.data if isinstance(adapter_response.data, dict) else {}
+        public_data = self._normalize_response_payload(response_data)
+
+        logger.warning(
+            "Fertilization recommendation response parsed: farm_uuid=%s status_code=%s response_keys=%s sections_count=%s",
+            str(farm.farm_uuid),
+            adapter_response.status_code,
+            sorted(response_data.keys()) if isinstance(response_data, dict) else None,
+            len(public_data.get("sections", [])),
+        )
+
+        FertilizationRecommendationRequest.objects.create(
+            farm=farm,
+            crop_id=crop_id,
+            growth_stage=payload.get("growth_stage", ""),
+            task_id="",
+            status=FertilizationRecommendationRequest.STATUS_PENDING_CONFIRMATION,
+            request_payload=payload,
+            response_payload=adapter_response.data if isinstance(adapter_response.data, dict) else {"raw": adapter_response.data},
+        )
+        if adapter_response.status_code >= 400:
+            return Response(
+                {
+                    "code": adapter_response.status_code,
+                    "msg": "error",
+                    "data": response_data if isinstance(response_data, dict) else {"message": str(adapter_response.data)},
+                },
+                status=adapter_response.status_code,
+            )
+
+        return Response(
+            {
+                "code": 200,
+                "msg": "success",
+                "data": public_data,
+            },
+            status=status.HTTP_200_OK,
+        )
+
+
+class RecommendationListView(FarmAccessMixin, APIView):
+    permission_classes = RecommendView.permission_classes
+    pagination_class = FertilizationRecommendationPagination
+
+    @extend_schema(
+        tags=["Fertilization Recommendation"],
+        parameters=[FertilizationRecommendationListQuerySerializer],
+        responses={200: code_response("FertilizationRecommendationListResponse")},
+    )
+    def get(self, request):
+        serializer = FertilizationRecommendationListQuerySerializer(data=request.query_params)
+        serializer.is_valid(raise_exception=True)
+
+        farm = self._get_farm(request, serializer.validated_data["farm_uuid"])
+        recommendations = farm.fertilizations.all().order_by("-created_at", "-id")
+
+        paginator = self.pagination_class()
+        page = paginator.paginate_queryset(recommendations, request, view=self)
+
+        items = []
+        view_helper = RecommendView()
+        for recommendation in page:
+            normalized_payload = view_helper._normalize_response_payload(recommendation.response_payload)
+            recommendation.fertilizer_type = (
+                normalized_payload.get("primary_recommendation", {}).get("fertilizer_type", "")
+            )
+            items.append(recommendation)
+
+        data = FertilizationRecommendationListItemSerializer(items, many=True).data
+        return paginator.get_paginated_response(data)
+
+
+class RecommendationDetailView(FarmAccessMixin, APIView):
+    @extend_schema(
+        tags=["Fertilization Recommendation"],
+        parameters=[
+            OpenApiParameter(
+                name="recommendation_uuid",
+                type=OpenApiTypes.UUID,
+                location=OpenApiParameter.PATH,
+                required=True,
+            )
+        ],
+        responses={
+            200: code_response("FertilizationRecommendationDetailResponse", data=FertilizationRecommendResponseDataSerializer()),
+            404: code_response("FertilizationRecommendationDetailNotFoundResponse"),
+        },
+    )
+    def get(self, request, recommendation_uuid):
+        recommendation = FertilizationRecommendationRequest.objects.filter(
+            uuid=recommendation_uuid,
+            farm__owner=request.user,
+        ).select_related("farm").first()
+        if recommendation is None:
+            return Response({"code": 404, "msg": "Recommendation not found."}, status=status.HTTP_404_NOT_FOUND)
+
+        view_helper = RecommendView()
+        data = view_helper._normalize_response_payload(recommendation.response_payload)
+        data["recommendation_uuid"] = str(recommendation.uuid)
+        data["crop_id"] = recommendation.crop_id
+        data["plant_name"] = recommendation.crop_id
+        data["growth_stage"] = recommendation.growth_stage
+        data["status"] = recommendation.status
+        data["status_label"] = recommendation.get_status_display()
+        return Response({"code": 200, "msg": "success", "data": data}, status=status.HTTP_200_OK)
+
+
+class PlanFromTextView(FarmAccessMixin, APIView):
+    @extend_schema(
+        tags=["Fertilization Recommendation"],
+        request=FreeTextPlanParserRequestSerializer,
+        responses={200: code_response("FertilizationPlanFromTextResponse", data=FreeTextPlanParserResponseDataSerializer())},
+    )
+    def post(self, request):
+        serializer = FreeTextPlanParserRequestSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        payload = serializer.validated_data.copy()
+
+        farm_uuid = payload.get("farm_uuid")
+        if farm_uuid:
+            farm = self._get_farm(request, farm_uuid)
+            payload["farm_uuid"] = str(farm.farm_uuid)
+
+        adapter_response = external_api_request(
+            "ai",
+            "/api/fertilization/plan-from-text/",
+            method="POST",
+            payload=payload,
+        )
+
+        response_data = adapter_response.data if isinstance(adapter_response.data, dict) else {"message": str(adapter_response.data)}
+        if adapter_response.status_code >= 400:
+            return Response(
+                {"code": adapter_response.status_code, "msg": "error", "data": response_data},
+                status=adapter_response.status_code,
+            )
+
+        return Response(
+            {"code": 200, "msg": response_data.get("msg", "موفق"), "data": response_data.get("data", response_data)},
+            status=status.HTTP_200_OK,
+        )