Ai/docs/plant_service_relation.md

ارتباط سرویس‌ها با Plant و گیاهان

این سند توضیح می‌دهد که در پروژه، داده‌ی گیاه از کجا می‌آید، چطور در farm_data نگه‌داری می‌شود، چگونه به سرویس‌های crop_simulation می‌رسد و در نهایت چطور در location_data برای پیشنهاد گیاه هر کلاستر استفاده می‌شود.

نمای کلی

در این پروژه سه لایه اصلی برای کار با گیاه وجود دارد:

1. plant
2. farm_data
3. crop_simulation و location_data

نقش هر لایه:

• plant: مرجع canonical نام گیاه و aliasها است.
• farm_data: نسخه snapshot شده‌ی گیاهان Backend و assignment هر مزرعه به گیاه‌ها را نگه می‌دارد.
• crop_simulation: از گیاه انتخاب‌شده برای ساخت ورودی شبیه‌سازی استفاده می‌کند.
• location_data: داده‌ی کلاسترهای KMeans را با گیاه‌های مزرعه ترکیب می‌کند و پیشنهاد گیاه می‌سازد.

1) لایه plant

اپ plant مرجع اصلی برای resolve کردن نام گیاه است.

فایل مهم:

• plant/apps.py

تابع مهم:

• resolve_plant_name

رفتار این تابع:

• نام ورودی را می‌گیرد.
• اگر همان نام در جدول plant.Plant وجود داشته باشد، همان را برمی‌گرداند.
• اگر alias برای آن تعریف شده باشد، alias را به نام canonical تبدیل می‌کند.
• اگر از نظر نرمال‌سازی متنی با یک گیاه match شود، همان نام canonical را برمی‌گرداند.

در نتیجه:

• ورودی‌هایی مثل plant_name، crop یا crop_name قبل از ورود به شبیه‌سازی، به نام استاندارد تبدیل می‌شوند.

2) لایه farm_data

اپ farm_data مدل read-model مربوط به گیاهان هر مزرعه را نگه می‌دارد.

مدل‌های اصلی:

• farm_data.models.PlantCatalogSnapshot
• farm_data.models.FarmPlantAssignment
• farm_data.models.SensorData

PlantCatalogSnapshot

این مدل کپی محلی و خواندنی از کاتالوگ گیاه Backend است.

اطلاعاتی که در آن نگه‌داری می‌شود:

• نام گیاه
• توضیحات
• growth_profile
• irrigation_profile
• health_profile
• فصل کاشت، زمان برداشت، فاصله کاشت، کود و ...

این مدل منبع اصلی هوش مصنوعی برای خواندن پروفایل گیاه است، نه relation قدیمی SensorData.plants.

FarmPlantAssignment

این مدل مشخص می‌کند هر مزرعه چه گیاه‌هایی دارد.

فیلدهای مهم:

• farm
• plant
• position
• stage
• metadata

یعنی هر مزرعه می‌تواند چند گیاه داشته باشد و ترتیب و مرحله رشد هرکدام هم ثبت می‌شود.

توابع مهم در farm_data/services.py

فایل مهم:

• farm_data/services.py

توابع کلیدی:

• sync_plant_catalog_from_backend
• assign_farm_plants_from_backend_ids
• get_farm_plant_assignments
• get_farm_plant_snapshots
• get_primary_plant_snapshot
• get_farm_plant_snapshot_by_name
• clone_snapshot_as_runtime_plant
• get_runtime_plant_for_farm
• list_runtime_plants_for_farm

جریان داده در farm_data

1. کاتالوگ گیاه از Backend خوانده می‌شود و داخل PlantCatalogSnapshot ذخیره می‌شود.
2. گیاه‌های انتخاب‌شده‌ی هر مزرعه با FarmPlantAssignment ثبت می‌شوند.
3. اگر سرویس شبیه‌سازی یک plant_name مشخص بگیرد، همان گیاه از assignmentها پیدا می‌شود.
4. اگر plant_name ارسال نشود، گیاه اول مزرعه به عنوان پیش‌فرض انتخاب می‌شود.

Runtime Plant

تابع get_runtime_plant_for_farm یک snapshot را به یک object سبک runtime تبدیل می‌کند تا downstream serviceها بدون وابستگی مستقیم به مدل DB از آن استفاده کنند.

این object شامل فیلدهایی مثل:

• name
• growth_profile
• irrigation_profile
• health_profile
• planting_season
• harvest_time

است.

3) ورود گیاه به crop_simulation

فایل‌های مهم:

• crop_simulation/services.py
• crop_simulation/growth_simulation.py
• crop_simulation/harvest_prediction.py
• crop_simulation/yield_prediction.py

build_simulation_payload_from_farm

مهم‌ترین نقطه اتصال بین farm_data و crop_simulation این تابع است:

• crop_simulation.services.build_simulation_payload_from_farm

این تابع:

1. مزرعه را با get_canonical_farm_record پیدا می‌کند.
2. گیاه را با get_runtime_plant_for_farm resolve می‌کند.
3. snapshot هوش مصنوعی مزرعه را می‌خواند.
4. weather, soil, site_parameters را می‌سازد.
5. از پروفایل گیاه، crop_parameters و در صورت وجود agromanagement پیش‌فرض را استخراج می‌کند.

خروجی این تابع شامل این بخش‌هاست:

