Logic/BACKEND_PLANTS_AI_FARMDATA_SYNC_PROPOSAL.md

پیشنهاد معماری جدید: Backend-owned Plants + AI farm_data Sync

خلاصه تصمیم

تصمیم جدید این است که مالک اصلی داده‌های گیاه در سیستم، Backend باشد و اپ plants در Backend به‌صورت کامل مسئول نگهداری catalog گیاه‌ها شود.

در این معماری:

• اپ Backend/plants منبع اصلی Plant Catalog خواهد بود
• اپ Backend/farm_hub رابطه‌ی فارم با گیاه‌ها را نگه می‌دارد
• اپ Ai/farm_data داده‌های مورد نیاز AI را از Backend دریافت می‌کند
• پس از هر تغییر در Backend، داده‌های مرتبط در Ai/farm_data به‌روزرسانی می‌شوند
• هرجایی در AI که به اطلاعات گیاه نیاز دارد، از داده‌های farm_data استفاده می‌کند

---

هدف اصلی

این تغییر برای حل چند مسئله انجام می‌شود:

• متمرکز شدن catalog گیاه‌ها در Backend
• حذف پراکندگی ownership داده‌های گیاه
• واضح شدن source of truth
• ساده‌تر شدن استفاده‌ی ماژول‌های AI از اطلاعات گیاه
• فراهم شدن یک read-model مشخص در Ai/farm_data

---

تصمیم domain-level

1) Backend مالک اصلی داده‌ی گیاه است

در این معماری، اطلاعات پایه‌ی گیاه باید در Backend نگهداری شود:

• نام گیاه
• مشخصات کاتالوگ
• ویژگی‌های رشد
• نور
• آب
• خاک
• دما
• فصل کاشت
• زمان برداشت
• spacing
• fertilizer
• و هر داده‌ی canonical دیگر

2) AI مصرف‌کننده‌ی داده‌ی گیاه است

در این معماری، AI دیگر owner داده‌های گیاه نیست، بلکه از Backend این اطلاعات را دریافت می‌کند.

3) Ai/farm_data لایه‌ی داده‌ای مورد استفاده‌ی AI می‌شود

در AI، داده‌ی گیاه مستقیماً از مدل canonical مستقل خوانده نمی‌شود، بلکه از داده‌هایی استفاده می‌شود که در Ai/farm_data ذخیره یا sync شده‌اند.

---

ساختار پیشنهادی Backend

اپ plants

اپ Backend/plants باید به اپ canonical برای catalog گیاه‌ها تبدیل شود.

مسئولیت‌ها

• نگهداری لیست همه‌ی گیاه‌ها
• نگهداری اطلاعات catalog هر گیاه
• ارائه‌ی API برای خواندن catalog گیاه‌ها
• ارائه‌ی API برای دریافت جزئیات یک گیاه
• در صورت نیاز، ارائه‌ی endpointهای تغییرات برای sync با AI

داده‌های این app

نمونه داده‌هایی که بهتر است در plants باشند:

• id
• name
• slug
• icon
• description
• light
• watering
• soil
• temperature
• growth_stage_defaults
• planting_season
• harvest_time
• spacing
• fertilizer
• health_profile
• irrigation_profile
• growth_profile
• is_active
• updated_at

---

اپ farm_hub

در Backend/farm_hub باید رابطه‌ی فارم با گیاه نگهداری شود.

پیشنهاد رابطه

در گام اول، چیزی که گفتی منطقی است:

• یک رابطه‌ی ManyToMany بین FarmHub و Plant

مثلاً در سطح مفهومی:

class FarmHub(models.Model):
    plants = models.ManyToManyField("plants.Plant", related_name="farms", blank=True)

این ساختار برای شروع خوب است اگر فقط بخواهی بدانی:

• هر فارم چه گیاه‌هایی دارد

نکته تکمیلی مهم

اگر بعداً برای رابطه‌ی فارم و گیاه metadata خواستی، ManyToMany ساده کافی نیست.

مثلاً اگر این داده‌ها لازم شوند:

• تاریخ کاشت
• وضعیت فعلی رشد
• نوع کشت در آن فارم
• تنظیمات اختصاصی آبیاری
• health state
• مقدار هدف تولید

بهتر است بعداً رابطه به مدل واسط تبدیل شود:

class FarmPlant(models.Model):
    farm = models.ForeignKey(FarmHub, on_delete=models.CASCADE)
    plant = models.ForeignKey("plants.Plant", on_delete=models.CASCADE)
    planted_at = models.DateField(null=True, blank=True)
    stage = models.CharField(max_length=64, blank=True)

