Backend/RECOMMENDATION_APIS.md

مستندات APIهای توصیه و تشخیص

این سند سه گروه API را شرح می‌دهد: توصیه آبیاری، تشخیص آفت و توصیه کوددهی. همهٔ پاسخ‌ها در حال حاضر از دادهٔ ثابت (mock) برگردانده می‌شوند و پارامترهای ورودی در پاسخ استفاده نمی‌شوند.

پایهٔ آدرس API: /api/

قالب کلی پاسخ:
{"status": "success", "data": <payload>} — فقط با کد وضعیت HTTP 200.

---

۱. توصیه آبیاری (Irrigation Recommendation)

پیشوند: api/irrigation-recommendation/

۱.۱ دریافت تنظیمات (Config)

• متد: GET
• آدرس: api/irrigation-recommendation/config/
• هدف: برگرداندن اطلاعات مزرعه و لیست گزینه‌های محصول برای فرم توصیه آبیاری (هنگام بارگذاری صفحه).
• ورودی: ندارد. پارامترهای query خوانده یا استفاده نمی‌شوند.

نمونه پاسخ:

{
  "status": "success",
  "data": {
    "farmInfo": {
      "soilType": "Loamy",
      "waterQuality": "Medium EC",
      "climateZone": "Temperate"
    },
    "cropOptions": [
      {"id": "wheat", "labelKey": "wheat", "icon": "tabler-wheat"},
      {"id": "corn", "labelKey": "corn", "icon": "tabler-plant-2"},
      {"id": "cotton", "labelKey": "cotton", "icon": "tabler-flower"},
      {"id": "saffron", "labelKey": "saffron", "icon": "tabler-flower-2"},
      {"id": "canola", "labelKey": "canola", "icon": "tabler-leaf"},
      {"id": "vegetables", "labelKey": "vegetables", "icon": "tabler-carrot"}
    ]
  }
}

فیلد	نوع	توضیح
farmInfo.soilType	string	نوع خاک
farmInfo.waterQuality	string	کیفیت آب (مثلاً EC)
farmInfo.climateZone	string	منطقه اقلیمی
cropOptions	array	لیست محصولات: id, labelKey, icon

---

۱.۲ دریافت توصیه آبیاری (Recommend)

• متد: POST
• آدرس: api/irrigation-recommendation/recommend/
• هدف: برگرداندن یک برنامهٔ آبیاری ثابت (تعداد در هفته، مدت، بهترین زمان، رطوبت، هشدار).
• ورودی (بدن درخواست، اختیاری): می‌توانید JSON با فیلدهایی مثل crop_id, soilType, waterQuality, climateZone بفرستید؛ در پاسخ فعلی استفاده نمی‌شوند.
• CSRF: این endpoint از CSRF معاف است (برای فراخوانی از فرانت بدون توکن).

نمونه پاسخ:

{
  "status": "success",
  "data": {
    "plan": {
      "frequencyPerWeek": 4,
      "durationMinutes": 45,
      "bestTimeOfDay": "05:00 - 07:00",
      "moistureLevel": 72,
      "warning": "Avoid irrigation during midday hours in the coming week due to forecasted high temperatures."
    }
  }
}

فیلد	نوع	توضیح
plan.frequencyPerWeek	number	تعداد آبیاری در هفته
plan.durationMinutes	number	مدت هر نوبت (دقیقه)
plan.bestTimeOfDay	string	بهترین بازه زمانی روز
plan.moistureLevel	number	سطح رطوبت هدف (درصد)
plan.warning	string	هشدار یا توصیه اضافه

---

۲. تشخیص آفت (Pest Detection)

پیشوند: api/pest-detection/

۲.۱ تحلیل تصویر (Analyze)

• متد: POST
• آدرس: api/pest-detection/analyze/
• هدف: برگرداندن نتیجهٔ ثابت تشخیص آفت (نام آفت، اطمینان، توضیح، درمان) — برای زمانی که کاربر تصویر گیاه را آپلود و درخواست تحلیل می‌کند.
• ورودی (بدن درخواست، اختیاری): JSON یا form-data (مثلاً شامل image یا file). در پاسخ فعلی استفاده نمی‌شود.
• CSRF: این endpoint از CSRF معاف است.

نمونه پاسخ:

{
  "status": "success",
  "data": {
    "pest": "شپشک",
    "confidence": 92,
    "description": "حشرات کوچک مکنده شیره که باعث پیچ خوردگی برگ می‌شوند.",
    "treatment": "یک بار در هفته از اسپری روغن نیم استفاده کنید."
  }
}