• plant
• runtime_plants
• weather
• soil
• site_parameters
• crop_parameters
• agromanagement

یعنی تمام چیزی که موتور شبیه‌سازی لازم دارد.

استفاده در Growth Simulation

در crop_simulation/growth_simulation.py اگر farm_uuid داده شود:

• build_growth_context از build_simulation_payload_from_farm استفاده می‌کند.
• گیاه انتخاب‌شده وارد context می‌شود.
• سپس شبیه‌سازی PCSE یا fallback projection روی همان گیاه اجرا می‌شود.

استفاده در Harvest Prediction

در crop_simulation/harvest_prediction.py اگر plant_name ارسال نشود:

• سرویس با get_runtime_plant_for_farm گیاه پیش‌فرض مزرعه را پیدا می‌کند.
• سپس از همان گیاه برای محاسبه‌ی GDD و پیش‌بینی برداشت استفاده می‌شود.

استفاده در Yield Prediction

در crop_simulation/yield_prediction.py:

• سرویس chart فعلی مزرعه را صدا می‌زند.
• chart هم قبلاً گیاه را از مسیر canonical مزرعه resolve کرده است.
• بنابراین yield همیشه روی یک گیاه مشخص از assignmentهای مزرعه محاسبه می‌شود.

4) نقش serializerها در resolve کردن نام گیاه

فایل مهم:

• crop_simulation/serializers.py

کلاس مهم:

• PlantNameAliasMixin

این mixin:

• plant_name
• crop
• crop_name

را قبول می‌کند و با apps.get_app_config("plant").resolve_plant_name(...) آن را canonical می‌کند.

پس حتی اگر کلاینت نام گیاه را با alias بفرستد، سرویس شبیه‌سازی با نام استاندارد کار می‌کند.

5) ارتباط location_data با گیاه‌ها

فایل مهم:

• location_data/cluster_recommendation.py

تابع اصلی:

• build_cluster_crop_recommendations

این تابع ارتباط بین کلاسترهای KMeans و گیاه‌های مزرعه را می‌سازد.

ورودی

• farm_uuid

کارهایی که انجام می‌دهد

1. مزرعه را از farm_data پیدا می‌کند.
2. لیست گیاه‌های ثبت‌شده را با get_farm_plant_assignments می‌خواند.
3. snapshot کلاسترهای location_data را می‌گیرد.
4. برای هر گیاه ثبت‌شده، با build_simulation_payload_from_farm یک payload پایه می‌سازد.
5. برای هر کلاستر:
   • متریک‌های همان کلاستر مثل ndvi, ndwi, soil_vv, soil_vv_db را جمع می‌کند.
   • پارامترهای soil/site را با داده همان کلاستر override می‌کند.
   • برای تک‌تک گیاه‌های مزرعه شبیه‌سازی اجرا می‌کند.
   • خروجی‌ها را بر اساس yield_estimate رتبه‌بندی می‌کند.
6. بهترین گیاه را به عنوان suggested_plant برمی‌گرداند.

نتیجه

location_data خودش مرجع گیاه نیست؛ فقط:

• گیاه‌ها را از farm_data
• نام canonical را از plant
• منطق شبیه‌سازی را از crop_simulation

می‌گیرد و روی داده‌های کلاستر اعمال می‌کند.

6) ترتیب مسئولیت‌ها

برای جلوگیری از ابهام، مسئولیت هر بخش این است:

• plant:

  • canonical name
  • alias resolving

• farm_data:

  • snapshot گیاه
  • assignment گیاه به مزرعه
  • تبدیل snapshot به runtime plant

• crop_simulation:

  • ساخت payload شبیه‌سازی از مزرعه و گیاه
  • اجرای شبیه‌سازی رشد، عملکرد و برداشت

• location_data:

  • خواندن کلاسترهای KMeans
  • مقایسه گیاه‌های مزرعه برای هر کلاستر
  • پیشنهاد گیاه برای sub-block

7) نکات مهم طراحی

• relation قدیمی SensorData.plants مسیر legacy است و منبع canonical نیست.
• مسیر canonical برای گیاه‌های مزرعه، FarmPlantAssignment و PlantCatalogSnapshot است.
• سرویس‌های شبیه‌سازی نباید مستقیم از plant.Plant برای گیاه مزرعه استفاده کنند؛ مسیر درست، farm_data.services.get_runtime_plant_for_farm است.
• اگر plant_name صریح داده نشود، معمولاً گیاه اول assignmentهای مزرعه انتخاب می‌شود.
• اگر چند گیاه برای مزرعه ثبت شده باشد، endpoint پیشنهاد کلاستر همه‌ی آن‌ها را compare می‌کند.

8) خلاصه جریان end-to-end

جریان کامل به این صورت است:

1. Backend plant catalog -> PlantCatalogSnapshot
2. farm selected plants -> FarmPlantAssignment
3. client request with farm_uuid
4. farm -> runtime plant resolution
5. runtime plant + farm metrics -> simulation payload
6. simulation payload -> PCSE/projection
7. cluster metrics + plant candidates -> recommended crop per cluster

9) فایل‌های کلیدی برای مرور سریع

• plant/apps.py
• farm_data/models.py
• farm_data/services.py
• crop_simulation/services.py
• crop_simulation/growth_simulation.py
• crop_simulation/harvest_prediction.py
• crop_simulation/yield_prediction.py
• location_data/cluster_recommendation.py