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