# Farm Dashboard API Reference

این سند، API های `dashboard` را به‌صورت کامل توضیح می‌دهد و برای هر بخش مشخص می‌کند داده از کجا دریافت می‌شود.

## Endpoint ها

### 1) دریافت کارت‌های داشبورد
- **Method:** `GET`
- **Path:** `/api/farm-dashboard/`
- **View:** `dashboard/views.py:118`
- **URL config:** `dashboard/urls.py:5`
- **Query param الزامی:** `farm_uuid`
- **Auth:** `IsAuthenticated`

### 2) دریافت تنظیمات داشبورد
- **Method:** `GET`
- **Path:** `/api/farm-dashboard-config/`
- **View:** `dashboard/views.py:67`
- **URL config:** `dashboard/urls_config.py:5`
- **Query param الزامی:** `farm_uuid`
- **Auth:** `IsAuthenticated`

### 3) ویرایش تنظیمات داشبورد
- **Method:** `PATCH`
- **Path:** `/api/farm-dashboard-config/`
- **View:** `dashboard/views.py:67`
- **Body:** `farm_uuid` + هرکدام از `disabled_card_ids`، `row_order`، `enable_drag_reorder`
- **Auth:** `IsAuthenticated`

## نحوه شناسایی مزرعه
- مزرعه از طریق `farm_uuid` و مالک کاربر لاگین‌شده پیدا می‌شود.
- پیاده‌سازی در `dashboard/views.py:20` و `dashboard/views.py:22` است.
- اگر `farm_uuid` ارسال نشود یا مزرعه برای آن کاربر پیدا نشود، خطای validation برمی‌گردد.

## تنظیمات داشبورد
تنظیمات داشبورد per-farm در دیتابیس ذخیره می‌شود.

### فیلدها
- `disabled_card_ids`: لیست کارت‌های غیرفعال
- `row_order`: ترتیب ردیف‌ها
- `enable_drag_reorder`: فعال/غیرفعال بودن drag reorder

### مدل ذخیره‌سازی
- مدل: `FarmDashboardConfig`
- فایل: `dashboard/models.py:6`
- جدول: `farm_dashboard_configs`

### مقادیر پیش‌فرض
- از `dashboard/defaults.py:4` و `dashboard/defaults.py:30` می‌آید.
- کارت‌های معتبر در `dashboard/defaults.py:16`
- ردیف‌های معتبر در `dashboard/defaults.py:4`

### اعتبارسنجی
- serializer اصلی: `dashboard/serializers.py:6`
- serializer patch: `dashboard/serializers.py:43`
- `disabled_card_ids` فقط باید از `VALID_CARD_IDS` باشد.
- `row_order` باید تمام `VALID_ROW_IDS` را دقیقاً یک‌بار داشته باشد.

## نقطه تجمیع اصلی داده‌ها
تمام کارت‌ها در تابع زیر assemble می‌شوند:
- `dashboard/services.py:85`

این تابع خروجی چند app مختلف را جمع می‌کند و response نهایی dashboard را می‌سازد.

## منبع داده هر کارت

### `farmOverviewKpis`
- **از کجا ساخته می‌شود:** `dashboard/services.py:41`
- **نوع:** aggregator
- **منابع ورودی:**
  - `farmHealthScore` از `crop_health.services.get_crop_health_summary_data`
  - `waterStressIndex` از `water.services.get_water_stress_index_data`
  - `avgSoilMoisture` از `device_hub.services.get_sensor_7_in_1_summary_data`
  - `disease_risk` و `pest_risk` از `pest_detection.services.get_risk_summary_data`
  - `yield_prediction_card` از `yield_harvest.services.get_yield_harvest_summary_data`
- **نکته مهم:** این کارت جدول یا مدل مستقل ندارد؛ از چند سرویس ترکیب می‌شود.

### `farmWeatherCard`
- **از کجا پر می‌شود:** `water/services.py:9`
- **مدل اصلی:** `WeatherForecastLog`
- **فایل مدل:** `water/models.py:8`
- **جدول:** `weather_forecast_logs`
- **منطق:** جدیدترین رکورد هواشناسی برای همان `farm` خوانده می‌شود.

