Ai/API_RELIABILITY_AUDIT_FA.md

ممیزی ضعف‌ها و میزان اعتماد APIها

این سند بر اساس بررسی کد فعلی پروژه نوشته شده است و هدفش این است که برای هر API مشخص کند:

• خروجی روی چه داده یا فرمولی تکیه دارد
• کجاها خروجی صرفا تقریبی، heuristic، mock یا وابسته به LLM است
• برای چه نوع استفاده‌ای قابل اتکا هست و برای چه نوع تصمیمی نیست
• سطح اعتماد عملی به پاسخ خروجی چقدر است

توجه:

• این سند درباره قابلیت اتکای عملیاتی است، نه فقط درست بودن ساختار JSON.
• ممکن است یک API از نظر فنی همیشه JSON درست برگرداند، اما از نظر agronomy یا تصمیم‌سازی هنوز کم‌اعتماد باشد.
• سطح اعتماد به معنی اعتماد به محتوای پاسخ است، نه availability سرویس.

معیار سطح اعتماد

• زیاد: عمدتا داده واقعی یا ذخیره شده برمی‌گرداند؛ فرمول یا منطق ساده ولی قابل توضیح است؛ برای نمایش و گزارش مناسب است.
• متوسط: داده واقعی دارد اما بخش مهمی از نتیجه وابسته به تقریب، پیش‌فرض، شبیه‌سازی، یا LLM است.
• کم: نتیجه بیشتر heuristic، fallback، برآورد تقریبی، یا تلفیق داده ناقص است.
• خیلی کم: داده mock، stub، یا خروجی عمدتا غیرقابل اتکا برای تصمیم واقعی.

خلاصه سریع APIهای پرریسک

• POST /api/economy/overview/: داده کاملا mock است؛ برای تصمیم واقعی نباید استفاده شود.
• POST /api/plants/fetch-info/: عملا پیاده‌سازی نشده و 503 برمی‌گرداند.
• POST /api/irrigation/water-stress/: اگر engine شبیه‌سازی خطا بدهد هنوز به فرمول ساده سنسور fallback می‌کند.
• POST /api/pest-disease/detect/ و POST /api/pest-disease/risk/: وابستگی مستقیم به RAG/LLM دارند؛ برای KPI قطعی یا تصمیم سم‌پاشی خودکار مناسب نیستند.
• POST /api/farm-alerts/tracker/ و POST /api/farm-alerts/timeline/: ترکیب rule-based + LLM هستند؛ برای آگاهی خوب‌اند ولی برای اتوماسیون بحرانی نه.
• POST /api/soile/moisture-heatmap/: visualization خوبی می‌دهد اما هنوز geostatistics دقیق یا history واقعی سنسورها را مدل نمی‌کند.

---

1) Soil Data API

GET|POST /api/soil-data/

• منبع داده:
  • اگر رکورد کامل موجود باشد از DB برمی‌گردد.
  • اگر موجود نباشد فقط task صف می‌شود و 202 می‌دهد.
• ضعف‌ها:
  • در حالت 202 هنوز خود داده خاک برنگشته، فقط شروع فرآیند واکشی اعلام می‌شود.
  • تطابق location بر اساس lat/lon گرد شده تا 6 رقم است؛ برای نقاط خیلی نزدیک ممکن است حساسیت مکانی محدود شود.
  • کیفیت نهایی کاملا وابسته به سرویس بیرونی خاک و کامل شدن depthهاست.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • این API خودش مدل پیش‌بینی ندارد؛ ریسک اصلی از ناقص بودن داده منبع یا incomplete بودن رکورد است.
• مناسب برای:
  • واکشی داده خام خاک و persistence.
• نامناسب برای:
  • استنتاج agronomy بدون بررسی منبع و completeness.
• سطح اعتماد:
  • زیاد وقتی source=database و location کامل است.
  • کم وقتی فقط task_id گرفته‌اید و هنوز داده واقعی ندارید.

GET /api/soil-data/tasks/{task_id}/status/

• منبع داده: وضعیت Celery + نتیجه ذخیره شده در DB.
• ضعف‌ها:
  • ممکن است task موفق شده باشد ولی رکورد location هنوز کامل نباشد.
  • خروجی SUCCESS لزوما به معنی کیفیت agronomic داده نیست؛ فقط completion فنی را نشان می‌دهد.
• سطح اعتماد:
  • متوسط برای وضعیت فنی task.
  • کم تا متوسط برای اعتماد به خود محتوای خاک، بسته به کامل بودن رکورد.