نتیجه

• برای فاز اول: ManyToMany ساده قابل قبول است
• برای فاز matureتر: through model بهتر است

---

ساختار پیشنهادی AI

نقش Ai/farm_data

در این تصمیم جدید، Ai/farm_data تبدیل به لایه‌ای می‌شود که داده‌های گیاه و داده‌های فارم-گیاه را برای مصرف ماژول‌های AI نگه می‌دارد.

یعنی:

• Backend source of truth است
• Ai/farm_data read/update replica برای use caseهای AI است

وظایف farm_data

• دریافت داده‌ی گیاه از Backend
• دریافت relationهای فارم و گیاه از Backend
• ذخیره‌ی داده‌ی مورد نیاز برای AI
• به‌روزرسانی داده بعد از هر تغییر
• ارائه‌ی data access ساده برای سایر appهای AI

---

جریان داده پیشنهادی

مرحله 1: تغییر در Backend

هر تغییری که در این بخش‌ها رخ می‌دهد:

• ایجاد گیاه جدید
• ویرایش catalog گیاه
• حذف یا غیرفعال‌سازی گیاه
• تغییر گیاه‌های مرتبط با یک فارم

باید باعث شود Ai/farm_data نیز به‌روزرسانی شود.

مرحله 2: sync به AI

بعد از تغییر، Backend از طریق API یا مکانیزم sync، داده را به Ai/farm_data می‌رساند.

مرحله 3: مصرف در AI

هر app در AI که به داده‌ی گیاه نیاز دارد، به‌جای dependency مستقیم روی مدل‌های قدیمی یا منابع پراکنده، از farm_data می‌خواند.

---

نکته مهم درباره apps.py

اگرچه در پیام قبلی بحث Ai/farm_data/apps.py مطرح بود، در این تصمیم جدید بهتر است منطق sync اصلی در apps.py قرار نگیرد.

apps.py برای چه مناسب است؟

• app registration
• signal registration
• import سبک startup

apps.py برای چه مناسب نیست؟

• orchestration سنگین sync
• HTTP fetch logic
• retry logic
• reconciliation logic
• business update flow

پیشنهاد بهتر

منطق sync بهتر است در این فایل‌ها قرار بگیرد:

• Ai/farm_data/services.py
• Ai/farm_data/tasks.py
• Ai/farm_data/clients/backend.py

و apps.py فقط wiring را انجام دهد.

---

دو نوع داده‌ای که باید تفکیک شوند

برای اینکه این معماری بعداً تمیز بماند، بهتر است از همین ابتدا دو نوع داده را از هم جدا ببینی.

1) Plant Catalog

داده‌های عمومی و canonical هر گیاه:

• نام
• مشخصات رشد
• پروفایل آبیاری
• نیازهای محیطی

این داده‌ها متعلق به Backend/plants هستند.

2) Farm Plant Assignment / Context

داده‌هایی که مشخص می‌کنند:

• یک فارم چه گیاهی دارد
• چه گیاهی برای آن فارم فعال است
• چه context یا تنظیمی روی آن اعمال شده

این داده‌ها از relation بین فارم و گیاه می‌آیند و در Backend تعریف می‌شوند، اما برای مصرف AI در farm_data sync می‌شوند.

---

چه appهایی در AI باید update شوند؟

در این معماری جدید، همه appهای AI لزوماً نیاز به تغییر مستقیم ندارند؛ فقط appهایی که الان مستقیم یا غیرمستقیم به داده‌ی گیاه یا SensorData.plants وابسته‌اند باید update شوند.

1) Ai/farm_data

این app مهم‌ترین app برای تغییر است و باید به هسته‌ی integration جدید تبدیل شود.

فایل‌ها و بخش‌هایی که باید update شوند

• Ai/farm_data/models.py
• Ai/farm_data/serializers.py
• Ai/farm_data/services.py
• Ai/farm_data/views.py
• Ai/farm_data/urls.py
• Ai/farm_data/apps.py
• Ai/farm_data/management/commands/seed_farm_data.py
• Ai/farm_data/tests/

تغییرات مورد نیاز

• حذف وابستگی مستقیم ManyToMany به plant.Plant در صورت جایگزینی با replica data
• تعریف ساختار جدید برای نگهداری plant catalog snapshot یا farm plant snapshot
• افزودن service client برای خواندن data از Backend
• افزودن endpoint یا task برای sync داده از Backend
• تغییر serializerها تا payload جدید گیاه را برگردانند
• اصلاح تست‌ها بر اساس source جدید داده

