# مستند کامل APIهای CropLogic AI

این فایل مرجع اجرایی APIهای پروژه است و بر اساس کد فعلی `config/urls.py`، `views.py` و `serializers.py` تهیه شده است.

## نکات کلی

- پیشوند تمام APIها: `/api/`
- اکثر endpointها خروجی را در envelope زیر برمی‌گردانند:

```json
{
  "code": 200,
  "msg": "success",
  "data": {}
}
```

- بعضی endpointهای AI علاوه بر داده نهایی، این فیلدها را هم برمی‌گردانند:
  - `raw_response`: متن خام خروجی مدل
  - `knowledge_base`: نام knowledge base مرتبط
- در چند endpoint قدیمی، به‌جای `farm_uuid` می‌توان `sensor_uuid` فرستاد؛ در صورت وجود، backend آن را به `farm_uuid` تبدیل می‌کند.
- فیلدهایی که در این داکیومنت با برچسب `الزامی` آمده‌اند، باید حتما ارسال شوند.

---

## 1) RAG

### 1.1) چت RAG

- مسیر: `POST /api/rag/chat/`
- نوع خروجی: `application/json`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `query` — `string` — اختیاری، ولی اگر تصویر نفرستید عملا الزامی است
- `message` — `string` — نام قدیمی `query`
- `history` — `array | string(JSON)` — اختیاری
- `image_urls` — `array` — اختیاری
- `image` — `file` — اختیاری
- `images` — `file[]` — اختیاری

#### قواعد الزامی

- اگر `query/message` خالی باشد و هیچ تصویری ارسال نشده باشد، درخواست `400` می‌گیرد
- `farm_uuid` نباید خالی باشد
- `history` باید آرایه باشد یا رشته JSON معتبرِ آرایه

#### خروجی موفق

- خروجی این endpoint به‌صورت JSON ساختاریافته برمی‌گردد
- پاسخ موفق داخل `data` شامل آرایه `sections` است

#### شکل خروجی

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "sections": [
      {
        "type": "recommendation",
        "title": "جمع بندي اصلي",
        "icon": "message-circle",
        "content": "خلاصه يک جمله اي از بهترين پاسخ يا اقدام اصلي",
        "primaryAction": "اقدام اصلي پيشنهادي",
        "timing": "بهترين زمان اجرا يا بررسي",
        "validityPeriod": "مدت اعتبار اين پاسخ يا توصيه",
        "expandableExplanation": "توضيح روشن درباره دليل پاسخ با ارجاع به داده مزرعه، آب و هوا، گياه و شبيه سازي"
      },
      {
        "type": "list",
        "title": "نکات اجرايي",
        "icon": "list",
        "items": [
          "نکته عملي 1",
          "نکته عملي 2"
        ]
      },
      {
        "type": "warning",
        "title": "هشدار يا محدوديت",
        "icon": "alert-triangle",
        "content": "هشدار کوتاه و کاربردي"
      }
    ]
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر، `farm_uuid` خالی، `history` نامعتبر، `query` خالی
- `404`: `farm` پیدا نشد

---

## 2) Farm Alerts

### 2.1) Tracker هشدارهای مزرعه

- مسیر: `POST /api/farm-alerts/tracker/`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `sensor_uuid` — `string` — اختیاری، alias
- `query` — `string` — اختیاری

#### خروجی موفق

خروجی این endpoint برای نمایش وضعیت هشدارهای مزرعه به این شکل است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "headline": "string",
    "overview": "string",
    "status_level": "info | warning | danger",
    "notifications": []
  }
}
```

`notifications` معمولا رکوردهای ذخیره‌شده هشدار یا هشدارهای نرمال‌شده را برمی‌گرداند.

#### خطاها

- `400`: نبودن `farm_uuid`
- `500`: خطا در تولید tracker

---

### 2.2) Timeline هشدارهای مزرعه

- مسیر: `POST /api/farm-alerts/timeline/`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `sensor_uuid` — `string` — اختیاری، alias
- `query` — `string` — اختیاری

#### خروجی موفق

خروجی این endpoint برای نمایش timeline هشدارها به این شکل است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "headline": "string",
    "overview": "string",
    "timeline": [],
    "notifications": []
  }
}
```