POST /api/soil-data/ndvi-health/

• منبع داده: observation ماهواره‌ای NDVI در location_data.ndvi.
• ضعف‌ها:
  • اگر observation موجود نباشد، کارت عملا به وضعیت Unavailable می‌رسد.
  • تفسیر NDVI ساده است و به تنهایی برای تشخیص علت تنش کافی نیست.
  • NDVI میانگین مزرعه است؛ heterogeneity داخل مزرعه را کامل نشان نمی‌دهد.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • NDVI فقط شاخص پوشش گیاهی است، نه تشخیص علت؛ کمبود آب، بیماری، تغذیه یا خطای سنجش ممکن است با هم اشتباه شوند.
• سطح اعتماد:
  • متوسط برای پایش کلی وضعیت پوشش گیاهی.
  • کم برای تصمیم‌گیری علّی یا درمانی.

---

2) Soile API

POST /api/soile/moisture-heatmap/

• منبع داده:
  • latest measurement هر سنسور
  • وزن‌دهی تازگی داده
  • جریمه outlier
  • interpolation از نوع weighted IDW
  • mask مرز مزرعه
• ضعف‌ها:
  • history واقعی سنسورها هنوز مدل نمی‌شود.
  • drift سنسور، calibration uncertainty و quality assurance واقعی لحاظ نشده‌اند.
  • depth-specific map به صورت measured واقعی نیست و بخشی از لایه‌ها از soil profile مشتق می‌شوند.
  • uncertainty به صورت heuristic برآورد می‌شود.
  • با تراکم سنسور پایین یا farm نامتقارن، heatmap بیشتر visualization است تا اندازه‌گیری دقیق.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • مدل interpolation علمی پیشرفته مثل kriging یا مدل uncertainty مکانی ندارد.
  • خروجی برای zoning دقیق agronomy کافی نیست.
• سطح اعتماد:
  • متوسط برای visualization و درک trend کلی.
  • کم برای تصمیم آبیاری دقیق نقطه‌ای یا نسخه agronomy.

POST /api/soile/health-summary/

• منبع داده: داده سنسور + خلاصه‌ساز سلامت خاک.
• ضعف‌ها:
  • خلاصه سلامت ذاتا compression از چند متریک است و همه context مزرعه را در بر نمی‌گیرد.
  • اگر سنسورهای مزرعه کم‌تعداد یا داده‌هایشان قدیمی باشد، summary گمراه‌کننده می‌شود.
• سطح اعتماد:
  • متوسط برای dashboard summary.
  • کم تا متوسط برای تصمیم اصلاح خاک بدون نمونه‌برداری میدانی.

POST /api/soile/anomaly-detection/

• منبع داده: anomaly آماری + تفسیر RAG.
• ضعف‌ها:
  • anomaly detection بر اساس context موجود است و به history و baseline کامل چندفصلی متکی نیست.
  • تفسیر نهایی توسط RAG تولید می‌شود و deterministic نیست.
  • اگر anomaly آماری واقعی نباشد، LLM ممکن است فقط آن را با متن تخصصی بسط دهد.
• سطح اعتماد:
  • متوسط برای پیدا کردن موارد مشکوک.
  • کم برای diagnosis نهایی بدون تایید کارشناس.

---

3) Weather API

POST /api/weather/farm-card/

• منبع داده: forecastهای ذخیره‌شده در DB از سرویس هواشناسی خارجی.
• ضعف‌ها:
  • docstring سرویس هنوز misleading است، ولی کد واقعا requests.get می‌زند.
  • اگر forecast تازه نباشد، کارت weather کهنه می‌شود.
  • کارت فقط summary ساده از forecast است و uncertainty پیش‌بینی هوا را منتقل نمی‌کند.
  • اگر forecast موجود نباشد، خروجی عملا صفر/نامشخص می‌شود.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • مشکل اصلی فرمول نیست؛ dependency به forecast خارجی و freshness داده است.
• سطح اعتماد:
  • متوسط تا زیاد وقتی forecast تازه و کامل موجود باشد.
  • کم وقتی داده weather ناقص یا قدیمی باشد.

POST /api/weather/water-need-prediction/

• منبع داده:
  • محاسبات ET/crop profile از irrigation.evapotranspiration
  • forecast هفت‌روزه
  • تفسیر تکمیلی از RAG
