Ai/APPS_URLS_AUDIT.md

# گزارش کامل اپ‌ها، URLها و بررسی ضعف‌های پیاده‌سازی

## خلاصه اجرایی

این مخزن یک پروژه Django با چند اپ API مستقل است. از نظر مسیرها، ساختار کلی مناسب است، اما چند نقطه مهم در پیاده‌سازی دیده می‌شود:

- بعضی endpointها مستقیما `mock` یا `stub` هستند و خروجی واقعی تولید نمی‌کنند.
- بعضی endpointها در صورت خطای LLM یا نبود سرویس بیرونی، خروجی fallback می‌دهند که واقعی است ولی کاملا مدل‌محور/تقریبی است.
- چند ضعف ساختاری وجود دارد که می‌تواند باعث خروجی ناقص، 405 ناخواسته، یا داده ظاهرا واقعی اما غیرقابل اتکا شود.
- بخش Weather و Plant هنوز به سرویس بیرونی واقعی کامل وصل نشده‌اند.
- در چند بخش، محاسبات ساده‌سازی شده‌اند و برای KPI عملیاتی یا تصمیم‌گیری دقیق کشاورزی کافی نیستند.

---

## URLهای اصلی پروژه

### URLهای عمومی

| Method | URL | توضیح |
|---|---|---|
| GET | `/admin/` | پنل ادمین Django |
| GET | `/api/schema/` | OpenAPI schema |
| GET | `/api/docs/` | Swagger UI |
| GET | `/api/redoc/` | ReDoc |

### App: RAG

Base: `/api/rag/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/rag/chat/` | چت RAG به صورت stream |

### App: Farm Alerts

Base: `/api/farm-alerts/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/farm-alerts/tracker/` | تحلیل tracker هشدارها |
| POST | `/api/farm-alerts/timeline/` | ساخت timeline هشدارها |

### App: Location Data / Soil Data

Base: `/api/soil-data/`

| Method | URL | توضیح |
|---|---|---|
| GET | `/api/soil-data/` | واکشی داده خاک با `lat` و `lon` |
| POST | `/api/soil-data/` | واکشی داده خاک با body |
| GET | `/api/soil-data/tasks/<task_id>/status/` | وضعیت تسک خاک |
| POST | `/api/soil-data/ndvi-health/` | کارت NDVI مزرعه |

### App: Soile

Base: `/api/soile/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/soile/anomaly-detection/` | تحلیل ناهنجاری خاک |
| POST | `/api/soile/health-summary/` | خلاصه سلامت خاک |
| POST | `/api/soile/moisture-heatmap/` | heatmap رطوبت خاک |

### App: Farm Data

Base: `/api/farm-data/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/farm-data/` | ایجاد/آپدیت داده مزرعه |
| GET | `/api/farm-data/<farm_uuid>/detail/` | جزئیات تجمیعی مزرعه |
| POST | `/api/farm-data/parameters/` | ایجاد/ویرایش پارامتر سنسور |

### App: Weather

Base: `/api/weather/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/weather/farm-card/` | کارت وضعیت آب‌وهوا |
| POST | `/api/weather/water-need-prediction/` | پیش‌بینی نیاز آبی 7 روز آینده |

### App: Economy

Base: `/api/economy/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/economy/overview/` | نمای اقتصادی مزرعه |

### App: Plant

Base: `/api/plants/`

| Method | URL | توضیح |
|---|---|---|
| GET | `/api/plants/` | لیست گیاهان |
| POST | `/api/plants/` | ایجاد گیاه |
| GET | `/api/plants/<pk>/` | جزئیات گیاه |
| PUT | `/api/plants/<pk>/` | ویرایش کامل گیاه |
| PATCH | `/api/plants/<pk>/` | ویرایش جزئی گیاه |
| DELETE | `/api/plants/<pk>/` | حذف گیاه |
| POST | `/api/plants/fetch-info/` | دریافت اطلاعات گیاه از API بیرونی |

### App: Pest & Disease

Base: `/api/pest-disease/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/pest-disease/detect/` | تشخیص آفت/بیماری از تصویر |
| POST | `/api/pest-disease/risk/` | پیش‌بینی ریسک آفات و بیماری |
| POST | `/api/pest-disease/risk-summary/` | خلاصه KPI ریسک آفات و بیماری |