### `farmAlertsTracker`
- **از کجا پر می‌شود:** `farm_alerts/services.py:379`
- **مدل اصلی:** `FarmAlert`
- **فایل مدل:** `farm_alerts/models.py:16`
- **جدول:** `farm_alerts`
- **منطق:** هشدارهای active مزرعه خوانده می‌شوند و از روی آن‌ها summary ساخته می‌شود.
- **نکته:** با اینکه مدل `FarmAlertTrackerSnapshot` هم وجود دارد در `farm_alerts/models.py:76`، endpoint فعلی کارت tracker مستقیم از `FarmAlert` می‌سازد، نه از snapshot.

### `sensorValuesList`
- **از کجا پر می‌شود:** `device_hub/services.py:495`
- **جزء داخلی:** `device_hub/services.py:334`
- **مدل‌ها:**
  - `FarmDevice` در `device_hub/models.py:45`
  - `SensorExternalRequestLog` در `device_hub/models.py:94`
- **جداول:**
  - `farm_sensors`
  - `sensor_external_request_logs`
- **منطق:**
  - اول سنسور اصلی خاک مزرعه پیدا می‌شود.
  - بعد history لاگ‌های همان device خوانده می‌شود.
  - از payload لاگ‌ها، مقادیر سنسورها استخراج می‌شود.

### `sensorRadarChart`
- **از کجا پر می‌شود:** `device_hub/services.py:389`
- **منبع داده:** همان `SensorExternalRequestLog` و `FarmDevice`
- **منطق:** آخرین reading سنسور 7-in-1 گرفته می‌شود و بر اساس ideal range برای هر فیلد score ساخته می‌شود.

### `sensorComparisonChart`
- **از کجا پر می‌شود:** `device_hub/services.py:412`
- **منبع داده:** `SensorExternalRequestLog`
- **منطق:** history چند reading آخر برای رطوبت خاک گرفته می‌شود و series نمودار ساخته می‌شود.

### `anomalyDetectionCard`
- **از کجا پر می‌شود:** `device_hub/services.py:451`
- **منبع داده:** `SensorExternalRequestLog`
- **منطق:** آخرین reading با بازه‌های ideal مقایسه می‌شود و anomaly های out-of-range ساخته می‌شود.
- **نکته:** در app `farm_alerts` یک مدل `AnomalyDetection` در `farm_alerts/models.py:41` هم وجود دارد، اما dashboard فعلی این کارت را از آن مدل نمی‌خواند.

### `farmAlertsTimeline`
- **از کجا پر می‌شود:** `farm_alerts/services.py:410`
- **مدل اصلی:** `FarmAlert`
- **فایل مدل:** `farm_alerts/models.py:16`
- **جدول:** `farm_alerts`
- **منطق:** حداکثر 10 alert آخر مزرعه خوانده می‌شود.

### `waterNeedPrediction`
- **از کجا پر می‌شود:** `water/services.py:58`
- **مدل اصلی:** `IrrigationRecommendationRequest`
- **فایل مدل:** `irrigation/models.py:9`
- **جدول:** `irrigation_requests`
- **منطق:**
  - از `response_payload` آخرین درخواست آبیاری، بخش `water_balance.daily` استخراج می‌شود.
  - سپس `gross_irrigation_mm` ها تبدیل به series نمودار می‌شوند.
- **نکته:** این کارت در app `water` assemble می‌شود ولی source واقعی‌اش داده‌ی persisted آبیاری است.

### `harvestPredictionCard`
- **از کجا پر می‌شود:** `yield_harvest/services.py:7`
- **مدل اصلی:** `YieldHarvestPredictionLog`
- **فایل مدل:** `yield_harvest/models.py:8`
- **جدول:** `yield_harvest_prediction_logs`
- **منطق:** جدیدترین لاگ برداشت/عملکرد مزرعه خوانده می‌شود.

### `yieldPredictionChart`
- **از کجا پر می‌شود:** `yield_harvest/services.py:7`
- **مدل اصلی:** `YieldHarvestPredictionLog`
- **فایل مدل:** `yield_harvest/models.py:8`
- **جدول:** `yield_harvest_prediction_logs`
- **منطق:** `chart_data` از همان لاگ برداشت/عملکرد برگردانده می‌شود.

### `soilMoistureHeatmap`
- **از کجا پر می‌شود:** `device_hub/services.py:469`
- **منبع داده:** `SensorExternalRequestLog`
- **مدل کمکی device:** `FarmDevice`
- **منطق:** چند reading آخر رطوبت خاک به فرمت heatmap/chart تبدیل می‌شود.