• ضعف‌ها:
  • دقت خروجی به کیفیت crop profile، growth stage و راندمان روش آبیاری وابسته است.
  • horizon فقط کوتاه‌مدت است.
  • insight متنی توسط LLM تولید می‌شود و fallback هم دارد.
  • اگر forecast ضعیف باشد، کل محاسبه نیاز آبی ضعیف می‌شود.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • برای برنامه‌ریزی کوتاه‌مدت خوب است، اما irrigation scheduling دقیق در مزرعه واقعی هنوز به سنسور و بازخورد عملی نیاز دارد.
• سطح اعتماد:
  • متوسط برای برنامه‌ریزی 3 تا 7 روزه.
  • کم تا متوسط برای تصمیم اجرایی بدون کنترل میدانی.

---

4) Economy API

POST /api/economy/overview/

• منبع داده: mock صریح در سرویس.
• ضعف‌ها:
  • کل خروجی ساختگی است.
  • اعداد هزینه آب، صرفه‌جویی، درآمد و هزینه کود از مزرعه واقعی استخراج نمی‌شوند.
  • trend chart نیز mock است.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • این API فعلا برای عملیات واقعی قابل اتکا نیست.
• سطح اعتماد:
  • خیلی کم

---

5) Plant API

GET|POST /api/plants/ و GET|PUT|PATCH|DELETE /api/plants/{id}/

• منبع داده: رکوردهای DB.
• ضعف‌ها:
  • اعتماد به محتوای agronomic رکوردها بستگی به کسی دارد که داده را وارد کرده است.
  • validation دامنه‌ای یا علمی عمیق روی محتوا دیده نمی‌شود.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • مشکل اصلی از جنس data governance است، نه الگوریتم.
• سطح اعتماد:
  • زیاد برای این‌که رکوردی که ذخیره شده همان برگردد.
  • متوسط برای اعتماد علمی به محتوای متنی رکوردها.

POST /api/plants/fetch-info/

• منبع داده: قرار بوده API خارجی باشد، ولی فعلا None برمی‌گرداند.
• ضعف‌ها:
  • عملا پیاده‌سازی نشده است.
  • در حالت فعلی 503 می‌دهد.
• سطح اعتماد:
  • خیلی کم

---

6) Farm Data API

POST /api/farm-data/

• منبع داده:
  • boundary مزرعه
  • sensor payload
  • واکشی خودکار location و weather
• نقاط قوت فعلی:
  • مرکز مزرعه با centroid هندسی polygon محاسبه می‌شود، نه average ساده.
  • merge سنسورها flat و overwrite خاموش ندارد؛ payload هر sensor جدا می‌ماند.
• ضعف‌ها:
  • centroid هندسی هنوز برای همه use-caseها بهترین نقطه نمونه‌برداری نیست؛ مخصوصا در مزرعه‌های خیلی کشیده یا چندبخشی.
  • health داده به شدت به درست بودن boundary ورودی وابسته است.
  • location و weather فقط برای یک نقطه مرکزی resolve می‌شوند؛ variability در سطح مزرعه از بین می‌رود.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • این API بیشتر data-ingestion است؛ ضعف اصلی spatial representativeness است.
• سطح اعتماد:
  • زیاد برای ذخیره‌سازی و linkage داده.
  • متوسط برای این فرض که یک center point نماینده کل مزرعه است.

GET /api/farm-data/{farm_uuid}/detail/

• منبع داده:
  • sensor payload
  • soil depth data
  • weather
  • plants و irrigation method
  • resolved_metrics با aggregation deterministic
• نقاط قوت فعلی:
  • conflict چند سنسور silent overwrite نمی‌شود.
  • source هر metric در metric_sources مشخص می‌شود.
• ضعف‌ها:
  • aggregation متریک‌های عددی در تعارض، به average ختم می‌شود؛ این روش همیشه از نظر agronomy بهترین strategy نیست.
  • sensor locality و timestamp تفکیک‌شده در resolved_metrics نهایی از بین می‌رود.
  • برای farm چندناحیه‌ای، یک resolved metric ممکن است variance مهم را پنهان کند.
• سطح اعتماد:
  • متوسط تا زیاد برای unified context.
  • متوسط برای تصمیم نقطه‌ای داخل مزرعه.

POST /api/farm-data/parameters/

• منبع داده: DB و log تغییرات.
• ضعف‌ها:
  • افزودن پارامتر جدید به معنی معتبر بودن agronomic آن نیست.
  • کیفیت metadata وابسته به داده ورودی کاربر است.