نکته مهم

الان در Ai/farm_data/models.py فیلد plants به plant.Plant وصل است. این نقطه یکی از اصلی‌ترین جاهایی است که باید بازطراحی شود، چون در معماری جدید AI نباید برای catalog گیاه به مدل canonical داخلی تکیه کند.

---

2) Ai/rag

این app از مهم‌ترین مصرف‌کننده‌های اطلاعات گیاه است و باید update شود تا به‌جای مدل‌های قبلی، از farm_data بخواند.

فایل‌ها و بخش‌هایی که باید update شوند

• Ai/rag/user_data.py
• Ai/rag/services/irrigation.py
• Ai/rag/services/fertilization.py
• Ai/rag/services/water_need_prediction.py
• Ai/rag/services/pest_disease.py
• Ai/rag/services/yield_harvest.py
• Ai/rag/tests/test_recommendation_services.py
• هر فایل دیگری که مستقیم Plant یا SensorData.plants را می‌خواند

تغییرات مورد نیاز

• حذف import مستقیم از plant.models
• استفاده از facade یا service داخل farm_data برای دریافت plant context
• جایگزینی readهای مستقیم از مدل گیاه با read model جدید
• اصلاح تست‌ها بر اساس structure جدید داده

نکته مهم

در حال حاضر Ai/rag/user_data.py مستقیم به Plant وابستگی دارد. این وابستگی باید حذف شود و همه چیز از farm_data خوانده شود.

---

3) Ai/irrigation

این app احتمالاً از داده‌ی گیاه برای recommendation یا indicator استفاده می‌کند و باید با read model جدید سازگار شود.

فایل‌ها و بخش‌هایی که باید update شوند

• Ai/irrigation/indicators.py
• Ai/irrigation/views.py
• تست‌های irrigation

تغییرات مورد نیاز

• اگر منطق آبیاری به plant profile وابسته است، profile باید از farm_data خوانده شود
• حذف هر dependency متنی یا مستقیم به جدول Plant
• هماهنگی responseها با data contract جدید

---

4) Ai/soile

این app مستقیماً SensorData را می‌خواند و در queryها plants را prefetch می‌کند؛ بنابراین باید update شود.

فایل‌ها و بخش‌هایی که باید update شوند

• Ai/soile/services.py
• Ai/soile/test_soil_moisture_heatmap_api.py

تغییرات مورد نیاز

• بازنویسی queryهایی که prefetch_related("plants") دارند
• استفاده از plant data جدیدی که در farm_data ذخیره می‌شود
• اصلاح منطق‌هایی که فرض می‌کنند plants یک relation مستقیم ORM به مدل Plant است

---

5) Ai/weather

این app بیشتر weather-centric است، ولی برخی flowها از SensorData و در مواردی از context فارم/گیاه برای پیش‌بینی نیاز آبی استفاده می‌کنند.

فایل‌ها و بخش‌هایی که باید update شوند

• Ai/weather/water_need_prediction.py
• Ai/weather/farm_weather.py
• تست‌های مرتبط با farm weather

تغییرات مورد نیاز

• اگر plant context برای water need استفاده می‌شود، منبع آن باید farm_data باشد
• اگر serializer یا service فرض می‌کند relation قبلی plants برقرار است، باید اصلاح شود

---

6) Ai/location_data

این app بیشتر location-centric است و وابستگی مستقیم شدیدی به گیاه ندارد، اما چون با SensorData کار می‌کند باید از سازگاری model جدید مطمئن شویم.

فایل‌ها و بخش‌هایی که باید update شوند

• Ai/location_data/ndvi.py
• Ai/location_data/views.py در صورت استفاده از farm context
• تست‌های location مرتبط با farm

تغییرات مورد نیاز

• بیشتر در حد compatibility check با ساختار جدید farm_data
• اگر plant-aware response وجود دارد، باید با source جدید هماهنگ شود

---

7) Ai/farm_alerts

اگر alertها به نوع گیاه، stage، یا context گیاه متکی باشند، این app هم باید update شود.

فایل‌ها و بخش‌هایی که باید بررسی/آپدیت شوند

• Ai/farm_alerts/services.py
• Ai/farm_alerts/alerts_tracker.py
• Ai/farm_alerts/views.py

تغییرات مورد نیاز

• هرجا alert rule به plant info وابسته است، plant info باید از farm_data خوانده شود
• اگر فعلاً وابستگی مستقیم ندارد، فقط compatibility review کافی است

---

8) Ai/economy

این app ممکن است در بعضی سناریوها به نوع گیاه برای تحلیل اقتصادی وابسته شود.