#### خطاها

- `400`: نبودن `farm_uuid`
- `500`: خطا در تولید timeline

---

## 3) Soil Data

### 3.1) دریافت داده خاک با GET

- مسیر: `GET /api/soil-data/?lat=...&lon=...`

#### ورودی

- `lat` — `decimal(9,6)` — الزامی
- `lon` — `decimal(9,6)` — الزامی

#### خروجی موفق از دیتابیس

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "source": "database",
    "id": 1,
    "lon": 51.400000,
    "lat": 35.700000,
    "depths": [
      {
        "depth_label": "0-5cm",
        "bdod": null,
        "cec": null,
        "cfvo": null,
        "clay": 22.0,
        "nitrogen": 14.0,
        "ocd": null,
        "ocs": null,
        "phh2o": 6.6,
        "sand": 40.0,
        "silt": 25.0,
        "soc": null,
        "wv0010": 0.41,
        "wv0033": 0.28,
        "wv1500": 0.12
      }
    ]
  }
}
```

#### خروجی وقتی داده هنوز آماده نیست

```json
{
  "code": 202,
  "msg": "تسک در صف. وضعیت را با task_id بررسی کنید.",
  "data": {
    "source": "task",
    "task_id": "string",
    "lon": 51.4,
    "lat": 35.7,
    "status_url": "/api/soil-data/tasks/<task_id>/status/"
  }
}
```

#### خطاها

- `400`: نبودن `lat/lon` یا نامعتبر بودن آن‌ها

---

### 3.2) دریافت داده خاک با POST

- مسیر: `POST /api/soil-data/`

#### ورودی

- `lat` — `decimal(9,6)` — الزامی
- `lon` — `decimal(9,6)` — الزامی

#### خروجی

- دقیقا مشابه endpoint قبلی

---

### 3.3) وضعیت تسک داده خاک

- مسیر: `GET /api/soil-data/tasks/<task_id>/status/`

#### ورودی

- `task_id` از path — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "string",
    "status": "PENDING | PROGRESS | SUCCESS | FAILURE",
    "message": "...",
    "progress": {},
    "result": {},
    "error": "..."
  }
}
```

---

### 3.4) NDVI سلامت مزرعه

- مسیر: `POST /api/soil-data/ndvi-health/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "ndviIndex": 0.73,
    "mean_ndvi": 0.73,
    "ndvi_map": {},
    "vegetation_health_class": "Healthy",
    "observation_date": "2026-04-10",
    "satellite_source": "sentinel-2",
    "healthData": [
      {
        "title": "string",
        "value": {},
        "color": "string",
        "icon": "string"
      }
    ]
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر
- `404`: مزرعه پیدا نشد

---

## 4) Soile

### 4.1) Heatmap رطوبت خاک

- مسیر: `POST /api/soile/moisture-heatmap/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string",
    "location": {},
    "current_sensor": {},
    "soil_profile": [],
    "timestamp": "string | null",
    "grid_resolution": {},
    "grid_cells": [],
    "sensor_points": [],
    "quality_legend": {}
  }
}
```

خروجی واقعی معمولا علاوه بر موارد بالا شامل `depth_layers`, `model_metadata`, `summary` هم هست.

#### خطاها

- `400`: ورودی نامعتبر
- `404`: مزرعه پیدا نشد

---

### 4.2) خلاصه سلامت خاک

- مسیر: `POST /api/soile/health-summary/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string",
    "healthScore": 82,
    "profileSource": "Tomato",
    "healthScoreDetails": {},
    "healthLanguage": {},
    "avgSoilMoisture": 46,
    "avgSoilMoistureRaw": 46.0,
    "avgSoilMoistureStatus": "بهینه"
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر
- `404`: مزرعه پیدا نشد

---

### 4.3) تحلیل ناهنجاری خاک