• سطح اعتماد:
  • زیاد برای ثبت و نگهداری metadata.
  • متوسط برای معنی علمی metadata.

---

7) Irrigation API

GET|POST /api/irrigation/ و GET /api/irrigation/{id}/

• منبع داده: رکوردهای روش آبیاری در DB.
• ضعف‌ها:
  • درصد راندمان و توضیحات روش آبیاری اگر دستی وارد شده باشند، لزوما calibrated برای مزرعه خاص نیستند.
• سطح اعتماد:
  • زیاد برای بازگرداندن داده ذخیره‌شده.
  • متوسط برای کاربرد agronomic عمومی.

POST /api/irrigation/recommend/

• منبع داده:
  • sensor/farm context
  • plant data
  • irrigation method
  • محاسبات FAO-56 و optimizer
  • متن نهایی از RAG
• نقاط قوت فعلی:
  • پاسخ نهایی provenance دارد و مشخص می‌کند کدام فیلد از LLM و کدام از fallback آمده است.
• ضعف‌ها:
  • merge نهایی هنوز deterministic است و برای پایداری UI fallback را نگه می‌دارد.
  • اگر crop profile، weather یا irrigation method درست نباشد، recommendation قابل اتکا نیست.
  • optimizer و LLM هر دو وابسته به کیفیت ورودی هستند.
  • خروجی ممکن است از نظر ظاهر کامل باشد، حتی وقتی بخشی از آن fallback است.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • برای تصمیم نهایی آبیاری در مزرعه، باید provenance و fallback بودن بخش‌ها دیده شود.
• سطح اعتماد:
  • متوسط وقتی داده مزرعه کامل باشد و fallback محدود باشد.
  • کم تا متوسط وقتی بخش‌های زیادی fallback شده باشند.

POST /api/irrigation/water-stress/

• منبع داده:
  • ابتدا سرویس crop simulation
  • در صورت خطا fallback به فرمول ساده clamp(round(35 - (soil_moisture / 2)), 0, 100)
• ضعف‌ها:
  • اگر engine اصلی خطا بدهد هنوز به فرمول ساده سنسوری fallback می‌شود.
  • fallback فقط از soil_moisture استفاده می‌کند و ET0، بارش، root depth، نوع گیاه، مرحله رشد و روند زمانی را نادیده می‌گیرد.
  • بنابراین ظاهر endpoint ممکن است simulation-based باشد اما در failure عملا heuristic برگرداند.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • هر خروجی‌ای که sourceMetric.engine = sensor_fallback داشته باشد برای KPI دقیق تنش آبی قابل اتکا نیست.
• سطح اعتماد:
  • متوسط اگر واقعا از simulation engine آمده باشد.
  • کم اگر fallback سنسوری فعال شده باشد.

---

8) Fertilization API

POST /api/fertilization/recommend/

• منبع داده:
  • sensor/farm context
  • plant data
  • optimizer
  • RAG
• نقاط قوت فعلی:
  • مانند irrigation، provenance بخش‌ها اضافه شده و تشخیص fallback بهتر شده است.
• ضعف‌ها:
  • merge نهایی هنوز deterministic است و ساختار UI را حتی در خروجی ضعیف حفظ می‌کند.
  • وضعیت واقعی عناصر غذایی مزرعه به sample quality و coverage محدود است.
  • مدل crop-specific کامل و region-specific صریح دیده نمی‌شود.
  • پاسخ متنی نهایی LLM-based است.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • برای نسخه کود نهایی بدون آزمون خاک و تایید agronomist کافی نیست.
• سطح اعتماد:
  • متوسط برای پیشنهاد اولیه.
  • کم تا متوسط برای prescription نهایی.

---

9) Pest & Disease API

POST /api/pest-disease/detect/

• منبع داده:
  • تصویر ارسالی
  • context مزرعه
  • knowledge base
  • LLM vision / RAG
• ضعف‌ها:
  • دقت شدیدا به کیفیت، زاویه، نور و فاصله تصویر وابسته است.
  • خروجی deterministic نیست.
  • confidence هم از خود مدل می‌آید و لزوما calibrated نیست.
  • ممکن است علائم تغذیه‌ای، abiotic stress و بیماری با هم اشتباه شوند.
• سطح اعتماد:
  • کم تا متوسط برای triage اولیه.
  • کم برای تصمیم سم‌پاشی یا تشخیص قطعی.

POST /api/pest-disease/risk/

• منبع داده:
  • context مزرعه
  • weather
  • knowledge base
  • RAG
