sajad-dev/Ai

Fork 0

Files

T

sajad-dev 88f56da582 UPDATE

2026-04-29 23:54:30 +03:30

33 KiB

Raw Blame History

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

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

نکات کلی

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

{
  "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 است

شکل خروجی

{
  "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 برای نمایش وضعیت هشدارهای مزرعه به این شکل است:

{
  "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 هشدارها به این شکل است:

{
  "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) — الزامی

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

{
  "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
      }
    ]
  }
}

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

{
  "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 — الزامی

خروجی موفق

{
  "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 — الزامی

خروجی موفق

{
  "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 — الزامی

خروجی موفق

{
  "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 — الزامی

خروجی موفق

{
  "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 تکمیلی است:

{
  "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`

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

GeoJSON Polygon

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

corners

{
  "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`

{
  "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 خلاصه تحلیلی و عملیاتی نیاز آبی را برمی‌گرداند:

{
  "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 — الزامی

خروجی موفق

{
  "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 — اختیاری

خروجی موفق

{
  "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 — الزامی

خروجی موفق

{
  "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 — الزامی

خروجی موفق

{
  "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 — الزامی

خروجی موفق

{
  "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/

خروجی موفق

{
  "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>/

خروجی موفق

{
  "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 برای تشخیص آفت/بیماری از روی تصویر به این شکل است:

{
  "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 برای پیش بینی ریسک آفات و بیماری به این شکل است:

{
  "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>/

خروجی موفق

{
  "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 نمایش داده نمی‌شوند. خروجی نهایی به این شکل است:

{
  "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 — اختیاری

خروجی موفق

{
  "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 برنمی‌گرداند. خروجی نهایی به این شکل است:

{
  "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 باید ارسال شود

خروجی موفق

{
  "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 — اختیاری

خروجی موفق

{
  "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 — اختیاری

خروجی موفق

{
  "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 — اختیاری

خروجی موفق

{
  "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 — اختیاری

خروجی موفق

{
  "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/

33 KiB Raw Blame History

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

نکات کلی

1) RAG

1.1) چت RAG

ورودی

قواعد الزامی

خروجی موفق

شکل خروجی

خطاها

2) Farm Alerts

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

ورودی

خروجی موفق

خطاها

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

ورودی

خروجی موفق

خطاها

3) Soil Data

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

ورودی

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

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

خطاها

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

ورودی

خروجی

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

ورودی

خروجی موفق

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

ورودی

خروجی موفق

خطاها

4) Soile

4.1) Heatmap رطوبت خاک

ورودی

خروجی موفق

خطاها

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

ورودی

خروجی موفق

خطاها

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

ورودی

خروجی موفق

خطاها

5) Farm Data

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

ورودی

نکته مهم

ساختار farm_boundary

ساختار sensor_payload

خروجی موفق

خطاها

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

ورودی

خروجی موفق

خطاها

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

ورودی

خروجی موفق

خطاها

6) Weather

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

ورودی

خروجی موفق

خطاها

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

ورودی

خروجی موفق

خطاها

7) Economy

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

ورودی

خروجی موفق

خطاها

8) Plants

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

33 KiB

Raw Blame History

ساختار `farm_boundary`

ساختار `sensor_payload`