UPDATE

Modules/Ai/plant/PLANT_NAMES_API.md

@@ -0,0 +1,74 @@
+# Plant Names API
+
+این API فقط لیست نام گیاه‌ها را به همراه آیکون و مراحل رشد برمی‌گرداند.
+
+## Endpoint
+
+- `GET /api/plants/names/`
+
+## کاربرد
+
+- گرفتن لیست سبک برای dropdown یا selector فرانت
+- نمایش نام گیاه
+- نمایش `icon`
+- نمایش مراحل رشد هر گیاه
+
+## رفتار API
+
+- فقط فیلدهای `name`، `icon` و `growth_stages` را برمی‌گرداند
+- اگر `growth_stage` برای یک گیاه خالی باشد، API به صورت خودکار این مراحل پیش‌فرض را اضافه و در دیتابیس ذخیره می‌کند:
+  - `initial`
+  - `vegetative`
+  - `flowering`
+  - `fruiting`
+  - `maturity`
+- اگر `icon` خالی باشد، مقدار پیش‌فرض `leaf` ذخیره و برگردانده می‌شود
+- اگر در `growth_profile.stage_thresholds` مرحله‌ای وجود داشته باشد، آن مرحله هم در خروجی `growth_stages` لحاظ می‌شود
+
+## نمونه درخواست
+
+```bash
+curl -X GET http://localhost:8000/api/plants/names/
+```
+
+## نمونه پاسخ
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": [
+    {
+      "name": "Tomato",
+      "icon": "leaf",
+      "growth_stages": [
+        "vegetative",
+        "flowering",
+        "fruiting"
+      ]
+    },
+    {
+      "name": "Pepper",
+      "icon": "leaf",
+      "growth_stages": [
+        "initial",
+        "vegetative",
+        "flowering",
+        "fruiting",
+        "maturity"
+      ]
+    }
+  ]
+}
+```
+
+## فیلدهای خروجی
+
+- `name`: نام گیاه
+- `icon`: آیکون گیاه برای فرانت
+- `growth_stages`: آرایه‌ای از مراحل رشد گیاه
+
+## نکته برای فرانت
+
+- این endpoint برای لیست سبک طراحی شده و مناسب صفحه‌های انتخاب گیاه است
+- اگر جزئیات کامل گیاه لازم دارید، از `GET /api/plants/` یا `GET /api/plants/{id}/` استفاده کنید

Modules/Ai/plant/__init__.py

@@ -0,0 +1 @@
+

Modules/Ai/plant/admin.py

@@ -0,0 +1,19 @@
+from django.contrib import admin
+
+from .models import Plant
+
+
+@admin.register(Plant)
+class PlantAdmin(admin.ModelAdmin):
+    list_display = (
+        "id",
+        "name",
+        "light",
+        "soil",
+        "temperature",
+        "planting_season",
+        "created_at",
+    )
+    list_filter = ("planting_season",)
+    search_fields = ("name",)
+    readonly_fields = ("created_at", "updated_at")

Modules/Ai/plant/apps.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import re
+from functools import cached_property
+
+from django.apps import AppConfig
+
+
+class PlantConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "plant"
+    verbose_name = "Plant"
+
+    @cached_property
+    def plant_aliases(self) -> dict[str, str]:
+        return {
+            "tomato": "گوجه‌فرنگی",
+            "cucumber": "خیار",
+            "pepper": "فلفل دلمه‌ای",
+            "bell pepper": "فلفل دلمه‌ای",
+            "carrot": "هویج",
+            "lettuce": "کاهو",
+            "potato": "سیب‌زمینی",
+            "onion": "پیاز",
+        }
+
+    @cached_property
+    def growth_stage_aliases(self) -> dict[str, str]:
+        return {
+            "initial": "initial",
+            "seedling": "initial",
+            "establishment": "initial",
+            "جوانه زنی": "initial",
+            "جوانه‌زنی": "initial",
+            "نشا": "initial",
+            "استقرار": "initial",
+            "vegetative": "vegetative",
+            "growth": "vegetative",
+            "رویشی": "vegetative",
+            "رشد رویشی": "vegetative",
+            "flowering": "flowering",
+            "anthesis": "flowering",
+            "گلدهی": "flowering",
+            "گل دهی": "flowering",
+            "fruiting": "fruiting",
+            "harvest": "fruiting",
+            "ripening": "fruiting",
+            "میوه دهی": "fruiting",
+            "میوه‌دهی": "fruiting",
+            "برداشت": "fruiting",
+            "maturity": "maturity",
+            "رسیدگی": "maturity",
+            "بلوغ": "maturity",
+        }
+
+    def _normalize_lookup_value(self, value: str | None) -> str:
+        text = (value or "").strip().lower()
+        if not text:
+            return ""
+
+        translation_table = str.maketrans(
+            {
+                "ي": "ی",
+                "ك": "ک",
+                "ة": "ه",
+                "أ": "ا",
+                "إ": "ا",
+                "ؤ": "و",
+                "ۀ": "ه",
+                "‌": " ",
+                "-": " ",
+                "_": " ",
+            }
+        )
+        text = text.translate(translation_table)
+        text = re.sub(r"\s+", " ", text)
+        return text.strip()
+
+    def resolve_growth_stage(self, growth_stage: str | None) -> str | None:
+        value = (growth_stage or "").strip()
+        if not value:
+            return value
+
+        normalized = self._normalize_lookup_value(value)
+        return self.growth_stage_aliases.get(normalized, value)
+
+    def resolve_plant_name(self, plant_name: str | None) -> str | None:
+        from .models import Plant
+
+        value = (plant_name or "").strip()
+        if not value:
+            return value
+
+        plant = Plant.objects.filter(name=value).first() or Plant.objects.filter(name__iexact=value).first()
+        if plant is not None:
+            return plant.name
+
+        normalized = self._normalize_lookup_value(value)
+        alias_target = self.plant_aliases.get(normalized)
+        if alias_target:
+            aliased_plant = Plant.objects.filter(name=alias_target).first()
+            if aliased_plant is not None:
+                return aliased_plant.name
+
+        for plant in Plant.objects.only("name").iterator():
+            if self._normalize_lookup_value(plant.name) == normalized:
+                return plant.name
+
+        return value

Modules/Ai/plant/gdd.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+from typing import Any
+
+
+DEFAULT_GROWTH_PROFILE = {
+    "base_temperature": 10.0,
+    "required_gdd_for_maturity": 1200.0,
+    "stage_thresholds": {
+        "flowering": 500.0,
+        "fruiting": 850.0,
+    },
+    "current_cumulative_gdd": 0.0,
+}
+
+
+@dataclass
+class HarvestPrediction:
+    current_cumulative_gdd: float
+    required_gdd_for_maturity: float
+    remaining_gdd: float
+    estimated_days_to_harvest: int
+    predicted_harvest_date: str
+    predicted_harvest_window: dict[str, str]
+    daily_gdd_forecast: list[dict[str, float | str]]
+    active_stage: str | None
+
+
+def resolve_growth_profile(plant: Any | None) -> dict:
+    profile = getattr(plant, "growth_profile", None) or {}
+    stage_thresholds = {
+        **DEFAULT_GROWTH_PROFILE["stage_thresholds"],
+        **profile.get("stage_thresholds", {}),
+    }
+    return {
+        **DEFAULT_GROWTH_PROFILE,
+        **profile,
+        "stage_thresholds": stage_thresholds,
+    }
+
+
+def calculate_daily_gdd(tmax: float, tmin: float, tbase: float) -> float:
+    mean_temp = (tmax + tmin) / 2.0
+    return round(max(mean_temp - tbase, 0.0), 3)
+
+
+def determine_active_stage(current_cumulative_gdd: float, stage_thresholds: dict[str, float]) -> str | None:
+    active_stage = None
+    for stage, threshold in sorted(stage_thresholds.items(), key=lambda item: item[1]):
+        if current_cumulative_gdd >= float(threshold):
+            active_stage = stage
+    return active_stage
+
+
+def predict_harvest_from_forecasts(
+    forecasts: list[Any],
+    plant: Any | None,
+) -> HarvestPrediction:
+    profile = resolve_growth_profile(plant)
+    base_temperature = float(profile.get("base_temperature", DEFAULT_GROWTH_PROFILE["base_temperature"]))
+    required_gdd = float(profile.get("required_gdd_for_maturity", DEFAULT_GROWTH_PROFILE["required_gdd_for_maturity"]))
+    current_cumulative_gdd = float(profile.get("current_cumulative_gdd", DEFAULT_GROWTH_PROFILE["current_cumulative_gdd"]))
+
+    cumulative_gdd = current_cumulative_gdd
+    daily_forecast: list[dict[str, float | str]] = []
+    estimated_date = forecasts[-1].forecast_date if forecasts else date.today()
+
+    for forecast in forecasts:
+        tmax = float(getattr(forecast, "temperature_max", None) or getattr(forecast, "temperature_mean", 0.0))
+        tmin = float(getattr(forecast, "temperature_min", None) or getattr(forecast, "temperature_mean", 0.0))
+        daily_gdd = calculate_daily_gdd(tmax=tmax, tmin=tmin, tbase=base_temperature)
+        cumulative_gdd += daily_gdd
+        daily_forecast.append(
+            {
+                "date": forecast.forecast_date.isoformat(),
+                "gdd": daily_gdd,
+                "cumulative_gdd": round(cumulative_gdd, 3),
+            }
+        )
+        if cumulative_gdd >= required_gdd:
+            estimated_date = forecast.forecast_date
+            break
+    else:
+        remaining_gdd_after_forecast = max(required_gdd - cumulative_gdd, 0.0)
+        avg_gdd = sum(item["gdd"] for item in daily_forecast) / len(daily_forecast) if daily_forecast else 0.0
+        extra_days = int(remaining_gdd_after_forecast / avg_gdd) + (1 if avg_gdd > 0 and remaining_gdd_after_forecast > 0 else 0)
+        estimated_date = estimated_date + timedelta(days=max(extra_days, 0))
+
+    remaining_gdd = max(required_gdd - current_cumulative_gdd, 0.0)
+    estimated_days = max((estimated_date - date.today()).days, 0)
+    active_stage = determine_active_stage(current_cumulative_gdd, profile.get("stage_thresholds", {}))
+
+    return HarvestPrediction(
+        current_cumulative_gdd=round(current_cumulative_gdd, 3),
+        required_gdd_for_maturity=round(required_gdd, 3),
+        remaining_gdd=round(remaining_gdd, 3),
+        estimated_days_to_harvest=estimated_days,
+        predicted_harvest_date=estimated_date.isoformat(),
+        predicted_harvest_window={
+            "start": (estimated_date - timedelta(days=3)).isoformat(),
+            "end": (estimated_date + timedelta(days=3)).isoformat(),
+        },
+        daily_gdd_forecast=daily_forecast,
+        active_stage=active_stage,
+    )

Modules/Ai/plant/management/__init__.py

@@ -0,0 +1 @@
+

Modules/Ai/plant/management/commands/__init__.py

@@ -0,0 +1 @@
+

Modules/Ai/plant/management/commands/seed_plants.py

@@ -0,0 +1,109 @@
+"""
+Management command to seed initial plant data.
+Run: python manage.py seed_plants
+"""
+
+from django.core.management.base import BaseCommand
+
+from plant.models import Plant
+
+
+INITIAL_PLANTS = [
+    {
+        "name": "گوجه‌فرنگی",
+        "light": "آفتاب کامل (۶-۸ ساعت)",
+        "watering": "منظم، هفته‌ای ۲-۳ بار",
+        "soil": "لومی، غنی از مواد آلی، pH بین ۶-۶.۸",
+        "temperature": "۲۰-۳۰ درجه سانتی‌گراد",
+        "planting_season": "بهار",
+        "harvest_time": "۷۰-۹۰ روز پس از کاشت",
+        "spacing": "۴۵-۶۰ سانتی‌متر",
+        "fertilizer": "کود NPK متعادل، کمپوست",
+    },
+    {
+        "name": "خیار",
+        "light": "آفتاب کامل",
+        "watering": "روزانه در فصل گرم",
+        "soil": "لومی شنی، غنی از هوموس",
+        "temperature": "۱۸-۳۰ درجه سانتی‌گراد",
+        "planting_season": "بهار تا اوایل تابستان",
+        "harvest_time": "۵۰-۷۰ روز پس از کاشت",
+        "spacing": "۳۰-۴۵ سانتی‌متر",
+        "fertilizer": "کود ازته، کمپوست",
+    },
+    {
+        "name": "فلفل دلمه‌ای",
+        "light": "آفتاب کامل (۶-۸ ساعت)",
+        "watering": "منظم، هفته‌ای ۲-۳ بار",
+        "soil": "لومی، زهکشی مناسب",
+        "temperature": "۲۰-۳۰ درجه سانتی‌گراد",
+        "planting_season": "بهار",
+        "harvest_time": "۶۰-۹۰ روز پس از کاشت",
+        "spacing": "۴۰-۵۰ سانتی‌متر",
+        "fertilizer": "کود فسفره و پتاسه",
+    },
+    {
+        "name": "هویج",
+        "light": "آفتاب کامل تا نیمه‌سایه",
+        "watering": "منظم، خاک مرطوب",
+        "soil": "شنی لومی، عمیق، بدون سنگ",
+        "temperature": "۱۵-۲۵ درجه سانتی‌گراد",
+        "planting_season": "اوایل بهار یا پاییز",
+        "harvest_time": "۷۰-۸۰ روز پس از کاشت",
+        "spacing": "۵-۸ سانتی‌متر",
+        "fertilizer": "کود پتاسه، کمپوست پوسیده",
+    },
+    {
+        "name": "کاهو",
+        "light": "نیمه‌سایه تا آفتاب کامل",
+        "watering": "منظم، خاک مرطوب",
+        "soil": "لومی، غنی از مواد آلی",
+        "temperature": "۱۰-۲۰ درجه سانتی‌گراد",
+        "planting_season": "بهار و پاییز",
+        "harvest_time": "۴۵-۶۰ روز پس از کاشت",
+        "spacing": "۲۰-۳۰ سانتی‌متر",
+        "fertilizer": "کود ازته، کمپوست",
+    },
+    {
+        "name": "سیب‌زمینی",
+        "light": "آفتاب کامل",
+        "watering": "منظم، هفته‌ای ۲ بار",
+        "soil": "لومی شنی، اسیدی ملایم، pH بین ۵-۶",
+        "temperature": "۱۵-۲۲ درجه سانتی‌گراد",
+        "planting_season": "اواخر زمستان تا اوایل بهار",
+        "harvest_time": "۹۰-۱۲۰ روز پس از کاشت",
+        "spacing": "۳۰-۴۰ سانتی‌متر",
+        "fertilizer": "کود NPK، کمپوست",
+    },
+    {
+        "name": "پیاز",
+        "light": "آفتاب کامل",
+        "watering": "منظم، خاک مرطوب ولی نه غرقابی",
+        "soil": "لومی، زهکشی خوب",
+        "temperature": "۱۲-۲۴ درجه سانتی‌گراد",
+        "planting_season": "پاییز یا اوایل بهار",
+        "harvest_time": "۹۰-۱۵۰ روز پس از کاشت",
+        "spacing": "۱۰-۱۵ سانتی‌متر",
+        "fertilizer": "کود فسفره، سولفات پتاسیم",
+    },
+]
+
+
+class Command(BaseCommand):
+    help = "Seed initial plant data (7 common vegetables)"
+
+    def handle(self, *args, **options):
+        created_count = 0
+        for plant_data in INITIAL_PLANTS:
+            _, created = Plant.objects.get_or_create(
+                name=plant_data["name"],
+                defaults=plant_data,
+            )
+            if created:
+                created_count += 1
+                self.stdout.write(
+                    self.style.SUCCESS(f"  Created: {plant_data['name']}")
+                )
+        self.stdout.write(
+            self.style.SUCCESS(f"\nDone. Created {created_count} new plants.")
+        )

Modules/Ai/plant/migrations/0001_initial.py

@@ -0,0 +1,36 @@
+# Generated by Django 5.2.12 on 2026-03-19 15:01
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Plant',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(db_index=True, help_text='نام گیاه', max_length=255, unique=True)),
+                ('light', models.CharField(blank=True, help_text='نور مورد نیاز', max_length=255)),
+                ('watering', models.CharField(blank=True, help_text='آبیاری', max_length=255)),
+                ('soil', models.CharField(blank=True, help_text='خاک مناسب', max_length=255)),
+                ('temperature', models.CharField(blank=True, help_text='دمای مناسب', max_length=255)),
+                ('planting_season', models.CharField(blank=True, help_text='فصل کاشت', max_length=255)),
+                ('harvest_time', models.CharField(blank=True, help_text='زمان برداشت', max_length=255)),
+                ('spacing', models.CharField(blank=True, help_text='فاصله کاشت', max_length=255)),
+                ('fertilizer', models.CharField(blank=True, help_text='کود مناسب', max_length=255)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+            ],
+            options={
+                'verbose_name': 'گیاه',
+                'verbose_name_plural': 'گیاهان',
+                'ordering': ['name'],
+            },
+        ),
+    ]

Modules/Ai/plant/migrations/0002_plant_health_profile.py

@@ -0,0 +1,23 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("plant", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="plant",
+            name="health_profile",
+            field=models.JSONField(
+                blank=True,
+                default=dict,
+                help_text=(
+                    "پروفایل سلامت گیاه برای KPIها. ساختار نمونه: "
+                    '{"moisture": {"ideal_value": 65, "min_range": 45, "max_range": 75, "weight": 0.4}}'
+                ),
+            ),
+        ),
+    ]

Modules/Ai/plant/migrations/0003_plant_irrigation_profile.py

@@ -0,0 +1,24 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("plant", "0002_plant_health_profile"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="plant",
+            name="irrigation_profile",
+            field=models.JSONField(
+                blank=True,
+                default=dict,
+                help_text=(
+                    "پروفایل آبیاری گیاه برای محاسبات ETc. "
+                    'نمونه: {"kc_initial": 0.6, "kc_mid": 1.15, "kc_end": 0.8, '
+                    '"growth_stage_duration": {"initial": 20, "mid": 30, "late": 25}}'
+                ),
+            ),
+        ),
+    ]

Modules/Ai/plant/migrations/0004_plant_growth_profile.py

@@ -0,0 +1,24 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("plant", "0003_plant_irrigation_profile"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="plant",
+            name="growth_profile",
+            field=models.JSONField(
+                blank=True,
+                default=dict,
+                help_text=(
+                    "پروفایل رشد گیاه برای مدل GDD. "
+                    'نمونه: {"base_temperature": 10, "required_gdd_for_maturity": 1200, '
+                    '"stage_thresholds": {"flowering": 500, "fruiting": 850}, "current_cumulative_gdd": 320}'
+                ),
+            ),
+        ),
+    ]

Modules/Ai/plant/migrations/0005_plant_growth_stage.py

@@ -0,0 +1,20 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("plant", "0004_plant_growth_profile"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="plant",
+            name="growth_stage",
+            field=models.CharField(
+                blank=True,
+                help_text="مرحله رشد",
+                max_length=255,
+            ),
+        ),
+    ]

Modules/Ai/plant/migrations/0006_plant_icon.py

@@ -0,0 +1,20 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("plant", "0005_plant_growth_stage"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="plant",
+            name="icon",
+            field=models.CharField(
+                blank=True,
+                default="leaf",
+                help_text="آیکون گیاه برای نمایش در فرانت",
+                max_length=255,
+            ),
+        ),
+    ]

Modules/Ai/plant/migrations/__init__.py

@@ -0,0 +1 @@
+

Modules/Ai/plant/models.py

@@ -0,0 +1,101 @@
+from django.db import models
+
+
+class Plant(models.Model):
+    """
+    اطلاعات گیاهان شامل شرایط نگهداری و کاشت.
+    """
+
+    name = models.CharField(
+        max_length=255,
+        unique=True,
+        db_index=True,
+        help_text="نام گیاه",
+    )
+    icon = models.CharField(
+        max_length=255,
+        blank=True,
+        default="leaf",
+        help_text="آیکون گیاه برای نمایش در فرانت",
+    )
+    light = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="نور مورد نیاز",
+    )
+    watering = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="آبیاری",
+    )
+    soil = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="خاک مناسب",
+    )
+    temperature = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="دمای مناسب",
+    )
+    growth_stage = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="مرحله رشد",
+    )
+    planting_season = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="فصل کاشت",
+    )
+    harvest_time = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="زمان برداشت",
+    )
+    spacing = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="فاصله کاشت",
+    )
+    fertilizer = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="کود مناسب",
+    )
+    health_profile = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text=(
+            "پروفایل سلامت گیاه برای KPIها. ساختار نمونه: "
+            '{"moisture": {"ideal_value": 65, "min_range": 45, "max_range": 75, "weight": 0.4}}'
+        ),
+    )
+    irrigation_profile = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text=(
+            "پروفایل آبیاری گیاه برای محاسبات ETc. "
+            'نمونه: {"kc_initial": 0.6, "kc_mid": 1.15, "kc_end": 0.8, '
+            '"growth_stage_duration": {"initial": 20, "mid": 30, "late": 25}}'
+        ),
+    )
+    growth_profile = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text=(
+            "پروفایل رشد گیاه برای مدل GDD. "
+            'نمونه: {"base_temperature": 10, "required_gdd_for_maturity": 1200, '
+            '"stage_thresholds": {"flowering": 500, "fruiting": 850}, "current_cumulative_gdd": 320}'
+        ),
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["name"]
+        verbose_name = "گیاه"
+        verbose_name_plural = "گیاهان"
+
+    def __str__(self):
+        return self.name

Modules/Ai/plant/serializers.py

@@ -0,0 +1,64 @@
+from rest_framework import serializers
+
+from .models import Plant
+
+
+DEFAULT_PLANT_GROWTH_STAGES = [
+    "initial",
+    "vegetative",
+    "flowering",
+    "fruiting",
+    "maturity",
+]
+
+
+def normalize_growth_stage_values(plant: Plant) -> list[str]:
+    stages: list[str] = []
+
+    raw_stage = (plant.growth_stage or "").replace("،", ",")
+    for part in raw_stage.split(","):
+        value = part.strip()
+        if value and value not in stages:
+            stages.append(value)
+
+    stage_thresholds = plant.growth_profile.get("stage_thresholds", {})
+    if isinstance(stage_thresholds, dict):
+        for stage_name in stage_thresholds.keys():
+            value = str(stage_name).strip()
+            if value and value not in stages:
+                stages.append(value)
+
+    if not stages:
+        stages = list(DEFAULT_PLANT_GROWTH_STAGES)
+
+    return stages
+
+
+class PlantSerializer(serializers.ModelSerializer):
+    """سریالایزر خروجی / ورودی برای Plant."""
+
+    class Meta:
+        model = Plant
+        fields = [
+            "id",
+            "name",
+            "icon",
+            "light",
+            "watering",
+            "soil",
+            "temperature",
+            "growth_stage",
+            "planting_season",
+            "harvest_time",
+            "spacing",
+            "fertilizer",
+            "created_at",
+            "updated_at",
+        ]
+        read_only_fields = ["id", "created_at", "updated_at"]
+
+
+class PlantNameStageSerializer(serializers.Serializer):
+    name = serializers.CharField()
+    icon = serializers.CharField()
+    growth_stages = serializers.ListField(child=serializers.CharField())

Modules/Ai/plant/services.py

@@ -0,0 +1,34 @@
+"""
+سرویس‌های گیاه — دریافت مشخصات گیاه از API خارجی بر اساس نام.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def fetch_plant_info_from_api(plant_name: str) -> dict | None:
+    """
+    اتصال به API خارجی و دریافت مشخصات گیاه بر اساس نام.
+
+    TODO: پیاده‌سازی اتصال واقعی به API.
+    در حال حاضر این تابع خالی است و None برمی‌گرداند.
+
+    پارامترها:
+        plant_name: نام گیاه
+
+    خروجی مورد انتظار (وقتی پیاده‌سازی شود):
+        {
+            "name": "گوجه‌فرنگی",
+            "light": "آفتاب کامل",
+            "watering": "منظم، هفته‌ای ۲-۳ بار",
+            "soil": "لومی، غنی از مواد آلی",
+            "temperature": "۲۰-۳۰ درجه سانتی‌گراد",
+            "planting_season": "بهار",
+            "harvest_time": "۷۰-۹۰ روز پس از کاشت",
+            "spacing": "۴۵-۶۰ سانتی‌متر",
+            "fertilizer": "کود NPK متعادل",
+        }
+    """
+    # TODO: اتصال واقعی به API
+    return None

Modules/Ai/plant/urls.py

@@ -0,0 +1,15 @@
+from django.urls import path
+
+from .views import (
+    PlantDetailView,
+    PlantFetchInfoView,
+    PlantListCreateView,
+    PlantNameStageListView,
+)
+
+urlpatterns = [
+    path("", PlantListCreateView.as_view(), name="plant-list-create"),
+    path("names/", PlantNameStageListView.as_view(), name="plant-name-stage-list"),
+    path("<int:pk>/", PlantDetailView.as_view(), name="plant-detail"),
+    path("fetch-info/", PlantFetchInfoView.as_view(), name="plant-fetch-info"),
+]

Modules/Ai/plant/views.py

@@ -0,0 +1,364 @@
+from drf_spectacular.utils import (
+    OpenApiExample,
+    OpenApiResponse,
+    extend_schema,
+    inline_serializer,
+)
+from rest_framework import serializers as drf_serializers
+from rest_framework import status
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from config.openapi import build_envelope_serializer, build_response
+from .models import Plant
+from .serializers import (
+    PlantNameStageSerializer,
+    PlantSerializer,
+    normalize_growth_stage_values,
+)
+from .services import fetch_plant_info_from_api
+
+
+PlantListResponseSerializer = build_envelope_serializer(
+    "PlantListResponseSerializer",
+    PlantSerializer,
+    many=True,
+)
+PlantDetailResponseSerializer = build_envelope_serializer(
+    "PlantDetailResponseSerializer",
+    PlantSerializer,
+)
+PlantValidationErrorSerializer = build_envelope_serializer(
+    "PlantValidationErrorSerializer",
+    data_required=False,
+    allow_null=True,
+)
+PlantFetchInfoResponseSerializer = build_envelope_serializer(
+    "PlantFetchInfoResponseSerializer",
+    PlantSerializer,
+)
+PlantNameStageListResponseSerializer = build_envelope_serializer(
+    "PlantNameStageListResponseSerializer",
+    PlantNameStageSerializer,
+    many=True,
+)
+
+
+class PlantListCreateView(APIView):
+    """لیست تمام گیاهان و ایجاد گیاه جدید."""
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="لیست گیاهان",
+        description="لیست تمام گیاهان ذخیره‌شده را برمی‌گرداند.",
+        responses={
+            200: build_response(
+                PlantListResponseSerializer,
+                "لیست گیاهان ذخیره‌شده.",
+            ),
+        },
+    )
+    def get(self, request):
+        plants = Plant.objects.all()
+        serializer = PlantSerializer(plants, many=True)
+        return Response(
+            {"code": 200, "msg": "success", "data": serializer.data},
+            status=status.HTTP_200_OK,
+        )
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="ایجاد گیاه جدید",
+        description="یک گیاه جدید با مشخصات داده‌شده ایجاد می‌کند.",
+        request=PlantSerializer,
+        responses={
+            201: build_response(
+                PlantDetailResponseSerializer,
+                "گیاه جدید با موفقیت ایجاد شد.",
+            ),
+            400: build_response(
+                PlantValidationErrorSerializer,
+                "داده ورودی نامعتبر است.",
+            ),
+        },
+        examples=[
+            OpenApiExample(
+                "نمونه درخواست",
+                value={
+                    "name": "گوجه‌فرنگی",
+                    "light": "آفتاب کامل",
+                    "watering": "منظم، هفته‌ای ۲-۳ بار",
+                    "soil": "لومی، غنی از مواد آلی",
+                    "temperature": "۲۰-۳۰ درجه سانتی‌گراد",
+                    "growth_stage": "رشد رویشی",
+                    "planting_season": "بهار",
+                    "harvest_time": "۷۰-۹۰ روز پس از کاشت",
+                    "spacing": "۴۵-۶۰ سانتی‌متر",
+                    "fertilizer": "کود NPK متعادل",
+                },
+                request_only=True,
+            ),
+        ],
+    )
+    def post(self, request):
+        serializer = PlantSerializer(data=request.data)
+        if not serializer.is_valid():
+            return Response(
+                {"code": 400, "msg": "داده نامعتبر.", "data": serializer.errors},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        serializer.save()
+        return Response(
+            {"code": 201, "msg": "success", "data": serializer.data},
+            status=status.HTTP_201_CREATED,
+        )
+
+
+class PlantNameStageListView(APIView):
+    """لیست سبک از نام گیاه، آیکون و مراحل رشد."""
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="لیست نام گیاهان با مراحل رشد",
+        description=(
+            "فقط نام گیاه، آیکون و مراحل رشد را برمی‌گرداند. "
+            "اگر برای گیاهی مرحله رشد ثبت نشده باشد، مراحل پیش‌فرض به آن اضافه و ذخیره می‌شود."
+        ),
+        responses={
+            200: build_response(
+                PlantNameStageListResponseSerializer,
+                "لیست نام گیاهان به همراه مراحل رشد و آیکون.",
+            ),
+        },
+    )
+    def get(self, request):
+        payload = []
+        for plant in Plant.objects.all():
+            growth_stages = normalize_growth_stage_values(plant)
+            serialized_stages = ", ".join(growth_stages)
+            update_fields: list[str] = []
+
+            if plant.growth_stage != serialized_stages:
+                plant.growth_stage = serialized_stages
+                update_fields.append("growth_stage")
+            if not plant.icon:
+                plant.icon = "leaf"
+                update_fields.append("icon")
+            if update_fields:
+                update_fields.append("updated_at")
+                plant.save(update_fields=update_fields)
+
+            payload.append(
+                {
+                    "name": plant.name,
+                    "icon": plant.icon,
+                    "growth_stages": growth_stages,
+                }
+            )
+
+        serializer = PlantNameStageSerializer(payload, many=True)
+        return Response(
+            {"code": 200, "msg": "success", "data": serializer.data},
+            status=status.HTTP_200_OK,
+        )
+
+
+class PlantDetailView(APIView):
+    """دریافت، ویرایش و حذف یک گیاه."""
+
+    def _get_plant(self, pk):
+        return Plant.objects.filter(pk=pk).first()
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="جزئیات گیاه",
+        description="مشخصات یک گیاه را بر اساس شناسه برمی‌گرداند.",
+        responses={
+            200: build_response(
+                PlantDetailResponseSerializer,
+                "جزئیات گیاه.",
+            ),
+            404: build_response(
+                PlantValidationErrorSerializer,
+                "گیاه یافت نشد.",
+            ),
+        },
+    )
+    def get(self, request, pk):
+        plant = self._get_plant(pk)
+        if not plant:
+            return Response(
+                {"code": 404, "msg": "گیاه یافت نشد.", "data": None},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        serializer = PlantSerializer(plant)
+        return Response(
+            {"code": 200, "msg": "success", "data": serializer.data},
+            status=status.HTTP_200_OK,
+        )
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="ویرایش کامل گیاه",
+        description="تمام فیلدهای یک گیاه را آپدیت می‌کند.",
+        request=PlantSerializer,
+        responses={
+            200: build_response(
+                PlantDetailResponseSerializer,
+                "گیاه با موفقیت به‌روزرسانی شد.",
+            ),
+            400: build_response(
+                PlantValidationErrorSerializer,
+                "داده ورودی نامعتبر است.",
+            ),
+            404: build_response(
+                PlantValidationErrorSerializer,
+                "گیاه یافت نشد.",
+            ),
+        },
+    )
+    def put(self, request, pk):
+        plant = self._get_plant(pk)
+        if not plant:
+            return Response(
+                {"code": 404, "msg": "گیاه یافت نشد.", "data": None},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        serializer = PlantSerializer(plant, data=request.data)
+        if not serializer.is_valid():
+            return Response(
+                {"code": 400, "msg": "داده نامعتبر.", "data": serializer.errors},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        serializer.save()
+        return Response(
+            {"code": 200, "msg": "success", "data": serializer.data},
+            status=status.HTTP_200_OK,
+        )
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="ویرایش جزئی گیاه",
+        description="فقط فیلدهای ارسال‌شده آپدیت می‌شوند.",
+        request=PlantSerializer,
+        responses={
+            200: build_response(
+                PlantDetailResponseSerializer,
+                "گیاه با موفقیت به‌روزرسانی شد.",
+            ),
+            400: build_response(
+                PlantValidationErrorSerializer,
+                "داده ورودی نامعتبر است.",
+            ),
+            404: build_response(
+                PlantValidationErrorSerializer,
+                "گیاه یافت نشد.",
+            ),
+        },
+    )
+    def patch(self, request, pk):
+        plant = self._get_plant(pk)
+        if not plant:
+            return Response(
+                {"code": 404, "msg": "گیاه یافت نشد.", "data": None},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        serializer = PlantSerializer(plant, data=request.data, partial=True)
+        if not serializer.is_valid():
+            return Response(
+                {"code": 400, "msg": "داده نامعتبر.", "data": serializer.errors},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        serializer.save()
+        return Response(
+            {"code": 200, "msg": "success", "data": serializer.data},
+            status=status.HTTP_200_OK,
+        )
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="حذف گیاه",
+        description="یک گیاه را حذف می‌کند.",
+        responses={
+            200: build_response(
+                PlantValidationErrorSerializer,
+                "گیاه با موفقیت حذف شد.",
+            ),
+            404: build_response(
+                PlantValidationErrorSerializer,
+                "گیاه یافت نشد.",
+            ),
+        },
+    )
+    def delete(self, request, pk):
+        plant = self._get_plant(pk)
+        if not plant:
+            return Response(
+                {"code": 404, "msg": "گیاه یافت نشد.", "data": None},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        plant.delete()
+        return Response(
+            {"code": 200, "msg": "گیاه با موفقیت حذف شد.", "data": None},
+            status=status.HTTP_200_OK,
+        )
+
+
+class PlantFetchInfoView(APIView):
+    """دریافت مشخصات گیاه از API خارجی بر اساس نام."""
+
+    @extend_schema(
+        tags=["Plant"],
+        summary="دریافت مشخصات گیاه از API خارجی",
+        description="بر اساس نام گیاه، مشخصات آن را از API خارجی دریافت می‌کند. (فعلاً خالی)",
+        request=inline_serializer(
+            name="PlantFetchInfoRequest",
+            fields={
+                "name": drf_serializers.CharField(help_text="نام گیاه"),
+            },
+        ),
+        responses={
+            200: build_response(
+                PlantFetchInfoResponseSerializer,
+                "اطلاعات گیاه از سرویس خارجی دریافت شد.",
+            ),
+            400: build_response(
+                PlantValidationErrorSerializer,
+                "نام گیاه ارسال نشده است.",
+            ),
+            503: build_response(
+                PlantValidationErrorSerializer,
+                "سرویس خارجی در دسترس نیست.",
+            ),
+        },
+        examples=[
+            OpenApiExample(
+                "نمونه درخواست",
+                value={"name": "گوجه‌فرنگی"},
+                request_only=True,
+            ),
+        ],
+    )
+    def post(self, request):
+        plant_name = request.data.get("name")
+        if not plant_name:
+            return Response(
+                {"code": 400, "msg": "نام گیاه الزامی است.", "data": None},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        result = fetch_plant_info_from_api(plant_name)
+        if result is None:
+            return Response(
+                {
+                    "code": 503,
+                    "msg": "سرویس API هنوز پیاده‌سازی نشده است.",
+                    "data": None,
+                },
+                status=status.HTTP_503_SERVICE_UNAVAILABLE,
+            )
+
+        return Response(
+            {"code": 200, "msg": "success", "data": result},
+            status=status.HTTP_200_OK,
+        )