- مسیر: `POST /api/soile/anomaly-detection/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی

#### خروجی موفق

خروجی این endpoint شامل تحلیل ناهنجاری خاک به همراه metadata تکمیلی است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string",
    "summary": "جمع بندی کوتاه ناهنجاری",
    "explanation": "توضیح کوتاه",
    "likely_cause": "علت محتمل",
    "recommended_action": "اقدام عملی",
    "monitoring_priority": "low | medium | high | urgent",
    "confidence": 0.0,
    "generated_at": "string",
    "anomalies": [],
    "interpretation": {},
    "knowledge_base": "string | null",
    "raw_response": "string | null"
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر
- `404`: مزرعه پیدا نشد
- `500`: خطا در تحلیل

---

## 5) Farm Data

### 5.1) ایجاد/آپدیت farm data

- مسیر: `POST /api/farm-data/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی
- `farm_boundary` — `object` — الزامی
- `sensor_key` — `string` — اختیاری، پیش‌فرض: `sensor-7-1`
- `sensor_payload` — `object` — اختیاری
- `plant_ids` — `integer[]` — اختیاری
- `irrigation_method_id` — `integer | null` — اختیاری

#### نکته مهم

- حداقل یکی از این سه فیلد باید ارسال شود:
  - `sensor_payload`
  - `plant_ids`
  - `irrigation_method_id`

#### ساختار `farm_boundary`

دو فرم اصلی در کد پشتیبانی می‌شود:

1. GeoJSON Polygon

```json
{
  "type": "Polygon",
  "coordinates": [
    [
      [51.39, 35.70],
      [51.41, 35.70],
      [51.41, 35.72],
      [51.39, 35.72],
      [51.39, 35.70]
    ]
  ]
}
```

2. corners

```json
{
  "corners": [
    {"lat": 35.70, "lon": 51.39},
    {"lat": 35.70, "lon": 51.41},
    {"lat": 35.72, "lon": 51.41},
    {"lat": 35.72, "lon": 51.39}
  ]
}
```

#### ساختار `sensor_payload`

```json
{
  "sensor-7-1": {
    "soil_moisture": 45.2,
    "soil_temperature": 22.5,
    "soil_ph": 6.8,
    "electrical_conductivity": 1.2,
    "nitrogen": 30.0,
    "phosphorus": 15.0,
    "potassium": 20.0
  },
  "leaf-sensor": {
    "leaf_wetness": 11.0
  }
}
```

#### خروجی موفق

بخش `insight` این endpoint خلاصه تحلیلی و عملیاتی نیاز آبی را برمی‌گرداند:

```json
{
  "code": 201,
  "msg": "success",
  "data": {
    "farm_uuid": "uuid",
    "center_location_id": 1,
    "weather_forecast_id": 10,
    "sensor_payload": {},
    "plant_ids": [1, 2],
    "irrigation_method_id": 3,
    "created_at": "datetime",
    "updated_at": "datetime"
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر، boundary نامعتبر، `sensor_payload` نامعتبر
- `502`: خطا در sync داده‌های بیرونی خاک/آب‌وهوا

---

### 5.2) جزئیات کامل farm

- مسیر: `GET /api/farm-data/<farm_uuid>/detail/`

#### ورودی

- `farm_uuid` در path — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "center_location": {
      "id": 1,
      "lat": 35.700000,
      "lon": 51.400000,
      "farm_boundary": {}
    },
    "weather": {
      "id": 10,
      "forecast_date": "2026-04-10",
      "temperature_min": 12.0,
      "temperature_max": 23.0,
      "temperature_mean": 18.0,
      "precipitation": 1.2,
      "precipitation_probability": 35.0,
      "humidity_mean": 52.0,
      "wind_speed_max": 11.0,
      "et0": 3.4,
      "weather_code": 0
    },
    "sensor_payload": {},
    "soil": {
      "resolved_metrics": {},
      "metric_sources": {},
      "depths": []
    },
    "plant_ids": [1, 2],
    "plants": [],
    "irrigation_method_id": 3,
    "irrigation_method": {},
    "created_at": "datetime",
    "updated_at": "datetime"
  }
}
```

