Backend/FRONTEND_PAGES_APIS_GUIDE.md

Frontend Pages & APIs Guide

این فایل برای تیم فرانت نوشته شده تا بدانند:

• چه app های جدیدی به بک‌اند اضافه شده‌اند
• چه API های جدیدی اضافه شده‌اند
• چه تغییراتی نسبت به commit قبلی و تغییرات فعلی انجام شده
• سیستم شبیه‌سازی گیاه چگونه به ساختار yield_harvest منتقل شده
• هر card داشبورد باید به کدام app و endpoint وصل شود
• هر card علاوه بر داشبورد باید در صفحه domain خودش هم نمایش داده شود

---

خلاصه تغییرات مهم

تغییرات مهم commit قبلی و فعلی

در تغییرات اخیر، backend از حالت monolithic dashboard mock به سمت app-based domain APIs رفته است.

یعنی به جای اینکه همه چیز فقط در dashboard یا فقط از AI بیاید:

• هر بخش domain اصلی app خودش را دارد
• برای چند domain جدید، API مستقل ساخته شده
• داشبورد از service های app های مختلف داده را assemble می‌کند

مهم‌ترین تغییر معماری

سیستم plant_simulator دیگر app مستقل نیست و منطق آن به yield_harvest منتقل شده است.

این یعنی:

• فولدر plant_simulator حذف شده
• route های شبیه‌ساز هنوز در api/plant-simulator/ موجودند
• اما implementation آن‌ها داخل yield_harvest نگهداری می‌شود

پس برای فرانت:

• صفحه Plant Simulator هنوز می‌تواند باقی بماند
• ولی از نظر backend ownership، این بخش زیرمجموعه yield_harvest محسوب می‌شود
• بهتر است در فرانت هم Plant Simulator به عنوان صفحه/تب وابسته به Yield & Harvest دیده شود

---

app های جدید یا تغییر یافته

1) crop_health

app جدید برای:

• ndviHealthCard
• farm_health_score

هدف:

• داشتن صفحه مستقل برای سلامت محصول / NDVI
• جدا کردن health-related KPIها از dashboard

2) WATER

این app جایگزین ساختار قبلی weather_forecast شده است.

الان app WATER مسئول این بخش‌هاست:

• farmWeatherCard
• waterNeedPrediction
• water_stress_index

هدف:

• ادغام weather + water نیاز + water stress در یک domain
• ساخت صفحه مستقل برای آب و هوا و وضعیت آب

3) soil

app جدید برای:

• avg_soil_moisture
• sensorRadarChart
• sensorComparisonChart
• anomalyDetectionCard
• soilMoistureHeatmap

هدف:

• جدا کردن card های مرتبط با خاک و سنسور از dashboard
• فراهم کردن API مستقل برای صفحه Soil / Sensor Insights

4) yield_harvest

این app قبلا وجود داشت، اما نقش آن گسترده‌تر شده:

• yieldPredictionChart
• harvestPredictionCard
• yield_prediction KPI
• منطق plant_simulator هم به این app منتقل شده

5) dashboard

dashboard الان دیگر منبع اصلی data نیست.

وظیفه جدید آن:

• گرفتن data از service های app های مختلف
• ساخت response نهایی برای صفحه داشبورد

---

API های جدید و فعال

Dashboard

• GET /api/farm-dashboard/?farm_uuid=...
• GET /api/farm-dashboard-config/?farm_uuid=...
• PATCH /api/farm-dashboard-config/

کاربرد:

• فقط برای صفحه Dashboard اصلی
• در فرانت برای داشبورد overview از این endpoint استفاده شود

---

Crop Health APIs

• GET /api/crop-health/summary/

کاربرد:

• صفحه مستقل Crop Health
• کارت‌های:
  • farm_health_score
  • ndviHealthCard

---

WATER APIs

• GET /api/water/card/
• GET /api/water/need-prediction/
• GET /api/water/stress-index/
• GET /api/water/summary/

کاربرد:

• صفحه مستقل Water / Water & Weather
• کارت‌های:
  • farmWeatherCard
  • waterNeedPrediction
  • water_stress_index

نکته:

• route قدیمی weather_forecast دیگر برای فرانت target اصلی نیست
• فرانت باید به api/water/... مهاجرت کند

---

Soil APIs

• GET /api/soil/avg-moisture/
• GET /api/sensor-7-in-1/sensor-radar-chart/
• GET /api/sensor-7-in-1/sensor-comparison-chart/
• GET /api/soil/anomalies/
• GET /api/soil/moisture-heatmap/
• GET /api/soil/summary/

کاربرد:

• صفحه مستقل Soil / Soil Analytics / Sensor Insights
• کارت‌های:
  • avg_soil_moisture
  • sensorRadarChart
  • sensorComparisonChart
  • anomalyDetectionCard
  • soilMoistureHeatmap