• ضعف‌ها:
  • هرچند intent آن RAG-based است، در لایه سرویس هنوز fallback heuristic نیز وجود دارد.
  • risk forecast region-specific و crop-specific calibrated model ندارد.
  • خروجی نهایی به retrieval quality و model behavior وابسته است.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • این endpoint باید فعلا به عنوان expert-assist دیده شود، نه predictive model قطعی.
• سطح اعتماد:
  • متوسط برای آگاهی از ریسک کلی.
  • کم برای عملیات خودکار یا قطعی.

POST /api/pest-disease/risk-summary/

• منبع داده: خلاصه سبک‌تر از همان سرویس RAG.
• نقاط قوت فعلی:
  • دیگر صرفا heuristic ثابت قبلی نیست و از RAG تغذیه می‌شود.
• ضعف‌ها:
  • چون summary است، جزئیات uncertainty کمتر دیده می‌شود.
  • اگر RAG fallback یا retrieval ضعیف داشته باشد، summary هم ضعیف می‌شود.
• سطح اعتماد:
  • متوسط رو به کم

---

10) Crop Simulation API

POST /api/crop-simulation/growth/

• منبع داده:
  • weather
  • soil
  • crop parameters
  • agromanagement
  • PCSE engine
• ضعف‌ها:
  • اگر پارامترهای واقعی مزرعه ناقص باشند، سیستم از defaultهای زیادی استفاده می‌کند.
  • بخشی از پارامترها مثل ELEV, IRRAD, RDMSOL, WAV, NAVAILI پیش‌فرض‌محور هستند.
  • کیفیت شبیه‌سازی به کیفیت profile گیاه و agromanagement وابسته است.
• نکته مهم:
  • در failure فعلی، خطا propagate می‌شود و دیگر fallback projection در مسیر اصلی برگردانده نمی‌شود؛ این از نظر شفافیت خوب است.
• سطح اعتماد:
  • متوسط وقتی ورودی‌ها خوب باشند و PCSE درست اجرا شود.
  • کم تا متوسط وقتی بخش زیادی از ورودی‌ها default باشند.

GET /api/crop-simulation/growth/{task_id}/status/

• منبع داده: status تسک + نتیجه شبیه‌سازی.
• ضعف‌ها:
  • وضعیت SUCCESS به معنی خوب بودن ورودی‌های مدل نیست.
  • page‌بندی timeline فقط presentation است و تضمین کیفیت علمی مدل نمی‌دهد.
• سطح اعتماد:
  • زیاد برای وضعیت فنی task.
  • متوسط برای محتوای simulation output.

POST /api/crop-simulation/current-farm-chart/

• منبع داده: simulation engine + context فعلی مزرعه.
• ضعف‌ها:
  • chart از شبیه‌سازی می‌آید، نه مشاهده واقعی برگ/بیوماس/weight.
  • leaf_count_estimate و برخی شاخص‌ها derived هستند، نه measured.
  • اگر weather forecast یا plant profile ضعیف باشد، chart گمراه‌کننده می‌شود.
• سطح اعتماد:
  • متوسط برای KPI بصری و trend.
  • کم تا متوسط برای تصمیم agronomy دقیق.

POST /api/crop-simulation/harvest-prediction/

• منبع داده:
  • growth simulation
  • GDD profile
  • extrapolation تا رسیدگی
• ضعف‌ها:
  • اگر maturity داخل بازه forecast رخ ندهد، تاریخ برداشت با extrapolation از میانگین رشد برآورد می‌شود.
  • بنابراین بخش‌هایی از تاریخ برداشت پیش‌بینی‌شده ممکن است فراتر از خروجی واقعی engine باشند.
  • وابستگی زیاد به required_gdd_for_maturity و current profile گیاه دارد.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • برای برنامه‌ریزی برداشت به عنوان estimate مناسب است، نه تعهد تقویمی قطعی.
• سطح اعتماد:
  • متوسط

POST /api/crop-simulation/yield-prediction/

• منبع داده: خروجی شبیه‌سازی رشد و تبدیل آن به yield KPI.
• ضعف‌ها:
  • عملکرد نهایی به کیفیت شبیه‌سازی upstream وابسته است.
  • اگر داده soil fertility، weather یا management واقعی نباشند، yield estimate فقط تقریبی است.
  • حمایت از uncertainty interval یا confidence band دیده نمی‌شود.
• سطح اعتماد:
  • متوسط رو به کم

---

11) Farm Alerts API