### App: Irrigation

Base: `/api/irrigation/`

| Method | URL | توضیح |
|---|---|---|
| GET | `/api/irrigation/` | لیست روش‌های آبیاری |
| POST | `/api/irrigation/` | ایجاد روش آبیاری |
| GET | `/api/irrigation/<pk>/` | جزئیات روش آبیاری |
| POST | `/api/irrigation/recommend/` | توصیه آبیاری |
| POST | `/api/irrigation/water-stress/` | شاخص تنش آبی |

> نکته: در کد متدهای `PUT/PATCH/DELETE` برای روش آبیاری نوشته شده‌اند، اما به کلاس اشتباه وصل شده‌اند و عملا روی route جزئیات اعمال نمی‌شوند.

### App: Fertilization

Base: `/api/fertilization/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/fertilization/recommend/` | توصیه کودهی |

### App: Crop Simulation

Base: `/api/crop-simulation/`

| Method | URL | توضیح |
|---|---|---|
| POST | `/api/crop-simulation/current-farm-chart/` | نمودار شبیه‌سازی وضعیت فعلی مزرعه |
| POST | `/api/crop-simulation/harvest-prediction/` | پیش‌بینی برداشت |
| POST | `/api/crop-simulation/yield-prediction/` | پیش‌بینی عملکرد |
| POST | `/api/crop-simulation/growth/` | شروع شبیه‌سازی رشد |
| GET | `/api/crop-simulation/growth/<task_id>/status/` | وضعیت شبیه‌سازی رشد |

---

## خروجی‌های Mock / Stub / Sample قطعی

### 1) Economy کاملا mock است
- سرویس `EconomicOverviewService` مستقیم `source: "mock"` برمی‌گرداند و همه داده‌ها ثابت هستند: `economy/services.py:7`
- خود description ویو هم صراحتا می‌گوید فعلا mock است: `economy/views.py:31`
- نتیجه: endpoint `POST /api/economy/overview/` فعلا برای استفاده واقعی قابل اتکا نیست.

### 2) Plant Fetch Info هنوز پیاده‌سازی نشده
- تابع اتصال بیرونی عملا `None` برمی‌گرداند: `plant/services.py:10`
- endpoint هم در این حالت `503` می‌دهد: `plant/views.py:292`
- نتیجه: `POST /api/plants/fetch-info/` فعلا هیچ داده واقعی از سرویس خارجی نمی‌گیرد.

### 3) Weather داده نمونه seeded دارد
- migration داده آب‌وهوای نمونه 7 روزه برای همه `SoilLocation`ها می‌سازد: `weather/migrations/0003_seed_weather_forecasts.py:1`
- نتیجه: در محیطی که migration اجرا شده باشد، بخشی از خروجی‌های Weather ممکن است از sample data بیایند نه API واقعی.

---

## خروجی‌هایی که mock مستقیم نیستند ولی fallback / تقریبی می‌دهند

### 1) Weather API از نظر مستندات و رفتار واقعی کد ناهماهنگ است
- داک‌استرینگ هنوز نوشته `TODO: پیاده‌سازی اتصال واقعی به API`: `weather/services.py:23`
- اما خود تابع در عمل `requests.get(...)` می‌زند و `response.json()` برمی‌گرداند: `weather/services.py:67`
- مسیر `no_data` در کد وجود دارد، ولی با پیاده‌سازی فعلی بیشتر یک branch دفاعی/قدیمی است تا رفتار اصلی: `weather/services.py:149`
- در `farm_data` اگر نتیجه weather برابر `no_data` باشد، خطا محسوب نمی‌شود و فرایند ادامه پیدا می‌کند: `farm_data/services.py:143`
- نتیجه: طراحی فعلی هنوز اجازه می‌دهد مزرعه بدون weather قابل اتکا ثبت/آپدیت شود، و این ابهام با وجود داده‌های seed شده شدیدتر می‌شود.

