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

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

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

Response fields used by UI

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

{
  "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 فعلی را تعریف کنیم، این ساختار کافی است:

{
  "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