#### خطاها

- `404`: farm یافت نشد

---

### 5.3) تعریف/ویرایش پارامتر سنسور

- مسیر: `POST /api/farm-data/parameters/`

#### ورودی

- `sensor_key` — `string` — اختیاری، پیش‌فرض `sensor-7-1`
- `code` — `string` — الزامی
- `name_fa` — `string` — الزامی
- `unit` — `string` — اختیاری
- `data_type` — `string` — اختیاری، پیش‌فرض `float`
- `metadata` — `object` — اختیاری

#### خروجی موفق

```json
{
  "code": 201,
  "msg": "success",
  "data": {
    "id": 1,
    "sensor_key": "sensor-7-1",
    "code": "soil_moisture",
    "name_fa": "رطوبت خاک",
    "unit": "%",
    "data_type": "float",
    "metadata": {},
    "created_at": "datetime",
    "action": "added | modified"
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر

---

## 6) Weather

### 6.1) کارت آب‌وهوای مزرعه

- مسیر: `POST /api/weather/farm-card/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "condition": "صاف",
    "temperature": 28.0,
    "unit": "°C",
    "humidity": 42.0,
    "windSpeed": 15.0,
    "windUnit": "km/h",
    "chartData": {
      "labels": ["2026-04-01", "2026-04-02"],
      "series": [[28.0, 29.0]]
    }
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر
- `404`: مزرعه یافت نشد

---

### 6.2) پیش‌بینی نیاز آبی

- مسیر: `POST /api/weather/water-need-prediction/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string",
    "totalNext7Days": 24.6,
    "unit": "mm",
    "categories": ["روز 1", "روز 2"],
    "series": [],
    "dailyBreakdown": [],
    "insight": {
      "summary": "جمع بندی نیاز آبی بازه کوتاه مدت",
      "irrigation_outlook": "برداشت عملیاتی از روند آبیاری روزهای آینده",
      "recommended_action": "اقدام عملی پیشنهادی برای آبیاری",
      "risk_note": "ریسک یا عدم قطعیت مهم",
      "confidence": 0.0
    },
    "knowledge_base": "water_need_prediction",
    "raw_response": "..."
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر
- `404`: مزرعه یافت نشد
- `500`: خطا در تحلیل

---

## 7) Economy

### 7.1) نمای اقتصادی مزرعه

- مسیر: `POST /api/economy/overview/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string",
    "source": "mock",
    "economicData": [
      {
        "title": "string",
        "value": "string",
        "subtitle": "string",
        "avatarIcon": "string",
        "avatarColor": "string"
      }
    ],
    "chartSeries": [
      {
        "name": "string",
        "data": [1.0, 2.0]
      }
    ],
    "chartCategories": ["فروردین", "اردیبهشت"]
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر

---

## 8) Plants

### 8.1) لیست گیاهان

- مسیر: `GET /api/plants/`

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "گوجه‌فرنگی",
      "light": "آفتاب کامل",
      "watering": "منظم",
      "soil": "لومی",
      "temperature": "20-30",
      "growth_stage": "رویشی",
      "planting_season": "بهار",
      "harvest_time": "70-90 روز",
      "spacing": "45-60 سانتی‌متر",
      "fertilizer": "NPK",
      "created_at": "datetime",
      "updated_at": "datetime"
    }
  ]
}
```

---

### 8.2) ایجاد گیاه

- مسیر: `POST /api/plants/`

#### ورودی

- `name` — `string` — الزامی
- `light` — `string` — اختیاری
- `watering` — `string` — اختیاری
- `soil` — `string` — اختیاری
- `temperature` — `string` — اختیاری
- `growth_stage` — `string` — اختیاری
- `planting_season` — `string` — اختیاری
- `harvest_time` — `string` — اختیاری
- `spacing` — `string` — اختیاری
- `fertilizer` — `string` — اختیاری

#### خروجی موفق

- همان ساختار `PlantSerializer`
- status: `201`

#### خطاها

- `400`: ورودی نامعتبر

---

### 8.3) جزئیات گیاه

- مسیر: `GET /api/plants/<pk>/`

#### خروجی موفق

- همان `PlantSerializer`

#### خطاها

- `404`: گیاه یافت نشد

---

### 8.4) ویرایش کامل گیاه

- مسیر: `PUT /api/plants/<pk>/`

#### ورودی

- تمام فیلدهای `PlantSerializer`
- عملا `name` باید وجود داشته باشد

#### خروجی موفق

- همان `PlantSerializer`

#### خطاها

- `400`: ورودی نامعتبر
- `404`: گیاه یافت نشد

---

### 8.5) ویرایش جزئی گیاه

- مسیر: `PATCH /api/plants/<pk>/`

#### ورودی

- هر زیرمجموعه‌ای از فیلدهای `PlantSerializer`

#### خروجی موفق

- همان `PlantSerializer`

#### خطاها

- `400`, `404`

---

### 8.6) حذف گیاه

- مسیر: `DELETE /api/plants/<pk>/`

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "گیاه با موفقیت حذف شد.",
  "data": null
}
```

