Backend/docs/dashboard_card_service_map.md

# نقشه سرویس کارت های داشبورد

این سند مرجع فشرده `وضعیت واقعی کارت های داشبورد` است؛ نه طراحی آینده.  
تمرکز آن روی منبع داده واقعی، status فعلی، و semantics پاسخ در runtime است.

## قانون runtime در برابر seed

- داده seed / bootstrap / fixture مجاز است و باید فقط از مسیرهای seeding و bootstrap در دسترس بماند.
- داده `mock/sample/demo` نباید در مسیر runtime سرویس، view یا adapter برای تولید پاسخ production-like استفاده شود.
- اگر داده واقعی وجود ندارد، سرویس باید `empty state` یا `failure contract` صریح برگرداند، نه داده ساختگی موفق.

## نقطه شروع فعلی

- تجمیع اصلی کارت‌ها در `dashboard/services.py` داخل `get_farm_dashboard_cards` انجام می‌شود.
- endpoint فعلی ارسال کارت‌ها در `dashboard/views.py` داخل `FarmDashboardCardsView` قرار دارد.
- لیست کارت‌های معتبر در `dashboard/defaults.py` داخل `VALID_CARD_IDS` نگهداری می‌شود.

## جمع‌بندی سریع

| Card ID | Status | semantics | منبع اصلی | تابع/سرویس فعلی | app داده | توضیح |
| --- | --- | --- | --- | --- | --- | --- |
| `farmOverviewKpis` | `implemented / transitional` | aggregator | تجمیع چند سرویس | `_build_overview_kpis` | `dashboard` | منبع واحد ندارد |
| `farmWeatherCard` | `partial` | provider/persisted | آب و هوا | `get_farm_weather_card_data` | `water` | نباید fallback ساختگی runtime داشته باشد |
| `farmAlertsTracker` | `implemented` | cached snapshot | snapshot persisted | `get_alert_tracker_data` | `farm_alerts` | live AI نیست |
| `sensorValuesList` | `implemented / transitional` | persisted sensor log | سنسور 7-in-1 | `get_sensor_7_in_1_summary_data` | `sensor_7_in_1` | adoption کامل facade `farm_data` هنوز کامل نشده |
| `sensorRadarChart` | `implemented / transitional` | persisted sensor log | سنسور 7-in-1 | `get_sensor_7_in_1_summary_data` | `sensor_7_in_1` | همان وضعیت |
| `sensorComparisonChart` | `implemented / transitional` | persisted sensor log | سنسور 7-in-1 | `get_sensor_7_in_1_summary_data` | `sensor_7_in_1` | همان وضعیت |
| `anomalyDetectionCard` | `implemented / transitional` | derived from sensor logs | سنسور 7-in-1 | `get_sensor_7_in_1_summary_data` | `sensor_7_in_1` | ownership نهایی anomalyها هنوز کامل یکدست نشده |
| `farmAlertsTimeline` | `partial` | persisted timeline | هشدارها | `get_alert_timeline_data` | `farm_alerts` | نباید fallback ساختگی runtime داشته باشد |
| `waterNeedPrediction` | `implemented / proxy-derived` | derived from persisted irrigation recommendation | آبیاری | `get_water_need_prediction_data` | `water` | facade در `water` است ولی business source در `irrigation` قرار دارد |
| `harvestPredictionCard` | `implemented / proxy-derived` | persisted AI-derived | برداشت/عملکرد | `get_yield_harvest_summary_data` | `yield_harvest` | از لاگ persisted می‌آید |
| `yieldPredictionChart` | `implemented / proxy-derived` | persisted AI-derived | برداشت/عملکرد | `get_yield_harvest_summary_data` | `yield_harvest` | از لاگ persisted می‌آید |
| `soilMoistureHeatmap` | `implemented / transitional` | persisted sensor log | سنسور 7-in-1 | `get_sensor_7_in_1_summary_data` | `sensor_7_in_1` | facade نهایی همه خوانش‌ها را هنوز unify نکرده |
| `ndviHealthCard` | `disabled / partial` | not runtime-ready | سلامت گیاه | `get_crop_health_summary_data` | `crop_health` | نباید به‌عنوان کارت implemented کامل معرفی شود |
| `recommendationsList` | `implemented / transitional` | aggregator | تجمیع پیشنهادها | `_build_recommendations_list` | `dashboard` | از چند app کنار هم ساخته می‌شود |
| `economicOverview` | `implemented` | persisted/log-based | نمای اقتصادی | `get_economic_overview_data` | `economic_overview` | داده اقتصادی persisted |

## نکات مهم کارت‌ها

### `farmOverviewKpis`
- aggregator است و باید در `dashboard` بماند.

### `farmWeatherCard`
- source: `water.models.WeatherForecastLog`
- قرارداد runtime: اگر داده هواشناسی موجود نباشد، باید `empty state` یا `failure contract` صریح برگردد، نه mock.

### `farmAlertsTracker`
- source: snapshot persisted
- semantics: `cached snapshot`

### `waterNeedPrediction`
- facade فعلی در `water`
- business source واقعی: `irrigation.models.IrrigationRecommendationRequest`
- semantics: `proxy-derived persisted data`

### `harvestPredictionCard` و `yieldPredictionChart`
- source: `yield_harvest.models.YieldHarvestPredictionLog`
- semantics: `persisted AI-derived`

### `ndviHealthCard`
- status: `disabled / partial`
- تا زمانی که source runtime-ready پایدار برای NDVI نهایی نشود، نباید به عنوان کارت production-ready مستند شود.

## Ownership و transitional boundaries

- plant catalog canonical در Backend شروع می‌شود.
- dashboard هنوز بعضی کارت‌ها را از facadeهای transitional می‌خواند.
- سنسور / plant / farm ownership به‌تدریج باید به facade `farm_data` نزدیک‌تر شود، ولی همه مصرف‌کننده‌ها هنوز migrate نشده‌اند.

## Response Semantics

- `farmAlertsTracker` → `cached snapshot`
- `waterNeedPrediction` → `derived from persisted irrigation recommendation`
- `harvestPredictionCard` / `yieldPredictionChart` → `persisted AI-derived snapshot`
- `farmOverviewKpis` / `recommendationsList` → `dashboard-owned aggregator`

## Known Gaps / Follow-up

- ownership نهایی خوانش سنسور بین facade `farm_data` و سرویس‌های legacy هنوز در بعضی کارت‌ها transitional است.
- `ndviHealthCard` هنوز برای runtime production-ready نیست.