### 2) NDVI در نبود تنظیمات ماهواره‌ای خروجی unavailable می‌دهد
- اگر `SATELLITE_NDVI_ENDPOINT` و `SATELLITE_NDVI_API_KEY` تنظیم نشده باشد، client عملا داده نمی‌آورد: `location_data/remote_sensing.py:77`
- در این حالت کارت NDVI با `vegetation_health_class = "Unavailable"` و پیام نبود داده ماهواره‌ای برمی‌گردد: `location_data/ndvi.py:33`
- نتیجه: `POST /api/soil-data/ndvi-health/` ممکن است پاسخ موفق بدهد ولی داده واقعی NDVI نداشته باشد.

### 3) Farm Alerts در خطای LLM fallback می‌سازد
- اگر LLM خطا بدهد، خروجی خالی برمی‌گردد: `farm_alerts/services.py:353`
- سپس tracker و timeline از fallback داخلی ساخته می‌شوند: `farm_alerts/services.py:376`, `farm_alerts/services.py:413`
- نتیجه: خروجی این endpointها همیشه ممکن است LLM-native نباشد و از هشدارهای ساختاریافته داخلی ساخته شده باشد.

### 4) Soil Anomaly در خطای LLM fallback تحلیلی می‌دهد
- در exception خروجی fallback بازگردانده می‌شود: `rag/services/soil_anomaly.py:181`
- حتی اگر JSON مدل نامعتبر باشد، fallback جایگزین می‌شود: `rag/services/soil_anomaly.py:192`
- نتیجه: `POST /api/soile/anomaly-detection/` ممکن است تحلیل واقعی مدل زبانی نباشد.

### 5) Pest & Disease detect/risk در خطای LLM fallback دارند
- تشخیص تصویر در failure به fallback برمی‌گردد: `rag/services/pest_disease.py:321`
- ریسک آفات/بیماری هم در failure به fallback برمی‌گردد: `rag/services/pest_disease.py:388`
- نتیجه: پاسخ ممکن است ساختاری و معتبر باشد، اما برآمده از rule/fallback باشد نه inference کامل مدل.

### 6) Water Need Prediction insight در failure fallback می‌دهد
- در خطای LLM fallback summary برمی‌گردد: `rag/services/water_need_prediction.py:165`
- نتیجه: لایه insight توضیحی همیشه تضمین نمی‌کند که از مدل آمده باشد.

### 7) توصیه‌های آبیاری و کودهی merge با fallback می‌شوند
- پاسخ آبیاری با fallback merge می‌شود: `rag/services/irrigation.py:147`
- پاسخ کودهی هم با fallback merge می‌شود: `rag/services/fertilization.py:130`
- نتیجه: حتی وقتی LLM جواب می‌دهد، بخش‌هایی از خروجی ممکن است از template/fallback آمده باشد.

### 8) Crop Simulation در failure از projection fallback استفاده می‌کند
- اگر engine اصلی خطا بدهد، `_run_projection_engine` استفاده می‌شود: `crop_simulation/growth_simulation.py:404`
- نتیجه: بعضی نتایج crop simulation ممکن است تقریبی باشند نه خروجی engine اصلی.

---

## ضعف‌های مهم پیاده‌سازی

### 1) باگ واضح در route جزئیات Irrigation
- route جزئیات به `IrrigationMethodDetailView` وصل است: `irrigation/urls.py:12`
- اما متدهای `put/patch/delete` داخل `WaterStressView` تعریف شده‌اند، نه داخل `IrrigationMethodDetailView`: `irrigation/views.py:231`, `irrigation/views.py:287`, `irrigation/views.py:326`, `irrigation/views.py:360`
- علاوه بر این، `WaterStressView` اصلا `_get_method` ندارد و این کد از نظر ساختاری اشتباه است.
- اثر عملی: `PUT/PATCH/DELETE /api/irrigation/<pk>/` به احتمال زیاد `405 Method Not Allowed` می‌دهند و CRUD کامل عملا شکسته است.

### 2) محاسبه تنش آبی بیش از حد ساده‌سازی شده
- فرمول فقط از `soil_moisture` استفاده می‌کند: `irrigation/indicators.py:8`
- فرمول هم یک clamp ساده است: `clamp(round(35 - (soil_moisture / 2)), 0, 100)`: `irrigation/indicators.py:16`
- عوامل مهمی مثل ET0، نوع گیاه، مرحله رشد، ظرفیت مزرعه، بافت خاک، بارش، عمق ریشه و روند زمانی لحاظ نشده‌اند.
- اثر عملی: `POST /api/irrigation/water-stress/` برای KPI واقعی یا تصمیم آبیاری دقیق کافی نیست.

