Frontend/SMART_IRRIGATION_BACKEND_INTEGRATION.md

Smart Irrigation Backend Integration

این فایل مشخص می کند صفحه src/views/dashboards/farm/smartIrrigation/SmartIrrigationRecommendation.tsx برای کار کامل با بک‌اند دقیقا چه داده هایی لازم دارد و از کدام endpointها باید استفاده کند.

هدف این سند:

• حذف داده های ماک
• مشخص شدن contract حداقلی بین فرانت و بک‌اند
• معلوم شدن این که هر بخش UI از کدام فیلد تغذیه می شود

---

1) دریافت محصولات انتخاب شده مزرعه

Endpoint

GET /api/plants/selected/?farm_uuid=<uuid>

کاربرد در UI

برای این بخش ها استفاده می شود:

• نمایش لیست محصول ها برای انتخاب
• گرفتن stageهای هر محصول
• انتخاب مقدار اولیه selectedCrop
• انتخاب مقدار اولیه growthStage

فیلدهای لازم از response

{
  "data": [
    {
      "name": "گوجه فرنگی",
      "icon": "tabler-carrot",
      "growth_stages": ["رویشی", "گلدهی", "میوه دهی"]
    }
  ]
}

فیلدهای مصرفی

• data[].name
  • برای crop.id
  • برای crop.name
• data[].icon
  • برای آیکن کارت محصول
• data[].growth_stages[]
  • برای لیست stageها

---

2) تولید recommendation آبیاری

Endpoint

POST /api/irrigation/recommend/

Request payload مورد نیاز فرانت

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه فرنگی",
  "growth_stage": "گلدهی"
}

نکته مهم

در UI فعلی برای recommendation فقط این سه فیلد برای request لازم هستند:

• farm_uuid
• plant_name
• growth_stage

---

3) فیلدهای لازم از response recommendation

فرانت در وضعیت فعلی فقط این بخش ها را برای نمایش نتیجه لازم دارد.

ساختار کلی مورد نیاز

{
  "code": 200,
  "msg": "success",
  "data": {
    "recommendation_uuid": "uuid",
    "crop_id": "گوجه فرنگی",
    "plant_name": "گوجه فرنگی",
    "growth_stage": "گلدهی",
    "irrigation_method_name": "آبیاری قطره ای",
    "status": "pending_confirmation",
    "status_label": "منتظر تایید",
    "plan": {},
    "water_balance": {},
    "timeline": [],
    "sections": []
  }
}

---

4) مصرف دقیق هر فیلد در UI recommendation

4.1) هدر صفحه نتیجه

برای نوار بالای صفحه نتیجه:

• data.plant_name
• data.growth_stage

کاربرد:

• ساخت resultContext
• نمایش عنوان بالای صفحه بعد از تولید recommendation

---

4.2) کارت Instruction Details

این کارت از این فیلدها تغذیه می شود:

از plan

• plan.frequencyPerWeek
• plan.durationMinutes
• plan.bestTimeOfDay
• plan.moistureLevel

از water_balance

• water_balance.daily[].gross_irrigation_mm

نمونه حداقلی

{
  "plan": {
    "frequencyPerWeek": 4,
    "durationMinutes": 38,
    "bestTimeOfDay": "05:30 تا 08:00 صبح",
    "moistureLevel": 72,
    "warning": "در ساعات گرم روز آبیاری انجام نشود"
  },
  "water_balance": {
    "daily": [
      {
        "gross_irrigation_mm": 17
      }
    ]
  }
}

نکته

در UI فعلی مقدار Water Amount با تکیه بر:

• water_balance.daily[0].gross_irrigation_mm
• و مساحت انتخابی در فرانت محاسبه می شود.

اگر بخواهید محاسبه دقیق تر و backend-driven شود، بهتر است بک‌اند یکی از این دو را هم بدهد:

• recommended_liters_per_hectare
• یا recommended_total_liters

اما فعلا UI بدون اینها هم کار می کند.

---

4.3) Gauge / Circular Indicator

برای gauge فقط این دو مقدار لازم است:

• plan.moistureLevel
• water_balance.daily لازم نیست

و اگر بخواهید target هم از بک‌اند بیاید، بهتر است این فیلد اضافه شود:

• target_moisture

وضعیت فعلی

در نسخه فعلی فرانت هنوز یک target mock-style استفاده می کند. برای اتصال کامل بهتر است بک‌اند این فیلد را هم داخل plan برگرداند:

{
  "plan": {
    "moistureLevel": 72,
    "targetMoisture": 78
  }
}

پیشنهاد

اگر ممکن است این فیلد به response اضافه شود:

• plan.targetMoisture

---

4.4) تراز آب و نیاز روزانه

این بخش مستقیما از water_balance استفاده می کند.

فیلدهای لازم

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

فیلدهای مصرفی

از 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 اصلی مستقیم رندر نمی شود، ولی برای آینده مفید است

---

4.5) Stepper مراحل و دستورالعمل اجرا

برای این بخش فقط timeline لازم است.

ساختار لازم

{
  "timeline": [
    {
      "step_number": 1,
      "title": "بررسی فشار",
      "description": "فشار ابتدا و انتهای لاین کنترل شود"
    }
  ]
}

فیلدهای مصرفی