#### خطاها

- `404`: گیاه یافت نشد

---

### 8.7) دریافت اطلاعات گیاه از API خارجی

- مسیر: `POST /api/plants/fetch-info/`

#### ورودی

- `name` — `string` — الزامی

#### خروجی موفق

- object شامل اطلاعات گیاه
- ساختار مورد انتظار مشابه `PlantSerializer` است

#### خطاها

- `400`: نام گیاه ارسال نشده
- `503`: سرویس خارجی در دسترس نیست یا پیاده‌سازی نشده

---

## 9) Pest & Disease

### 9.1) تشخیص آفت/بیماری از روی تصویر

- مسیر: `POST /api/pest-disease/detect/`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `sensor_uuid` — `string` — اختیاری
- `plant_name` — `string` — اختیاری
- `query` — `string` — اختیاری
- `image_urls` — `array` — اختیاری
- `image` — `file` — اختیاری
- `images` — `file[]` — اختیاری

#### قاعده مهم

- حداقل یک تصویر باید به یکی از این روش‌ها ارسال شود: `image_urls` یا `image` یا `images`

#### خروجی موفق

خروجی این endpoint برای تشخیص آفت/بیماری از روی تصویر به این شکل است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "has_issue": true,
    "category": "pest | disease | nutrient_stress | abiotic_stress | no_issue | unknown",
    "confidence": 0.0,
    "severity": "low | medium | high",
    "summary": "جمع بندی کوتاه تشخیص",
    "detected_signs": [],
    "possible_causes": [],
    "immediate_actions": [],
    "reasoning": []
  }
}
```

#### خطاها

- `400`: نبودن `farm_uuid` یا نبودن تصویر
- `500`: خطا در تحلیل تصویر

---

### 9.2) پیش‌بینی ریسک آفات و بیماری

- مسیر: `POST /api/pest-disease/risk/`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `sensor_uuid` — `string` — اختیاری
- `plant_name` — `string` — اختیاری
- `growth_stage` — `string` — اختیاری
- `query` — `string` — اختیاری

#### خروجی موفق

خروجی این endpoint برای پیش بینی ریسک آفات و بیماری به این شکل است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "summary": "جمع بندی کوتاه ریسک",
    "forecast_window": "بازه زمانی",
    "overall_risk": "low | medium | high",
    "disease_risk": {
      "score": 0.0,
      "level": "low | medium | high",
      "likely_conditions": [],
      "reasoning": []
    },
    "pest_risk": {
      "score": 0.0,
      "level": "low | medium | high",
      "likely_conditions": [],
      "reasoning": []
    },
    "key_drivers": [],
    "recommended_actions": []
  }
}
```

#### خطاها

- `400`: نبودن `farm_uuid`
- `500`: خطا در پیش‌بینی

---

## 10) Irrigation

### 10.1) لیست روش‌های آبیاری

- مسیر: `GET /api/irrigation/`

#### خروجی موفق