### 3) مرکز مزرعه با average ساده محاسبه می‌شود، نه centroid هندسی دقیق
- مرکز boundary با میانگین نقاط محاسبه می‌شود: `farm_data/services.py:100`
- برای polygonهای نامتقارن یا concave، این روش می‌تواند مرکز واقعی زمین را اشتباه بدهد.
- اثر عملی: داده خاک و هوا ممکن است برای نقطه‌ای غیرواقعی از مزرعه واکشی شوند.

### 4) ادغام داده چند سنسور باعث overwrite خاموش می‌شود
- در `farm_data`, متریک‌های همه sensorها flat می‌شوند و کلیدهای تکراری روی هم overwrite می‌شوند: `farm_data/services.py:155`
- هیچ تفکیک زمانی/مکانی/اولویت‌بندی بین سنسورها وجود ندارد.
- اثر عملی: در مزرعه چند سنسوره، `resolved_metrics` ممکن است فقط آخرین سنسور iterate شده را منعکس کند.

### 5) Weather card و Weather need کاملا وابسته به داده forecast موجود هستند
- اگر forecast نباشد، card خروجی صفر/نامشخص می‌دهد: `weather/farm_weather.py:42`
- build payload پیش‌بینی نیاز آبی هم در نبود forecast خروجی صفر می‌دهد: `weather/water_need_prediction.py:19`
- اثر عملی: endpoint ممکن است 200 بدهد اما محتوای عملیاتی نداشته باشد.

### 6) NDVI بدون boundary واقعی از bbox پیش‌فرض استفاده می‌کند
- اگر boundary وجود نداشته باشد، bbox کوچک پیش‌فرض تولید می‌شود: `location_data/remote_sensing.py:57`
- اثر عملی: NDVI ممکن است برای محدوده تقریبی اطراف center محاسبه شود، نه مرز واقعی مزرعه.

### 7) Heatmap رطوبت خاک مدل مکانی ساده دارد
- فقط latest measurement هر sensor استفاده می‌شود: `soile/services.py:22`, `soile/services.py:32`
- درون‌یابی از نوع IDW ساده است: `soile/services.py:46`
- history واقعی، drift سنسور، عدم قطعیت، zoning مزرعه یا depth-specific map در آن لحاظ نشده‌اند.
- اثر عملی: heatmap برای visualization خوب است ولی برای تصمیم agronomy دقیق کافی نیست.

### 8) Pest/Disease Risk Summary یک heuristic ساده است
- امتیاز بیماری و آفت از ترکیب چند فرمول ثابت ساخته می‌شود: `pest_disease/services.py:39`
- وزن‌ها hard-coded هستند و مدل crop-specific یا region-specific ندارند.
- اثر عملی: `POST /api/pest-disease/risk-summary/` بیشتر KPI تقریبی است تا مدل پیش‌بینی دقیق.

### 9) توصیه‌های RAG در لایه نهایی deterministic merge می‌شوند
- برای irrigation/fertilization، fallback همیشه ساختار نهایی را پر می‌کند: `rag/services/irrigation.py:153`, `rag/services/fertilization.py:135`
- اثر عملی: خروجی از نظر UI پایدار است، اما تشخیص اینکه کدام بخش واقعا از LLM آمده سخت می‌شود.

### 10) Crop Simulation ممکن است از engine اصلی به projection تقریبی سقوط کند
- fallback projection در خطا فعال می‌شود: `crop_simulation/growth_simulation.py:404`
- اگر consumer فقط status 200 ببیند و `simulation_warning` را ignore کند، ممکن است خروجی تقریبی را واقعی فرض کند.

---

## وضعیت هر اپ از نظر اتکا به داده واقعی

