Backend/docs/yield_harvest_prediction_api_changes.md

Yield/Harvest Prediction API Changes

این فایل تغییرات 3 API زیر را توضیح می‌دهد:

• POST /api/yield-harvest/harvest-prediction/
• POST /api/yield-harvest/yield-prediction/
• POST /api/yield-harvest/current-farm-chart/

---

خلاصه تغییرات

تغییر اصلی در هر 3 endpoint این است که backend حالا context موردنیاز AI را خودش از روی مزرعه و planهای انتخابی می‌سازد.

قبل

در استفاده قدیمی، معمولاً فرض می‌شد client باید context بیشتری برای AI بفرستد.

الآن

• farm_uuid ورودی اصلی و الزامی است.
• plant_name اگر هم توسط client ارسال شود، مبنای نهایی backend نیست و از روی مزرعه بازنویسی/resolve می‌شود.
• در صورت نیاز، irrigation_plan_uuid و fertilization_plan_uuid هم می‌توانند ارسال شوند.
• اگر plan انتخابی معتبر و متعلق به همان مزرعه کاربر باشد، backend محتوای آن را به payload ارسالی به AI اضافه می‌کند.
• خروجی backend به‌صورت یکدست با فرمت code / msg / data برگردانده می‌شود.

---

Request Contract جدید

هر 3 API از این قرارداد ورودی استفاده می‌کنند:

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "irrigation_plan_uuid": "6d6a1f0d-1a9b-4f2f-8fe1-2d73d9d2d9f1",
  "fertilization_plan_uuid": "7e7b2f1e-2b0c-4a3a-9fe2-3e84e0e3e0a2"
}

فیلدها

• farm_uuid اجباری
• irrigation_plan_uuid اختیاری
• fertilization_plan_uuid اختیاری

نکته مهم

اگر client plant_name بفرستد، در این APIها مبنای نهایی backend نیست؛ backend نام گیاه را از مزرعه استخراج می‌کند.

---

1) POST /api/yield-harvest/current-farm-chart/

تغییرات

• ورودی endpoint عملاً بر پایه farm_uuid کار می‌کند و plant_name از context مزرعه تعیین می‌شود.
• backend به‌صورت خودکار plant_name را از مزرعه پیدا می‌کند.
• در صورت ارسال irrigation_plan_uuid، اطلاعات برنامه آبیاری داخل payload ارسالی به AI قرار می‌گیرد.
• در صورت ارسال fertilization_plan_uuid، اطلاعات برنامه کودی هم اضافه می‌شود.

نمونه request

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111"
}

payload ارسالی backend به AI

نمونه مفهومی:

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

در صورت انتخاب plan

نمونه مفهومی:

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "irrigation_plan": {
    "id": 12,
    "plan_payload": {
      "plan": {
        "durationMinutes": 20
      }
    }
  }
}

پاسخ موفق

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "plant_name": "گوجه‌فرنگی",
    "scenario_id": 1,
    "categories": ["day1"],
    "series": {
      "biomass": [1.2]
    }
  }
}

---

2) POST /api/yield-harvest/harvest-prediction/

تغییرات

• ورودی endpoint عملاً بر پایه farm_uuid کار می‌کند و plant_name توسط backend تعیین می‌شود.
• امکان ارسال fertilization_plan_uuid و irrigation_plan_uuid برای enrich کردن context اضافه/پشتیبانی شده است.
• پاسخ AI بعد از extract شدن در data.result، به شکل مستقیم در data برگردانده می‌شود.

نمونه request

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "fertilization_plan_uuid": "7e7b2f1e-2b0c-4a3a-9fe2-3e84e0e3e0a2"
}

payload ارسالی backend به AI

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "fertilization_plan": {
    "id": 34,
    "plan_payload": {
      "primary_recommendation": {
        "fertilizer_code": "npk-151515"
      }
    }
  }
}

پاسخ موفق

{
  "code": 200,
  "msg": "success",
  "data": {
    "date": "2026-07-15",
    "dateFormatted": "15 Jul 2026",
    "daysUntil": 96,
    "gddDetails": {
      "current": 800
    }
  }
}

---

3) POST /api/yield-harvest/yield-prediction/

تغییرات

• مثل دو endpoint دیگر، plant_name از روی مزرعه resolve می‌شود.
• در نبود محصول مستقیم روی مزرعه، backend از fallback مناسب مزرعه استفاده می‌کند.
• امکان ارسال irrigation_plan_uuid و fertilization_plan_uuid برای فرستادن context planها به AI اضافه/پشتیبانی شده است.
• پاسخ نهایی با ساختار یکنواخت code / msg / data برگردانده می‌شود.

نمونه request

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "irrigation_plan_uuid": "6d6a1f0d-1a9b-4f2f-8fe1-2d73d9d2d9f1",
  "fertilization_plan_uuid": "7e7b2f1e-2b0c-4a3a-9fe2-3e84e0e3e0a2"
}

payload ارسالی backend به AI

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "irrigation_plan": {
    "id": 12,
    "plan_payload": {
      "plan": {
        "durationMinutes": 30
      }
    }
  },
  "fertilization_plan": {
    "id": 34,
    "plan_payload": {
      "primary_recommendation": {
        "fertilizer_code": "npk-202020"
      }
    }
  }
}

پاسخ موفق

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "predictedYieldTons": 8.4,
    "scenarioId": 1
  }
}

---

خطاها و Validation

1) مزرعه نامعتبر یا متعلق به کاربر دیگر

در این حالت endpoint خطای دسترسی/یافت‌نشدن مزرعه برمی‌گرداند.

2) plan نامعتبر یا متعلق به مزرعه دیگر

اگر irrigation_plan_uuid یا fertilization_plan_uuid متعلق به همان مزرعه کاربر نباشد، درخواست با خطا رد می‌شود.

نمونه:

{
  "code": 404,
  "msg": "error",
  "data": {
    "irrigation_plan_uuid": [
      "Irrigation plan not found."
    ]
  }
}

3) خطای validation ورودی

اگر farm_uuid ارسال نشود یا plan_uuidها نامعتبر باشند، serializer خطای validation برمی‌گرداند.

---

جمع‌بندی تغییرات برای فرانت

• دیگر لازم نیست plant_name را برای این 3 API بفرستید.
• فقط farm_uuid اجباری است.
• اگر کاربر plan خاصی را انتخاب کرده، irrigation_plan_uuid و/یا fertilization_plan_uuid را هم بفرستید.
• response هر 3 endpoint با ساختار یکنواخت code, msg, data برمی‌گردد.
• backend خودش payload مناسب AI را از context مزرعه و planهای انتخابی می‌سازد.