فایل‌ها و بخش‌هایی که باید بررسی شوند

• Ai/economy/services.py
• Ai/economy/views.py
• تست‌های economy

تغییرات مورد نیاز

• اگر نوع گیاه یا catalog گیاه در محاسبات اقتصادی استفاده می‌شود، باید از farm_data خوانده شود
• اگر فعلاً استفاده‌ای ندارد، تنها review کافی است

---

appهایی که احتمالاً بیشترین تغییر را دارند

اگر بخواهیم اولویت‌بندی کنیم، بیشترین تغییر در AI به‌ترتیب در این appها خواهد بود:

• Ai/farm_data
• Ai/rag
• Ai/soile
• Ai/irrigation
• Ai/weather

و این appها بیشتر نیاز به review و compatibility check دارند:

• Ai/location_data
• Ai/farm_alerts
• Ai/economy

---

الگوی پیشنهادی برای جلوگیری از پخش شدن وابستگی‌ها

برای اینکه تغییرات در AI کنترل‌پذیر بماند، بهتر است appهای دیگر مستقیماً model جدید farm_data را تکه‌تکه query نزنند.

پیشنهاد

یک لایه‌ی access مرکزی در farm_data تعریف شود، مثلاً:

• Ai/farm_data/services.py
• یا Ai/farm_data/context.py

و appهای دیگر فقط از همین interface استفاده کنند.

مثال از مسئولیت این facade

• گرفتن plant catalog برای یک farm
• گرفتن primary plant یا active plants
• گرفتن irrigation profile گیاه
• گرفتن growth/health context گیاه

این کار باعث می‌شود اگر بعداً schema داخلی farm_data عوض شد، فقط یک لایه update شود.

---

تغییرات مستندی که باید در AI انجام شوند

علاوه بر کد، این بخش‌های مستنداتی هم باید update شوند:

• Ai/API_REFERENCE_FA.md
• Ai/APPS_URLS_AUDIT.md
• Ai/API_RELIABILITY_AUDIT_FA.md
• هر doc مرتبط با Plant API
• هر doc مرتبط با farm_data payload

دلیل

چون در وضعیت جدید:

• Plant API دیگر نباید به‌عنوان canonical داخل AI معرفی شود
• farm_data باید به‌عنوان plant consumer/read model معرفی شود
• endpointها و schemaهای response احتمالاً تغییر می‌کنند

---

پیشنهاد فازبندی update اپ‌های AI

فاز 1: هسته‌ی data layer

• update Ai/farm_data
• تعریف schema جدید data
• تعریف sync service با Backend

فاز 2: مصرف‌کننده‌های اصلی

• update Ai/rag
• update Ai/soile
• update Ai/irrigation
• update Ai/weather

فاز 3: مصرف‌کننده‌های ثانویه

• review/update Ai/location_data
• review/update Ai/farm_alerts
• review/update Ai/economy

فاز 4: پاک‌سازی نهایی

• حذف dependency مستقیم به plant.models
• حذف endpointهای قدیمی یا deprecated در AI
• اصلاح تست‌ها و docs

---

صورت‌بندی نهایی این تغییر

نسخه‌ی دقیق‌تر و کامل‌تر این تصمیم به این صورت است:

• یک app کامل plants در Backend نگهدارنده‌ی catalog همه‌ی گیاه‌ها باشد.
• در Backend/farm_hub رابطه‌ی ManyToMany بین FarmHub و Plant تعریف شود.
• بعد از هر تغییر در catalog گیاه یا رابطه‌ی فارم-گیاه، داده‌ها به Ai/farm_data sync شوند.
• Ai/farm_data به منبع مصرفی همه‌ی ماژول‌های AI برای اطلاعات گیاه تبدیل شود.
• در AI هرجا اطلاعات گیاه، catalog گیاه، یا نوع گیاه لازم است، از farm_data خوانده شود، نه از مدل‌های پراکنده یا منبع دیگری.
• appهای AI که الان به Plant یا SensorData.plants وابسته‌اند باید مرحله‌به‌مرحله به این مدل جدید مهاجرت کنند.

---

نتیجه یک‌خطی

این تصمیم از نظر معماری قابل دفاع و قابل توسعه است، به شرطی که Backend/plants source of truth بماند، farm_hub رابطه‌ی فارم-گیاه را نگه دارد، Ai/farm_data لایه‌ی sync/read برای AI باشد، و تمام appهای وابسته در AI به‌صورت کنترل‌شده از dependency مستقیم به Plant جدا شوند.