- آرایه‌ای از `IrrigationMethodSerializer`

#### فیلدهای هر آیتم

- `id`
- `name`
- `category`
- `description`
- `water_efficiency_percent`
- `water_pressure_required`
- `flow_rate`
- `coverage_area`
- `soil_type`
- `climate_suitability`
- `created_at`
- `updated_at`

---

### 10.2) ایجاد روش آبیاری

- مسیر: `POST /api/irrigation/`

#### ورودی

- `name` — `string` — الزامی
- `category` — `string` — اختیاری
- `description` — `string` — اختیاری
- `water_efficiency_percent` — `float | null` — اختیاری
- `water_pressure_required` — `string` — اختیاری
- `flow_rate` — `string` — اختیاری
- `coverage_area` — `string` — اختیاری
- `soil_type` — `string` — اختیاری
- `climate_suitability` — `string` — اختیاری

#### خروجی موفق

- همان `IrrigationMethodSerializer`

#### خطاها

- `400`: ورودی نامعتبر

---

### 10.3) جزئیات روش آبیاری

- مسیر: `GET /api/irrigation/<pk>/`

#### خروجی موفق

- همان `IrrigationMethodSerializer`

#### خطاها

- `404`: یافت نشد

---

### 10.4) ویرایش کامل روش آبیاری

- مسیر: `PUT /api/irrigation/<pk>/`

#### ورودی

- تمام فیلدهای `IrrigationMethodSerializer`

#### خروجی موفق

- همان `IrrigationMethodSerializer`

#### خطاها

- `400`, `404`

---

### 10.5) ویرایش جزئی روش آبیاری

- مسیر: `PATCH /api/irrigation/<pk>/`

#### ورودی

- هر زیرمجموعه‌ای از فیلدهای `IrrigationMethodSerializer`

#### خروجی موفق

- همان `IrrigationMethodSerializer`

#### خطاها

- `400`, `404`

---

### 10.6) حذف روش آبیاری

- مسیر: `DELETE /api/irrigation/<pk>/`

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "روش آبیاری با موفقیت حذف شد.",
  "data": null
}
```

#### خطاها

- `404`: یافت نشد

---

### 10.7) توصیه آبیاری

- مسیر: `POST /api/irrigation/recommend/`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `sensor_uuid` — `string` — اختیاری
- `plant_name` — `string` — اختیاری
- `growth_stage` — `string` — اختیاری
- `irrigation_method_name` — `string` — اختیاری
- `query` — `string` — اختیاری

#### خروجی موفق

این endpoint فقط آبجکت نهایی و قابل استفاده برای کشاورز را برمی‌گرداند و فیلدهای داخلی مثل `simulation_optimizer`، `water_balance`، `mergeMetadata`، `selected_irrigation_method` و `raw_response` در پاسخ public نمایش داده نمی‌شوند. خروجی نهایی به این شکل است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "sections": [
      {
        "type": "recommendation",
        "title": "برنامه آبیاری بهینه",
        "icon": "droplet",
        "content": "خلاصه یک جمله ای از بهترین سناریوی شبیه سازی",
        "frequency": "تعداد نوبت آبیاری در بازه اعتبار",
        "amount": "مقدار آب در هر نوبت و جمع کل",
        "timing": "بهترین زمان اجرا",
        "validityPeriod": "مدت اعتبار دقیق توصیه",
        "expandableExplanation": "توضیح دلیل انتخاب این سناریو با ارجاع به تنش آبی، دما، بارش و شبیه سازی"
      },
      {
        "type": "list",
        "title": "اقدامات اجرایی",
        "icon": "list",
        "items": ["نکته عملی 1", "نکته عملی 2"]
      },
      {
        "type": "warning",
        "title": "هشدار آبیاری",
        "icon": "alert-triangle",
        "content": "هشدار کوتاه و کاربردی"
      }
    ]
  }
}
```

#### خطاها

- `400`: نبودن `farm_uuid`
- `500`: خطا در تولید توصیه

---

### 10.8) شاخص تنش آبی