فیلد	نوع	توضیح
pest	string	نام آفت
confidence	number	درصد اطمینان (۰–۱۰۰)
description	string	توضیح کوتاه آفت
treatment	string	توصیه درمان

---

۳. توصیه کوددهی (Fertilization Recommendation)

پیشوند: api/fertilization-recommendation/

۳.۱ دریافت تنظیمات (Config)

• متد: GET
• آدرس: api/fertilization-recommendation/config/
• هدف: برگرداندن دادهٔ مزرعه، مراحل رشد و گزینه‌های محصول برای فرم توصیه کوددهی (هنگام بارگذاری صفحه).
• ورودی: ندارد.

نمونه پاسخ:

{
  "status": "success",
  "data": {
    "farmData": {
      "soilType": "Loamy",
      "organicMatter": "Medium (2.5%)",
      "waterEC": "1.2 dS/m"
    },
    "growthStages": [
      {"id": "prePlanting", "icon": "tabler-seedling"},
      {"id": "earlyGrowth", "icon": "tabler-leaf"},
      {"id": "flowering", "icon": "tabler-flower"},
      {"id": "fruiting", "icon": "tabler-apple"},
      {"id": "postHarvest", "icon": "tabler-basket"}
    ],
    "cropOptions": [
      {"id": "wheat", "labelKey": "wheat", "icon": "tabler-wheat"},
      {"id": "corn", "labelKey": "corn", "icon": "tabler-plant-2"},
      {"id": "cotton", "labelKey": "cotton", "icon": "tabler-flower"},
      {"id": "saffron", "labelKey": "saffron", "icon": "tabler-flower-2"},
      {"id": "canola", "labelKey": "canola", "icon": "tabler-leaf"},
      {"id": "vegetables", "labelKey": "vegetables", "icon": "tabler-carrot"}
    ]
  }
}

فیلد	نوع	توضیح
farmData.soilType	string	نوع خاک
farmData.organicMatter	string	ماده آلی خاک
farmData.waterEC	string	EC آب
growthStages	array	مراحل رشد: id, icon
cropOptions	array	لیست محصولات: id, labelKey, icon

---

۳.۲ دریافت توصیه کوددهی (Recommend)

• متد: POST
• آدرس: api/fertilization-recommendation/recommend/
• هدف: برگرداندن یک برنامهٔ کوددهی ثابت (نسبت NPK، مقدار در هکتار، روش و فاصله مصرف، استدلال).
• ورودی (بدن درخواست، اختیاری): JSON با فیلدهایی مثل crop_id, growth_stage, soilType, organicMatter, waterEC. در پاسخ فعلی استفاده نمی‌شوند.
• CSRF: این endpoint از CSRF معاف است.

نمونه پاسخ:

{
  "status": "success",
  "data": {
    "plan": {
      "npkRatio": "20-20-20 (NPK)",
      "amountPerHectare": "150 kg/ha",
      "applicationMethod": "Foliar spray + soil broadcast",
      "applicationInterval": "Every 14 days",
      "reasoning": "Your loamy soil with medium organic matter (2.5%) provides good nutrient retention. Water EC of 1.2 dS/m indicates low salinity—suitable for most crops. At the flowering stage, increased phosphorus supports bloom development. We recommend a balanced NPK to maintain nitrogen for vegetative growth while boosting phosphorous for flowering."
    }
  }
}

فیلد	نوع	توضیح
plan.npkRatio	string	نسبت NPK پیشنهادی
plan.amountPerHectare	string	مقدار مصرف در هکتار
plan.applicationMethod	string	روش مصرف (مثلاً محلول‌پاشی، خاکی)
plan.applicationInterval	string	فاصله بین مصرف
plan.reasoning	string	توضیح/استدلال توصیه

---

خلاصه Endpointها

ماژول	متد	Endpoint
Irrigation	GET	/api/irrigation-recommendation/config/
Irrigation	POST	/api/irrigation-recommendation/recommend/
Pest Detection	POST	/api/pest-detection/analyze/
Fertilization	GET	/api/fertilization-recommendation/config/
Fertilization	POST	/api/fertilization-recommendation/recommend/

---

توجه: در نسخهٔ فعلی هیچ پردازش، اعتبارسنجی یا استفاده از پارامترهای ورودی در پاسخ انجام نمی‌شود؛ همهٔ خروجی‌ها از دادهٔ ثابت (mock) هستند.