Frontend/IRRIGATION_RECOMMENDATION_BACKEND_REQUIREMENTS.md

# Backend data needed only for irrigation recommendation

این فایل فقط اطلاعاتی را لیست می کند که فرانت برای بخش `recommendation` در صفحه
`src/views/dashboards/farm/smartIrrigation/SmartIrrigationRecommendation.tsx`
از بک اند نیاز دارد.

این سند شامل داده های `config`، `history`، یا اکشن های جانبی نیست؛ فقط داده های لازم برای
ساخت نتیجه توصیه آبیاری را پوشش می دهد.

## Request payload

فرانت برای گرفتن توصیه فقط به این فیلدها نیاز دارد:

```json
{
  "farm_uuid": "string",
  "plant_name": "string",
  "growth_stage": "string"
}
```

## Response fields used by UI

فرانت در وضعیت فعلی فقط از این فیلدها در پاسخ recommendation استفاده می کند:

```json
{
  "plan": {
    "frequencyPerWeek": 4,
    "durationMinutes": 38,
    "bestTimeOfDay": "05:30 تا 08:00 صبح",
    "moistureLevel": 72,
    "warning": "string"
  },
  "water_balance": {
    "active_kc": 0.93,
    "crop_profile": {
      "kc_initial": 0.55,
      "kc_mid": 1.05,
      "kc_end": 0.78
    },
    "daily": [
      {
        "forecast_date": "2025-02-12",
        "et0_mm": 5.4,
        "etc_mm": 4.9,
        "effective_rainfall_mm": 0,
        "gross_irrigation_mm": 17,
        "irrigation_timing": "05:30 - 07:00"
      }
    ]
  },
  "timeline": [
    {
      "step_number": 1,
      "title": "string",
      "description": "string"
    }
  ],
  "sections": [
    {
      "title": "string",
      "icon": "string",
      "type": "warning | tip",
      "content": "string"
    }
  ]
}
```

## Field-by-field usage

### 1) `plan`

برای نمایش خلاصه نسخه و هشدارها:

- `plan.frequencyPerWeek`
  - نمایش تعداد نوبت آبیاری
- `plan.durationMinutes`
  - نمایش مدت هر نوبت
- `plan.bestTimeOfDay`
  - نمایش بهترین بازه زمانی آبیاری
- `plan.moistureLevel`
  - نمایش مقدار رطوبت فعلی در gauge
- `plan.warning`
  - نمایش هشدار اصلی در بخش warnings

### 2) `water_balance`

برای نمایش تراز آب و داده های روزانه:

- `water_balance.daily[]`
  - `forecast_date`
  - `gross_irrigation_mm`
  - `irrigation_timing`
  - `et0_mm`
  - `etc_mm`
  - `effective_rainfall_mm`
- `water_balance.crop_profile`
  - `kc_initial`
  - `kc_mid`
  - `kc_end`
- `water_balance.active_kc`
  - فعلا در UI فعلی استفاده مستقیم ندارد، اما بهتر است بماند اگر قرار است بعدا نمایش داده شود

### 3) `timeline`

برای نمایش Stepper مراحل اجرا:

- `timeline[].step_number`
- `timeline[].title`
- `timeline[].description`

نکته:
- در UI فعلی فقط همین سه فیلد لازم است.
- `time_label` و `state` قبلا در ماک استفاده شده بودند ولی در نسخه فعلی UI دیگر مصرف نمی شوند.

### 4) `sections`

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

- `sections[].type`
  - فقط این مقادیر فعلا مصرف می شوند:
    - `warning`
    - `tip`
- `sections[].title`
  - برای کارت tip
- `sections[].icon`
  - برای کارت tip
- `sections[].content`
  - برای متن warning و tip

## Minimum response required

اگر بخواهیم حداقل پاسخ قابل استفاده برای UI فعلی را تعریف کنیم، این ساختار کافی است:

```json
{
  "plan": {
    "frequencyPerWeek": 4,
    "durationMinutes": 38,
    "bestTimeOfDay": "05:30 تا 08:00 صبح",
    "moistureLevel": 72,
    "warning": "در ساعات گرم روز آبیاری انجام نشود"
  },
  "water_balance": {
    "crop_profile": {
      "kc_initial": 0.55,
      "kc_mid": 1.05,
      "kc_end": 0.78
    },
    "daily": [
      {
        "forecast_date": "2025-02-12",
        "et0_mm": 5.4,
        "etc_mm": 4.9,
        "effective_rainfall_mm": 0,
        "gross_irrigation_mm": 17,
        "irrigation_timing": "05:30 - 07:00"
      }
    ]
  },
  "timeline": [
    {
      "step_number": 1,
      "title": "بررسی فشار",
      "description": "فشار ابتدا و انتهای لاین کنترل شود"
    }
  ],
  "sections": [
    {
      "title": "هشدار تبخیر بالا",
      "icon": "tabler-alert-triangle",
      "type": "warning",
      "content": "در ساعات گرم روز آبیاری انجام نشود"
    },
    {
      "title": "نکته بهره وری",
      "icon": "tabler-bulb",
      "type": "tip",
      "content": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
    }
  ]
}
```

## Fields currently not required by this UI

فیلدهای زیر در نسخه فعلی صفحه برای نمایش recommendation لازم نیستند:

- `raw_response`
- `status`
- `generated_at`
- `recommendation_title`
- `recommendation_subtitle`
- `final_verdict`
- `primary_method`
- `usage_summary`
- `alternative_plans`
- `sections[].type = schedule`
- `sections[].type = method`

## Practical backend recommendation

اگر هدف فقط راه اندازی همین UI فعلی است، بهتر است endpoint recommendation حداقل این 4 بخش را برگرداند:

- `plan`
- `water_balance`
- `timeline`
- `sections`

و در `sections` فعلا حداقل این دو نوع را پشتیبانی کند:

- `warning`
- `tip`