- مسیر: `POST /api/irrigation/water-stress/`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `sensor_uuid` — `string` — اختیاری

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string",
    "waterStressIndex": 12,
    "level": "پایین",
    "sourceMetric": {}
  }
}
```

#### خطاها

- `400`: نبودن `farm_uuid`
- `404`: مزرعه پیدا نشد

---

## 11) Fertilization

### 11.1) توصیه کودهی

- مسیر: `POST /api/fertilization/recommend/`

#### ورودی

- `farm_uuid` — `string` — الزامی
- `sensor_uuid` — `string` — اختیاری
- `plant_name` — `string` — اختیاری
- `growth_stage` — `string` — اختیاری
- `query` — `string` — اختیاری

#### خروجی موفق

این endpoint فقط خروجی نهایی بهینه شده و آماده استفاده را برمی‌گرداند و جزئیات داخلی مثل `simulation_optimizer`، `mergeMetadata` و `raw_response` را در پاسخ public برنمی‌گرداند. خروجی نهایی به این شکل است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "sections": [
      {
        "type": "recommendation",
        "title": "برنامه کودهی بهینه",
        "icon": "leaf",
        "content": "خلاصه یک جمله ای از سناریوی منتخب",
        "fertilizerType": "نوع کود پیشنهادی",
        "amount": "مقدار مصرف دقیق",
        "applicationMethod": "روش مصرف",
        "timing": "بهترین زمان اجرا",
        "validityPeriod": "مدت اعتبار این توصیه",
        "expandableExplanation": "دلیل انتخاب این سناریو بر اساس کمبود عناصر، pH، مرحله رشد و شبیه سازی"
      },
      {
        "type": "list",
        "title": "نکات اجرایی و اختلاط",
        "icon": "list",
        "items": ["نکته عملی 1", "نکته عملی 2"]
      },
      {
        "type": "warning",
        "title": "هشدار کودهی",
        "icon": "alert-triangle",
        "content": "هشدار کوتاه و کاربردی"
      }
    ]
  }
}
```

#### خطاها

- `400`: نبودن `farm_uuid`
- `500`: خطا در تولید توصیه

---

## 12) Crop Simulation

### 12.1) شروع شبیه‌سازی رشد

- مسیر: `POST /api/crop-simulation/growth/`

#### ورودی

- `plant_name` — `string` — الزامی
- `dynamic_parameters` — `string[]` — الزامی و نباید خالی باشد
- `farm_uuid` — `uuid | null` — اختیاری
- `weather` — `object | array` — اختیاری
- `soil_parameters` — `object` — اختیاری
- `site_parameters` — `object` — اختیاری
- `crop_parameters` — `object` — اختیاری
- `agromanagement` — `object` — اختیاری
- `page_size` — `integer` — اختیاری، بین 1 تا 50

#### قاعده مهم

- حداقل یکی از `farm_uuid` یا `weather` باید ارسال شود

#### خروجی موفق

```json
{
  "code": 202,
  "msg": "تسک شبیه سازی رشد در صف قرار گرفت.",
  "data": {
    "task_id": "string",
    "status_url": "/api/crop-simulation/growth/<task_id>/status/",
    "plant_name": "گوجه‌فرنگی"
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر

---

### 12.2) وضعیت شبیه‌سازی رشد

- مسیر: `GET /api/crop-simulation/growth/<task_id>/status/`

#### query params

- `page` — `integer` — اختیاری
- `page_size` — `integer` — اختیاری

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "string",
    "status": "PENDING | PROGRESS | SUCCESS | FAILURE",
    "message": "string",
    "progress": {},
    "result": {
      "plant_name": "string",
      "dynamic_parameters": ["DVS", "LAI"],
      "engine": "string | null",
      "model_name": "string | null",
      "scenario_id": 1,
      "simulation_warning": "",
      "summary_metrics": {},
      "stage_timeline": [],
      "stages_page": [],
      "pagination": {
        "page": 1,
        "page_size": 10,
        "total_items": 2,
        "total_pages": 1,
        "has_next": false,
        "has_previous": false
      },
      "daily_records_count": 51,
      "default_page_size": 10
    },
    "error": "string"
  }
}
```