### `ndviHealthCard`
- **از کجا پر می‌شود:** `crop_health/services.py:6`
- **منبع داده فعلی:** mock data
- **فایل:** `crop_health/mock_data.py` از طریق `crop_health/services.py:3`
- **منطق:** فعلاً از دیتابیس یا external log خوانده نمی‌شود؛ مستقیم از mock برمی‌گردد.

### `recommendationsList`
- **از کجا ساخته می‌شود:** `dashboard/services.py:54`
- **نوع:** aggregator
- **منابع ورودی:**
  - recommendationهای ذخیره‌شده در `Recommendation` از `farm_alerts/services.py:459`
  - پیشنهاد آبیاری از `irrigation/services.py:289`
  - پیشنهاد کوددهی از `fertilization/services.py:79`
  - بازه برداشت از `yield_harvest.services.get_yield_harvest_summary_data`
- **مدل‌های اصلی:**
  - `Recommendation` در `farm_alerts/models.py:59`
  - `IrrigationRecommendationRequest` در `irrigation/models.py:9`
  - `FertilizationRecommendationRequest` در `fertilization/models.py:9`
  - `YieldHarvestPredictionLog` در `yield_harvest/models.py:8`
- **نکته:** این کارت داده چند domain مختلف را یکی می‌کند و duplicate titleها را حذف می‌کند.

### `economicOverview`
- **از کجا پر می‌شود:** `economic_overview/services.py:7`
- **مدل اصلی:** `EconomicOverviewLog`
- **فایل مدل:** `economic_overview/models.py:8`
- **جدول:** `economic_overview_logs`
- **منطق:** آخرین لاگ اقتصادی مزرعه خوانده می‌شود.

## منابعی که فعلاً mock هستند
این بخش مهم است، چون user خواسته بداند اطلاعات از کجا می‌آید:

- `ndviHealthCard` از mock می‌آید: `crop_health/services.py:6`
- `farmHealthScore` که داخل `farmOverviewKpis` استفاده می‌شود هم از mock می‌آید: `crop_health/services.py:6`
- `disease_risk` و `pest_risk` که داخل `farmOverviewKpis` استفاده می‌شوند از mock می‌آیند: `pest_detection/services.py:6`

## منابعی که از دیتابیس می‌آیند
- تنظیمات dashboard از `FarmDashboardConfig`
- weather از `WeatherForecastLog`
- alerts/timeline از `FarmAlert`
- recommendationهای ذخیره‌شده از `Recommendation`
- داده آبیاری از `IrrigationRecommendationRequest`
- داده کوددهی برای recommendation card از `FertilizationRecommendationRequest`
- برداشت/عملکرد از `YieldHarvestPredictionLog`
- overview اقتصادی از `EconomicOverviewLog`
- سنسورها از `FarmDevice` و `SensorExternalRequestLog`

## وابستگی بین app ها در dashboard
تجمیع dashboard در `dashboard/services.py:85` به این app ها وابسته است:
- `water`
- `crop_health`
- `economic_overview`
- `farm_alerts`
- `fertilization`
- `irrigation`
- `pest_detection`
- `device_hub`
- `yield_harvest`

## نمونه flow برای `GET /api/farm-dashboard/`
1. کاربر `farm_uuid` را می‌فرستد.
2. در `dashboard/views.py:127` مزرعه متعلق به user پیدا می‌شود.
3. `dashboard/services.py:85` صدا زده می‌شود.
4. این تابع به سرویس‌های appهای مختلف call می‌زند.
5. هر سرویس یا از DB می‌خواند یا از mock/template.
6. پاسخ نهایی به‌صورت یک object شامل تمام cardها برمی‌گردد.

## نکات مهم عملی
- endpoint کارت‌ها فقط config را برنمی‌گرداند؛ payload کامل تمام cardها را یکجا برمی‌گرداند.
- config dashboard از خود کارت‌ها جداست و در endpoint جداگانه مدیریت می‌شود.
- بعضی کارت‌ها production data دارند، بعضی transitional هستند، و بعضی هنوز mock دارند.
- اگر برای مزرعه داده‌ای در بعضی جدول‌ها نباشد، معمولاً fallback/template خالی برمی‌گردد.

## فایل‌های مرجع مهم
- `dashboard/views.py:67`
- `dashboard/views.py:118`
- `dashboard/services.py:85`
- `dashboard/defaults.py:4`
- `dashboard/serializers.py:6`
- `dashboard/models.py:6`
- `docs/dashboard_card_service_map.md:1`