| App | وضعیت کلی | توضیح |
|---|---|---|
| `economy` | ضعیف | کاملا mock |
| `plant` | متوسط رو به ضعیف | CRUD واقعی است، ولی `fetch-info` پیاده‌سازی نشده |
| `weather` | متوسط | ساختار خوب است، ولی API بیرونی/seed sample هنوز ریسک دارد |
| `farm_data` | متوسط | هسته aggregation خوب است، ولی center/merge چند سنسور ساده‌سازی شده |
| `location_data` | متوسط | SoilGrids واقعی است، NDVI وابسته به تنظیمات بیرونی است |
| `soile` | متوسط | داده واقعی دارد، اما مدل تحلیلی و interpolation ساده است |
| `pest_disease` | متوسط | fallback زیاد و بخش risk-summary heuristic است |
| `farm_alerts` | متوسط | خروجی قابل استفاده است، ولی در failure به fallback داخلی می‌رود |
| `irrigation` | متوسط رو به ضعیف | recommendation خوب، اما water-stress ساده و CRUD detail معیوب |
| `fertilization` | متوسط | recommendation موجود است ولی heavily fallback-assisted |
| `rag` | متوسط | کارکرد خوب، اما بخشی از خروجی‌ها merge/fallback هستند |
| `crop_simulation` | متوسط | ساختار خوب، ولی fallback projection باید شفاف‌تر expose شود |

---

## endpointهایی که فعلا نباید به عنوان «داده قطعی واقعی» در نظر گرفته شوند

1. `POST /api/economy/overview/`
2. `POST /api/plants/fetch-info/`
3. `POST /api/weather/farm-card/` در محیطی که forecast نمونه/seed شده باشد
4. `POST /api/weather/water-need-prediction/` وقتی forecast واقعی موجود نیست
5. `POST /api/soil-data/ndvi-health/` وقتی satellite config ست نشده
6. `POST /api/farm-alerts/tracker/` و `POST /api/farm-alerts/timeline/` در failureهای LLM
7. `POST /api/soile/anomaly-detection/` در failureهای LLM
8. `POST /api/pest-disease/detect/` و `POST /api/pest-disease/risk/` در fallback mode
9. `POST /api/irrigation/water-stress/` برای تصمیم agronomy دقیق
10. endpointهای crop simulation وقتی `simulation_warning` نشان‌دهنده fallback engine باشد

---

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

### اولویت خیلی بالا
1. اصلاح باگ `PUT/PATCH/DELETE` در `irrigation/views.py`
2. حذف/mock-flag شفاف برای `economy`
3. تکمیل واقعی `plant/services.py`
4. شفاف‌سازی منبع forecast در weather (real / seeded / unavailable)

### اولویت بالا
1. جلوگیری از پذیرش silent `no_data` برای weather در بعضی flowهای حساس
2. اصلاح aggregation چند سنسور در `farm_data`
3. استفاده از centroid واقعی polygon به‌جای average ساده نقاط
4. اضافه‌کردن source flag به خروجی‌های fallback در RAG/Farm Alerts/Pest Disease/Soil Anomaly

### اولویت متوسط
1. بهبود مدل water stress
2. بهبود IDW/heatmap و استفاده از time-series
3. بهبود risk-summary آفت/بیماری با crop profile و weather window دقیق‌تر
4. اضافه‌کردن flag صریح برای crop-simulation fallback

---

## فایل‌های کلیدی که این گزارش بر اساس آن‌ها ساخته شده

- `config/urls.py`
- `rag/urls.py`
- `farm_alerts/urls.py`
- `location_data/urls.py`
- `soile/urls.py`
- `farm_data/urls.py`
- `weather/urls.py`
- `economy/urls.py`
- `plant/urls.py`
- `pest_disease/urls.py`
- `irrigation/urls.py`
- `fertilization/urls.py`
- `crop_simulation/urls.py`
- `economy/services.py:7`
- `plant/services.py:10`
- `weather/services.py:19`
- `weather/migrations/0003_seed_weather_forecasts.py:1`
- `farm_data/services.py:123`
- `location_data/remote_sensing.py:75`
- `location_data/ndvi.py:21`
- `soile/services.py:98`
- `pest_disease/services.py:25`
- `irrigation/views.py:196`
- `irrigation/indicators.py:8`
- `rag/services/soil_anomaly.py:137`
- `rag/services/pest_disease.py:350`
- `rag/services/water_need_prediction.py:129`
- `rag/services/irrigation.py:147`
- `rag/services/fertilization.py:130`
- `crop_simulation/growth_simulation.py:404`