---

### 12.3) chart وضعیت فعلی مزرعه

- مسیر: `POST /api/crop-simulation/current-farm-chart/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی
- `plant_name` — `string` — اختیاری

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string | null",
    "plant_name": "string",
    "engine": "string | null",
    "model_name": "string | null",
    "scenario_id": 1,
    "simulation_warning": "",
    "categories": [],
    "series": {},
    "summary": {},
    "current_state": {},
    "metrics": {},
    "daily_output": {}
  }
}
```

#### خطاها

- `400`: ورودی نامعتبر
- `500`: خطا در اجرای chart

---

### 12.4) پیش‌بینی برداشت

- مسیر: `POST /api/crop-simulation/harvest-prediction/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی
- `plant_name` — `string` — اختیاری

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "date": "2026-07-15",
    "dateFormatted": "15 Jul 2026",
    "daysUntil": 96,
    "description": "string",
    "optimalWindowStart": "2026-07-10",
    "optimalWindowEnd": "2026-07-20",
    "gddDetails": {}
  }
}
```

#### خطاها

- `400`, `500`

---

### 12.5) پیش‌بینی عملکرد

- مسیر: `POST /api/crop-simulation/yield-prediction/`

#### ورودی

- `farm_uuid` — `uuid` — الزامی
- `plant_name` — `string` — اختیاری

#### خروجی موفق

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "string",
    "plant_name": "string | null",
    "predictedYieldTons": 8.4,
    "predictedYieldRaw": 8400.0,
    "unit": "t/ha",
    "sourceUnit": "kg/ha",
    "simulationEngine": "string | null",
    "simulationModel": "string | null",
    "scenarioId": 1,
    "simulationWarning": "",
    "supportingMetrics": {}
  }
}
```

#### خطاها

- `400`, `500`

---

## 13) وضعیت کدهای HTTP

- `200` — موفق
- `201` — ایجاد/آپدیت موفق
- `202` — تسک async در صف قرار گرفت
- `400` — ورودی نامعتبر یا فیلد الزامی ارسال نشده
- `404` — رکورد/مزرعه/گیاه پیدا نشد
- `500` — خطای داخلی در پردازش تحلیلی
- `502` — خطا در sync داده بیرونی
- `503` — سرویس خارجی در دسترس نیست

---

## 14) endpointهای نهایی به‌صورت خلاصه

- `POST /api/rag/chat/`
- `POST /api/farm-alerts/tracker/`
- `POST /api/farm-alerts/timeline/`
- `GET /api/soil-data/`
- `POST /api/soil-data/`
- `GET /api/soil-data/tasks/<task_id>/status/`
- `POST /api/soil-data/ndvi-health/`
- `POST /api/soile/moisture-heatmap/`
- `POST /api/soile/health-summary/`
- `POST /api/soile/anomaly-detection/`
- `POST /api/farm-data/`
- `GET /api/farm-data/<farm_uuid>/detail/`
- `POST /api/farm-data/parameters/`
- `POST /api/weather/farm-card/`
- `POST /api/weather/water-need-prediction/`
- `POST /api/economy/overview/`
- `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/`
- `POST /api/pest-disease/detect/`
- `POST /api/pest-disease/risk/`
- `GET /api/irrigation/`
- `POST /api/irrigation/`
- `GET /api/irrigation/<pk>/`
- `PUT /api/irrigation/<pk>/`
- `PATCH /api/irrigation/<pk>/`
- `DELETE /api/irrigation/<pk>/`
- `POST /api/irrigation/recommend/`
- `POST /api/irrigation/water-stress/`
- `POST /api/fertilization/recommend/`
- `POST /api/crop-simulation/growth/`
- `GET /api/crop-simulation/growth/<task_id>/status/`
- `POST /api/crop-simulation/current-farm-chart/`
- `POST /api/crop-simulation/harvest-prediction/`
- `POST /api/crop-simulation/yield-prediction/`
