Logic/Modules/Ai/irrigation/IRRIGATION_RECOMMENDATION_API_FIELDS.md

Irrigation Recommendation API Fields

این فایل فقط فیلدهای API مربوط به POST /api/irrigation/recommend/ را توضیح می‌دهد.

Endpoint

POST /api/irrigation/recommend/

کاربرد

این endpoint برای تولید recommendation آبیاری استفاده می‌شود و خروجی آن با UI فعلی صفحه src/views/dashboards/farm/smartIrrigation/SmartIrrigationRecommendation.tsx هماهنگ شده است.

ساختار کلی پاسخ

{
  "code": 200,
  "msg": "success",
  "data": {
    "plan": {},
    "water_balance": {},
    "timeline": [],
    "sections": []
  }
}

Request

حداقل payload پیشنهادی

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "growth_stage": "گلدهی",
  "irrigation_type": "آبیاری قطره‌ای"
}

فیلدهای Request

farm_uuid

• نوع: string
• اجباری: بله
• توضیح: شناسه یکتای مزرعه.

sensor_uuid

• نوع: string
• اجباری: خیر
• توضیح: نام قدیمی برای farm_uuid. اگر farm_uuid ارسال نشده باشد، این مقدار به جای آن استفاده می‌شود.

plant_name

• نوع: string
• اجباری: خیر
• توضیح: نام گیاه هدف برای تولید توصیه. اگر ارسال نشود، سیستم در صورت امکان گیاه ثبت‌شده روی مزرعه را استفاده می‌کند.

growth_stage

• نوع: string
• اجباری: خیر
• توضیح: مرحله رشد گیاه مثل رویشی، گلدهی یا میوه‌دهی.

irrigation_type

• نوع: string
• اجباری: خیر
• توضیح: نوع یا نام روش آبیاری مورد نظر فرانت. این فیلد برای UI فعلی پیشنهاد می‌شود.

irrigation_method_name

• نوع: string
• اجباری: خیر
• توضیح: نام روش آبیاری. این فیلد با irrigation_type هم‌ارز است و در بک‌اند به همان ورودی نهایی نرمال می‌شود.

Response

فیلدهای لایه اول Response

code

• نوع: number
• توضیح: کد وضعیت پاسخ در قالب استاندارد API پروژه.

msg

• نوع: string
• توضیح: پیام وضعیت پاسخ. در حالت موفق معمولاً success است.

data

• نوع: object
• توضیح: بدنه اصلی recommendation آبیاری.

فیلدهای data

plan

• نوع: object
• توضیح: خلاصه اصلی recommendation برای نمایش در کارت بالای UI.

water_balance

• نوع: object
• توضیح: تراز آب و خروجی محاسبات روزانه FAO-56.

timeline

• نوع: array
• توضیح: مراحل اجرایی recommendation برای Stepper.

sections

• نوع: array
• توضیح: نکات تکمیلی و هشدارها. در UI فعلی فقط warning و tip مصرف می‌شوند.

فیلدهای data.plan

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

frequencyPerWeek

• نوع: number
• توضیح: تعداد نوبت آبیاری در هفته.

durationMinutes

• نوع: number
• توضیح: مدت هر نوبت آبیاری بر حسب دقیقه.

bestTimeOfDay

• نوع: string
• توضیح: بهترین بازه زمانی اجرای آبیاری.

moistureLevel

• نوع: number
• توضیح: سطح رطوبت فعلی یا هدف خاک برای نمایش در gauge.

warning

• نوع: string
• توضیح: هشدار اصلی recommendation.

فیلدهای data.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"
    }
  ]
}

active_kc

• نوع: number
• توضیح: ضریب Kc فعال برای مرحله رشد فعلی.

crop_profile

• نوع: object
• توضیح: پروفایل Kc گیاه در مراحل مختلف.

daily

• نوع: array
• توضیح: داده‌های روزانه مورد استفاده در جدول یا نمودار تراز آب.

فیلدهای data.water_balance.crop_profile

kc_initial

• نوع: number
• توضیح: Kc مرحله ابتدایی رشد.

kc_mid

• نوع: number
• توضیح: Kc مرحله میانی رشد.

kc_end

• نوع: number
• توضیح: Kc مرحله پایانی رشد.

فیلدهای هر آیتم در data.water_balance.daily[]

forecast_date

• نوع: string
• توضیح: تاریخ پیش‌بینی.

et0_mm

• نوع: number
• توضیح: تبخیر و تعرق مرجع روزانه.

etc_mm

• نوع: number
• توضیح: تبخیر و تعرق گیاه.

effective_rainfall_mm

• نوع: number
• توضیح: بارش مؤثر محاسبه‌شده.

gross_irrigation_mm

• نوع: number
• توضیح: مقدار آبیاری ناخالص پیشنهادی برای آن روز.

irrigation_timing

• نوع: string
• توضیح: زمان پیشنهادی اجرای آبیاری برای آن روز.

فیلدهای data.timeline

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

step_number

• نوع: number
• توضیح: شماره مرحله.

title

• نوع: string
• توضیح: عنوان مرحله.

description

• نوع: string
• توضیح: توضیح اجرایی مرحله.

فیلدهای data.sections

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

title

• نوع: string
• توضیح: عنوان کارت.

icon

• نوع: string
• توضیح: نام آیکون مورد استفاده در UI.

type

• نوع: string
• توضیح: نوع سکشن. در UI فعلی فقط این مقادیر مصرف می‌شوند:
  • warning
  • tip

content

• نوع: string
• توضیح: متن هشدار یا نکته.

حداقل پاسخ قابل استفاده برای UI فعلی

{
  "code": 200,
  "msg": "success",
  "data": {
    "plan": {
      "frequencyPerWeek": 4,
      "durationMinutes": 38,
      "bestTimeOfDay": "05:30 تا 08:00 صبح",
      "moistureLevel": 72,
      "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": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
      }
    ]
  }
}

فیلدهایی که فرانت فعلی لازم ندارد

فیلدهای زیر برای UI فعلی recommendation لازم نیستند و نباید به عنوان dependency فرانت در نظر گرفته شوند:

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

نمونه cURL

curl -s -X POST "http://localhost:8000/api/irrigation/recommend/" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "plant_name": "گوجه‌فرنگی",
    "growth_stage": "گلدهی",
    "irrigation_type": "آبیاری قطره‌ای"
  }'