POST /api/farm-alerts/tracker/

• منبع داده:
  • rule-based tracker
  • thresholdهای hard-coded
  • خلاصه و notification با RAG/LLM
• ضعف‌ها:
  • alert tracker پایه، heuristic و threshold-driven است.
  • آستانه‌های moisture، pH، EC، fungal risk و ... hard-coded هستند.
  • region-specific و crop-specific calibration محدود است.
  • اگر LLM JSON بد برگرداند، fallback rule-based جای آن را می‌گیرد.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • برای هشدارآگاهی مناسب است، نه برای auto-actuation.
• سطح اعتماد:
  • متوسط برای شناسایی موارد مشکوک.
  • کم تا متوسط برای اقدام خودکار.

POST /api/farm-alerts/timeline/

• منبع داده: همان tracker + LLM timeline.
• ضعف‌ها:
  • timeline بیشتر narration است تا سنجش مستقل.
  • اگر مبنای alertها heuristic باشد، timeline فقط همان heuristic را بازبسته‌بندی می‌کند.
• سطح اعتماد:
  • کم تا متوسط

---

12) RAG API

POST /api/rag/chat/

• منبع داده:
  • farm context
  • history
  • images احتمالی
  • retrieval از knowledge base
  • LLM
• ضعف‌ها:
  • پاسخ stream می‌شود و structure قراردادی سختی ندارد.
  • hallucination، retrieval miss، و dependence به prompt/tone وجود دارد.
  • برای سوال‌های policy/diagnosis/operation ممکن است confident but wrong باشد.
• اگر فرمول/اطلاعات قابل اتکا نباشد:
  • این endpoint باید دستیار تحلیلی در نظر گرفته شود، نه source of truth.
• سطح اعتماد:
  • کم تا متوسط

POST /api/rag/recommend/irrigation/

• ماهیت:
  • عملا همان recommendation RAG-based آبیاری را مستقیما expose می‌کند.
• ضعف‌ها:
  • همان ضعف‌های POST /api/irrigation/recommend/ را دارد.
  • ظاهر کامل پاسخ می‌تواند fallback بودن بخش‌هایی از محتوا را پنهان کند، هرچند provenance اضافه شده است.
• سطح اعتماد:
  • متوسط با ورودی خوب
  • کم تا متوسط با fallback زیاد

POST /api/rag/recommend/fertilization/

• ماهیت:
  • مستقیم‌ترین مسیر recommendation کودهی مبتنی بر RAG است.
• ضعف‌ها:
  • همان ضعف‌های POST /api/fertilization/recommend/ را دارد.
• سطح اعتماد:
  • متوسط رو به کم

---

13) جمع‌بندی نهایی بر اساس کاربرد

APIهای مناسب برای استفاده عملی‌تر

• POST /api/farm-data/
• GET /api/farm-data/{farm_uuid}/detail/
• GET|POST /api/soil-data/
• POST /api/weather/farm-card/

این‌ها بیشتر data-centric هستند و اگر داده منبع خوب باشد، قابل اتکاترند.

APIهای مناسب برای dashboard و insight، نه تصمیم قطعی

• POST /api/soile/moisture-heatmap/
• POST /api/soile/health-summary/
• POST /api/weather/water-need-prediction/
• POST /api/crop-simulation/current-farm-chart/
• POST /api/crop-simulation/harvest-prediction/
• POST /api/crop-simulation/yield-prediction/
• POST /api/farm-alerts/tracker/
• POST /api/farm-alerts/timeline/

APIهای کم‌اعتماد یا نیازمند بازطراحی

• POST /api/economy/overview/
• POST /api/plants/fetch-info/
• POST /api/irrigation/water-stress/ در حالت fallback
• POST /api/pest-disease/detect/ برای diagnosis قطعی
• POST /api/pest-disease/risk/
• POST /api/pest-disease/risk-summary/
• POST /api/rag/chat/ برای پاسخ‌های حساس و اجرایی

---

14) پیشنهاد اولویت اصلاح

1. حذف fallback ساده از water-stress یا حداقل expose کردن صریح نوع engine در top-level response
2. جایگزینی mock در economy با data pipeline واقعی
3. پیاده‌سازی واقعی plants/fetch-info
4. افزودن uncertainty و freshness صریح به heatmap و water-need outputs
5. crop-specific و region-specific کردن alert/risk thresholds
6. اضافه کردن confidence واقعی و source provenance استاندارد به تمام endpointهای RAG-based