---

Yield & Harvest APIs

• GET /api/yield-harvest/summary/

Plant Simulator routes که الان implementationشان زیر yield_harvest است:

• GET /api/plant-simulator/config/
• GET /api/plant-simulator/state/
• POST /api/plant-simulator/start/
• POST /api/plant-simulator/stop/
• POST /api/plant-simulator/reset/
• PATCH /api/plant-simulator/environment/

کاربرد:

• صفحه مستقل Yield & Harvest
• صفحه یا تب Plant Simulator

---

Economic Overview APIs

• POST /api/economy/overview/

کاربرد:

• صفحه مستقل Economic Overview
• کارت economicOverview

---

Pest Detection APIs

• GET /api/pest-detection/risk-summary/

کاربرد:

• صفحه Pest / Disease Risk
• KPIهای:
  • disease_risk
  • pest_risk

---

Farm Alerts APIs

در backend برای dashboard service استفاده می‌شوند:

• tracker
• timeline
• recommendations

مسیرهای موجود:

• GET /api/farm-alerts/tracker/
• GET /api/farm-alerts/timeline/
• GET /api/farm-alerts/anomalies/
• GET /api/farm-alerts/recommendations/

کاربرد:

• صفحه Alerts
• برخی recommendationها

نکته:

• در ساختار جدید، anomalyDetectionCard برای dashboard از soil می‌آید
• ولی farm_alerts هنوز برای timeline/tracker/recommendations مهم است

---

تغییر سیستم Plant Simulator

قبل

• app جداگانه‌ای به اسم plant_simulator وجود داشت
• config, view, route و mock data همگی در همان app بودند

الان

• app plant_simulator حذف شده
• route های plant simulator حفظ شده‌اند
• implementation آن‌ها به yield_harvest منتقل شده

نتیجه برای فرانت

• صفحه Plant Simulator حذف نشود
• اما در navigation و ownership بهتر است به عنوان بخشی از Yield & Harvest دیده شود
• اگر صفحه Yield & Harvest دارید، Plant Simulator بهتر است زیر همین domain قرار بگیرد

پیشنهاد UI/Navigation

• Yield & Harvest
  • Overview
  • Yield Prediction
  • Harvest Prediction
  • Plant Simulator

---

مپ کامل card ها به app ها

Card	Dashboard Row	Source App	Preferred Endpoint	Frontend Page
farm_health_score	overviewKpis	crop_health	GET /api/crop-health/summary/	Crop Health Page
water_stress_index	overviewKpis	WATER	GET /api/water/stress-index/	Water Page
avg_soil_moisture	overviewKpis	soil	GET /api/soil/avg-moisture/	Soil Page
disease_risk	overviewKpis	pest_detection	GET /api/pest-detection/risk-summary/	Pest Risk Page
yield_prediction	overviewKpis	yield_harvest	GET /api/yield-harvest/summary/	Yield & Harvest Page
pest_risk	overviewKpis	pest_detection	GET /api/pest-detection/risk-summary/	Pest Risk Page
farmWeatherCard	weatherAlerts	WATER	GET /api/water/card/	Water Page
farmAlertsTracker	weatherAlerts	farm_alerts	GET /api/farm-alerts/tracker/	Alerts Page
sensorValuesList	sensorMonitoring	فعلا dashboard	فعلا فقط dashboard	Sensor Page در آینده
sensorRadarChart	sensorCharts	sensor_7_in_1	GET /api/sensor-7-in-1/sensor-radar-chart/	Soil Page
sensorComparisonChart	sensorCharts	sensor_7_in_1	GET /api/sensor-7-in-1/sensor-comparison-chart/	Soil Page
anomalyDetectionCard	alertsWater	soil	GET /api/soil/anomalies/	Soil Page
farmAlertsTimeline	alertsWater	farm_alerts	GET /api/farm-alerts/timeline/	Alerts Page
waterNeedPrediction	alertsWater	WATER	GET /api/water/need-prediction/	Water Page
harvestPredictionCard	predictions	yield_harvest	GET /api/yield-harvest/summary/	Yield & Harvest Page
yieldPredictionChart	predictions	yield_harvest	GET /api/yield-harvest/summary/	Yield & Harvest Page
soilMoistureHeatmap	soilHeatmap	soil	GET /api/soil/moisture-heatmap/	Soil Page
ndviHealthCard	ndviRecommendations	crop_health	GET /api/crop-health/summary/	Crop Health Page
recommendationsList	ndviRecommendations	ترکیبی	dashboard aggregate	Recommendations / Alerts / Domain Pages
economicOverview	economic	economic_overview	POST /api/economy/overview/	Economic Overview Page

---

صفحه‌هایی که تیم فرانت باید بسازد

با توجه به backend فعلی، پیشنهاد می‌شود این صفحه‌ها حتما در فرانت ساخته شوند:

1) Dashboard Page

برای overview کلی مزرعه

endpoint اصلی:

• GET /api/farm-dashboard/?farm_uuid=...

2) Crop Health Page

نمایش:

• farm_health_score
• ndviHealthCard

endpoint:

• GET /api/crop-health/summary/

3) Water Page

نمایش:

• farmWeatherCard
• waterNeedPrediction
• water_stress_index

endpoint ها:

• GET /api/water/card/
• GET /api/water/need-prediction/
• GET /api/water/stress-index/
• یا یکجا GET /api/water/summary/

4) Soil Page

نمایش:

• avg_soil_moisture
• sensorRadarChart
• sensorComparisonChart
• anomalyDetectionCard
• soilMoistureHeatmap

endpoint ها:

• GET /api/soil/avg-moisture/
• GET /api/sensor-7-in-1/sensor-radar-chart/
• GET /api/sensor-7-in-1/sensor-comparison-chart/
• GET /api/soil/anomalies/
• GET /api/soil/moisture-heatmap/
• یا یکجا GET /api/soil/summary/

5) Yield & Harvest Page

نمایش:

• yield_prediction
• yieldPredictionChart
• harvestPredictionCard

endpoint:

• GET /api/yield-harvest/summary/

6) Plant Simulator Page / Tab

این صفحه باید باقی بماند، اما domain آن الان زیر yield_harvest است.

endpoint ها:

• GET /api/plant-simulator/config/
• GET /api/plant-simulator/state/
• POST /api/plant-simulator/start/
• POST /api/plant-simulator/stop/
• POST /api/plant-simulator/reset/
• PATCH /api/plant-simulator/environment/

7) Alerts Page

نمایش:

• farmAlertsTracker
• farmAlertsTimeline
• recommendationهای alert-based

endpoint ها:

• GET /api/farm-alerts/tracker/
• GET /api/farm-alerts/timeline/
• GET /api/farm-alerts/recommendations/

8) Pest / Disease Risk Page

نمایش:

• disease_risk
• pest_risk

endpoint:

• GET /api/pest-detection/risk-summary/

9) Economic Overview Page

نمایش:

• economicOverview

endpoint:

• POST /api/economy/overview/

---

قانون مهم برای تیم فرانت

هر card باید در دو جا قابل استفاده باشد:

1) داخل Dashboard

برای overview سریع مزرعه

2) داخل صفحه domain خودش

برای نمایش کامل‌تر و جزئی‌تر

یعنی:

• ndviHealthCard هم در Dashboard باشد هم در Crop Health Page
• waterNeedPrediction هم در Dashboard باشد هم در Water Page
• soilMoistureHeatmap هم در Dashboard باشد هم در Soil Page
• yieldPredictionChart هم در Dashboard باشد هم در Yield & Harvest Page
• economicOverview هم در Dashboard باشد هم در Economic Page

این الگو باید برای همه card های domain-based رعایت شود.

---

پیشنهاد ساختار صفحات در فرانت

پیشنهادی برای منوی اصلی

• Dashboard
• Crop Health
• Water
• Soil
• Yield & Harvest
• Plant Simulator
• Alerts
• Pest & Disease Risk
• Economic Overview

پیشنهادی برای ارتباط صفحه و API

• Dashboard -> فقط dashboard aggregate
• Domain pages -> endpoint اختصاصی همان app

این روش باعث می‌شود:

• dashboard سریع‌تر و ساده‌تر بماند
• صفحات domain مستقل توسعه‌پذیر باشند
• coupling بین frontend pages و dashboard کم شود

---

نکته مهم درباره sensorValuesList

در حال حاضر:

• sensorValuesList هنوز app اختصاصی ندارد
• هنوز از dashboard/mock_data.py می‌آید

برای فرانت:

• موقتا می‌تواند فقط در Dashboard نشان داده شود
• یا یک placeholder page برای Sensor Details ساخته شود

اما از نظر backend، این card هنوز به app اختصاصی مهاجرت نکرده است.

---

جمع‌بندی نهایی

app های جدید یا تغییر یافته برای فرانت

• crop_health
• WATER
• soil
• yield_harvest با نقش گسترده‌تر
• حذف plant_simulator به عنوان app مستقل و انتقال آن به yield_harvest

چیزی که فرانت باید بداند

• dashboard دیگر منبع domain data نیست؛ فقط aggregator است
• هر card مهم الان باید app/domain خودش را داشته باشد
• هر card باید هم در dashboard باشد هم در صفحه مربوط به خودش
• Plant Simulator هنوز endpoint دارد، اما از نظر معماری بخشی از yield_harvest است

بهترین rule برای تیم فرانت

اگر صفحه overview می‌خواهید:

• از GET /api/farm-dashboard/ استفاده کنید

اگر صفحه domain می‌خواهید:

• از endpoint اختصاصی همان app استفاده کنید