518 lines
14 KiB
Markdown
518 lines
14 KiB
Markdown
# 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/soil/sensor-radar-chart/`
|
|
- `GET /api/soil/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
|
|
|
|
- `GET /api/economic-overview/summary/`
|
|
|
|
کاربرد:
|
|
|
|
- صفحه مستقل 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` | `soil` | `GET /api/soil/sensor-radar-chart/` | Soil Page |
|
|
| `sensorComparisonChart` | `sensorCharts` | `soil` | `GET /api/soil/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` | `GET /api/economic-overview/summary/` | 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/soil/sensor-radar-chart/`
|
|
- `GET /api/soil/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:
|
|
|
|
- `GET /api/economic-overview/summary/`
|
|
|
|
---
|
|
|
|
## قانون مهم برای تیم فرانت
|
|
|
|
هر 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 استفاده کنید
|