• timeline[].step_number
• timeline[].title
• timeline[].description

نکته

در UI فعلی این فیلدها کافی هستند. فیلدهایی مثل time_label یا state فعلا لازم نیستند.

---

4.6) هشدارها و نکات

این بخش از plan.warning و sections استفاده می کند.

فیلدهای لازم

{
  "plan": {
    "warning": "در ساعات گرم روز آبیاری انجام نشود"
  },
  "sections": [
    {
      "title": "هشدار تبخیر بالا",
      "icon": "tabler-alert-triangle",
      "type": "warning",
      "content": "در ساعات گرم روز آبیاری انجام نشود"
    },
    {
      "title": "نکته بهره وری",
      "icon": "tabler-bulb",
      "type": "tip",
      "content": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
    }
  ]
}

مصرف در UI

هشدارها

• plan.warning
• sections[].type === "warning"
• sections[].content

نکات پایین صفحه

• sections[].type === "tip"
• sections[].title
• sections[].icon
• sections[].content

---

5) حداقل response پیشنهادی برای recommendation

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

{
  "code": 200,
  "msg": "success",
  "data": {
    "recommendation_uuid": "8a4c22d8-3f75-4aef-8e04-b40f6b4a2d11",
    "crop_id": "گوجه فرنگی",
    "plant_name": "گوجه فرنگی",
    "growth_stage": "گلدهی",
    "irrigation_method_name": "آبیاری قطره ای",
    "status": "pending_confirmation",
    "status_label": "منتظر تایید",
    "plan": {
      "frequencyPerWeek": 4,
      "durationMinutes": 38,
      "bestTimeOfDay": "05:30 تا 08:00 صبح",
      "moistureLevel": 72,
      "targetMoisture": 78,
      "warning": "در ساعات گرم روز آبیاری انجام نشود"
    },
    "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": "بررسی فشار",
        "description": "فشار ابتدا و انتهای لاین کنترل شود"
      }
    ],
    "sections": [
      {
        "title": "هشدار تبخیر بالا",
        "icon": "tabler-alert-triangle",
        "type": "warning",
        "content": "در ساعات گرم روز آبیاری انجام نشود"
      },
      {
        "title": "نکته بهره وری",
        "icon": "tabler-bulb",
        "type": "tip",
        "content": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
      }
    ]
  }
}

---

6) history recommendationهای آبیاری

Endpoint

GET /api/irrigation/recommendations/?farm_uuid=<uuid>&page=1&page_size=10

کاربرد در UI

برای جدول history پایین فرم استفاده می شود.

فیلدهای لازم هر آیتم

{
  "recommendation_uuid": "uuid",
  "plant_name": "گوجه فرنگی",
  "growth_stage": "گلدهی",
  "irrigation_method_name": "آبیاری قطره ای",
  "status": "pending_confirmation",
  "status_label": "منتظر تایید",
  "requested_at": "2025-02-12T09:30:00Z"
}

نکته مهم برای فرانت فعلی

در کد فعلی جدول history این فیلد را به عنوان ستون روش آبیاری می خواهد:

• irrigation_method

اما طبق contract بک‌اند، فیلد موجود این است:

• irrigation_method_name

نتیجه

برای اتصال کامل یکی از این دو کار باید انجام شود:

1. یا فرانت irrigation_method_name را بخواند
2. یا بک‌اند علاوه بر آن، فیلد irrigation_method هم برگرداند

پیشنهاد بهتر:

• فرانت را با irrigation_method_name align کنید

pagination لازم

{
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_pages": 1,
    "total_items": 1,
    "has_next": false,
    "has_previous": false,
    "next": null,
    "previous": null
  }
}

---

7) جزئیات یک recommendation

Endpoint

GET /api/irrigation/recommendations/{recommendation_uuid}/

کاربرد در UI

وقتی کاربر از جدول history روی آیکن گزارش کلیک می کند، این endpoint باید صدا زده شود.

ساختار لازم

خروجی این endpoint باید همان shape endpoint recommendation اصلی را برگرداند؛ یعنی:

• recommendation_uuid
• plant_name
• growth_stage
• irrigation_method_name
• status
• status_label
• plan
• water_balance
• timeline
• sections

---

8) فیلدهایی که فعلا در UI لازم نیستند

این فیلدها در نسخه فعلی صفحه ضروری نیستند:

• raw_response
• crop_id (اگر plant_name وجود داشته باشد)
• sensor_uuid
• status در خود recommendation result page
• generated_at
• final_verdict
• recommendation_title
• recommendation_subtitle
• primary_method
• usage_summary
• alternative_plans
• sections[].type = schedule
• sections[].type = method

---

9) جمع بندی نهایی

برای این صفحه اگر بخواهیم فقط داده های ضروری از بک‌اند بگیریم، این endpointها کافی هستند:

1. GET /api/plants/selected/
2. POST /api/irrigation/recommend/
3. GET /api/irrigation/recommendations/
4. GET /api/irrigation/recommendations/{recommendation_uuid}/

و برای recommendation page حداقل این بخش های response باید حتما وجود داشته باشند:

• plant_name
• growth_stage
• plan
• water_balance
• timeline
• sections

و برای history:

• recommendation_uuid
• plant_name
• growth_stage
• irrigation_method_name
• status
• status_label
• requested_at
• pagination