sajad-dev/Logic

Fork 0

Files

T

sajad-dev d0e68a1a56 UPDATE

2026-05-11 03:27:21 +03:30

36 KiB

Raw Blame History

Crop Simulation API Reference

این فایل توضیح کامل API های ماژول crop_simulation را پوشش می دهد:

POST /api/crop-simulation/current-farm-chart/
POST /api/crop-simulation/growth/
GET /api/crop-simulation/growth/{task_id}/status/
POST /api/crop-simulation/harvest-prediction/
GET /api/crop-simulation/yield-harvest-summary/
POST /api/crop-simulation/yield-prediction/

الگوی کلی پاسخ ها

تقریبا همه endpoint ها از الگوی envelope زیر استفاده می کنند:

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

معنی فیلدهای envelope

فیلد	نوع	توضیح
`code`	integer	کد منطقی پاسخ. معمولا با HTTP status همسو است.
`msg`	string	پیام کوتاه پاسخ. در موفقیت معمولا `success` و در خطا متن فارسی خطا است.
`data`	object / null	بدنه اصلی داده. در خطاهای validation معمولا شامل جزئیات خطا است.

خطاهای رایج

HTTP Status	`code`	توضیح
`400`	`400`	ورودی نامعتبر است؛ مثل نبودن `farm_uuid` یا ناقص بودن payload
`500`	`500`	اجرای سرویس یا شبیه سازی داخلی با خطا مواجه شده است
`202`	`202`	تسک async با موفقیت در صف قرار گرفته است

1) POST `/api/crop-simulation/current-farm-chart/`

کاربرد

برای ساخت chart وضعیت فعلی مزرعه با استفاده از شبیه سازی رشد.
این endpoint داده هایی مثل:

روند روزانه رشد
بیوماس
وزن محصول
شاخص سطح برگ
رطوبت خاک

را برمی گرداند.

درخواست

Body

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی"
}

فیلدهای ورودی

فیلد	نوع	اجباری	توضیح
`farm_uuid`	string (UUID)	بله	شناسه یکتای مزرعه
`plant_name`	string	خیر	نام گیاه. اگر ارسال نشود سیستم سعی می کند گیاه پیش فرض مزرعه را تشخیص دهد

پاسخ موفق

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "plant_name": "گوجه‌فرنگی",
    "engine": "growth_projection",
    "model_name": "growth_projection_v1",
    "scenario_id": 12,
    "simulation_warning": null,
    "categories": ["2026-04-01", "2026-04-02"],
    "series": [
      {
        "name": "تعداد برگ تخمینی",
        "key": "leaf_count_estimate",
        "data": [120.0, 140.0]
      },
      {
        "name": "وزن بیوماس",
        "key": "biomass_weight",
        "data": [35.0, 45.0]
      }
    ],
    "summary": [
      {
        "title": "تعداد برگ تخمینی",
        "subtitle": "وضعیت فعلی",
        "amount": 140.0,
        "unit": "leaf",
        "avatarColor": "success",
        "avatarIcon": "tabler-leaf"
      }
    ],
    "current_state": {
      "date": "2026-04-02",
      "leaf_count_estimate": 140.0,
      "leaf_area_index": 0.0117,
      "biomass_weight": 45.0,
      "storage_organ_weight": 10.0,
      "soil_moisture_percent": 41.2,
      "development_stage": 0.35,
      "gdd": 9.0
    },
    "metrics": {
      "yield_estimate": 10.0
    },
    "daily_output": []
  }
}

توضیح کامل فیلدهای پاسخ

فیلد	نوع	توضیح
`farm_uuid`	string / null	شناسه مزرعه
`plant_name`	string	نام گیاهی که شبیه سازی برای آن انجام شده
`engine`	string / null	موتور شبیه سازی استفاده شده
`model_name`	string / null	نام مدل شبیه سازی
`scenario_id`	integer / null	شناسه سناریو اگر در سیستم ثبت شده باشد
`simulation_warning`	string / null	هشدار غیر بحرانی؛ مثلا وقتی fallback استفاده شده
`categories`	array[string]	محور زمانی نمودار؛ معمولا تاریخ های روزانه
`series`	array[object]	سری های نمودار برای رندر frontend
`summary`	array[object]	کارت های خلاصه برای نمایش سریع وضعیت فعلی
`current_state`	object	وضعیت آخرین روز شبیه سازی
`metrics`	object	شاخص های محاسبه شده نهایی
`daily_output`	array[object]	خروجی روزانه خام شبیه سازی

ساختار `series`

هر عضو series معمولا این ساختار را دارد:

فیلد	نوع	توضیح
`name`	string	عنوان سری برای chart
`key`	string	کلید فنی سری
`data`	array[number]	داده های عددی سری به ترتیب `categories`

نمونه key های مهم:

leaf_count_estimate
biomass_weight
storage_organ_weight
lai
soil_moisture_percent

ساختار `summary`

هر آیتم summary یک KPI card است:

فیلد	نوع	توضیح
`title`	string	عنوان کارت
`subtitle`	string	زیرعنوان
`amount`	number	مقدار اصلی کارت
`unit`	string	واحد
`avatarColor`	string	رنگ پیشنهادی برای UI
`avatarIcon`	string	آیکن پیشنهادی برای UI

ساختار `current_state`

فیلد	نوع	توضیح
`date`	string	تاریخ آخرین رکورد
`leaf_count_estimate`	number	تعداد برگ تخمینی
`leaf_area_index`	number	شاخص سطح برگ (LAI)
`biomass_weight`	number	وزن بیوماس
`storage_organ_weight`	number	وزن اندام ذخیره ای / محصول
`soil_moisture_percent`	number	رطوبت خاک به درصد
`development_stage`	number	مرحله رشد گیاه به صورت DVS
`gdd`	number	درجه روز رشد همان روز

ساختار `daily_output`

این بخش خروجی خام شبیه سازی است و معمولا شامل فیلدهایی مثل این هاست:

DAY
DVS
LAI
TAGP
TWSO
SM
GDD
TMIN
TMAX
RAIN
ET0

خطاها

400

وقتی farm_uuid ارسال نشود:

{
  "code": 400,
  "msg": "داده نامعتبر.",
  "data": {
    "farm_uuid": ["This field is required."]
  }
}

500

وقتی شبیه ساز داخلی fail شود:

{
  "code": 500,
  "msg": "خطا در اجرای chart شبیه سازی مزرعه: simulator offline",
  "data": null
}

2) POST `/api/crop-simulation/growth/`

کاربرد

برای شروع شبیه سازی رشد گیاه به صورت async.
این endpoint خود نتیجه نهایی را برنمی گرداند؛ فقط یک task_id می دهد تا بعدا از endpoint وضعیت استفاده شود.

درخواست

نمونه با weather مستقیم

{
  "plant_name": "گوجه‌فرنگی",
  "dynamic_parameters": ["DVS", "LAI", "TAGP", "TWSO", "SM"],
  "weather": [
    {
      "DAY": "2026-04-01",
      "LAT": 35.7,
      "LON": 51.4,
      "TMIN": 12,
      "TMAX": 24,
      "RAIN": 0.0,
      "ET0": 0.32
    }
  ],
  "soil_parameters": {
    "SMFCF": 0.34,
    "SMW": 0.14,
    "RDMSOL": 120.0
  },
  "site_parameters": {
    "WAV": 40.0
  },
  "page_size": 2
}

نمونه با farm

{
  "plant_name": "گوجه‌فرنگی",
  "dynamic_parameters": ["DVS", "LAI", "TAGP"],
  "farm_uuid": "11111111-1111-1111-1111-111111111111"
}

فیلدهای ورودی

فیلد	نوع	اجباری	توضیح
`plant_name`	string	بله	نام گیاه
`dynamic_parameters`	array[string]	بله	پارامترهای رشد که باید در خروجی stageها گزارش شوند
`farm_uuid`	string (UUID)	شرطی	اگر weather نفرستید لازم است
`weather`	array/object	شرطی	اگر `farm_uuid` نفرستید لازم است
`soil_parameters`	object	خیر	پارامترهای خاک
`site_parameters`	object	خیر	پارامترهای سایت / مزرعه
`crop_parameters`	object	خیر	پارامترهای مدل محصول
`agromanagement`	object / array	خیر	مدیریت زراعی
`page_size`	integer	خیر	اندازه صفحه stage ها، بین `1` تا `50`

نکته مهم validation

حداقل یکی از این دو باید وجود داشته باشد:

farm_uuid
weather

پاسخ موفق

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

توضیح فیلدهای پاسخ

فیلد	نوع	توضیح
`task_id`	string	شناسه تسک Celery
`status_url`	string	آدرس endpoint وضعیت برای پیگیری نتیجه
`plant_name`	string	نام گیاه مربوط به این شبیه سازی

خطاهای رایج

400

اگر نه farm_uuid و نه weather ارسال نشده باشد:

{
  "code": 400,
  "msg": "داده نامعتبر.",
  "data": {
    "non_field_errors": ["یکی از farm_uuid یا weather باید ارسال شود."]
  }
}

3) GET `/api/crop-simulation/growth/{task_id}/status/`

کاربرد

برای گرفتن وضعیت تسک async شبیه سازی رشد.

Query Parameters

فیلد	نوع	اجباری	توضیح
`page`	integer	خیر	شماره صفحه stage ها
`page_size`	integer	خیر	تعداد stage ها در هر صفحه، حداکثر `50`

حالت های پاسخ

این endpoint همیشه HTTP 200 می دهد، ولی فیلد data.status تعیین می کند تسک در چه وضعیتی است.

مقادیر مهم:

PENDING
PROGRESS
SUCCESS
FAILURE

پاسخ در حالت `PENDING`

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "growth-task-1",
    "status": "PENDING",
    "message": "تسک در صف یا یافت نشد."
  }
}

توضیح

فیلد	توضیح
`task_id`	شناسه تسک
`status`	وضعیت فعلی
`message`	پیام کمکی برای کاربر

پاسخ در حالت `PROGRESS`

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "growth-task-1",
    "status": "PROGRESS",
    "progress": {
      "current": 2,
      "total": 3,
      "message": "simulation finished"
    }
  }
}

توضیح

فیلد	نوع	توضیح
`progress.current`	integer	مرحله فعلی پردازش
`progress.total`	integer	تعداد کل مراحل
`progress.message`	string	توضیح مرحله جاری

پاسخ در حالت `SUCCESS`

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "growth-task-1",
    "status": "SUCCESS",
    "result": {
      "plant_name": "گوجه‌فرنگی",
      "dynamic_parameters": ["DVS"],
      "engine": "growth_projection",
      "model_name": "growth_projection_v1",
      "scenario_id": null,
      "simulation_warning": null,
      "summary_metrics": {},
      "stage_timeline": [
        {
          "order": 1,
          "stage_code": "establishment",
          "stage_name": "استقرار",
          "start_date": "2026-04-01",
          "end_date": "2026-04-02",
          "days_count": 2,
          "metrics": {
            "DVS": {
              "start": 0.1,
              "end": 0.2,
              "min": 0.1,
              "max": 0.2,
              "avg": 0.15
            }
          }
        }
      ],
      "stages_page": [
        {
          "order": 1,
          "stage_code": "establishment",
          "stage_name": "استقرار",
          "start_date": "2026-04-01",
          "end_date": "2026-04-02",
          "days_count": 2,
          "metrics": {
            "DVS": {
              "start": 0.1,
              "end": 0.2,
              "min": 0.1,
              "max": 0.2,
              "avg": 0.15
            }
          }
        }
      ],
      "pagination": {
        "page": 1,
        "page_size": 1,
        "total_items": 3,
        "total_pages": 3,
        "has_next": true,
        "has_previous": false
      },
      "daily_records_count": 7,
      "default_page_size": 1
    }
  }
}

توضیح کامل `result`

فیلد	نوع	توضیح
`plant_name`	string	نام گیاه
`dynamic_parameters`	array[string]	پارامترهایی که stage metrics برایشان تولید شده
`engine`	string / null	موتور شبیه سازی
`model_name`	string / null	نام مدل
`scenario_id`	integer / null	شناسه سناریو
`simulation_warning`	string / null	هشدار غیر بحرانی
`summary_metrics`	object	شاخص های خلاصه
`stage_timeline`	array[object]	کل timeline مراحل رشد
`stages_page`	array[object]	فقط صفحه فعلی timeline
`pagination`	object	اطلاعات صفحه بندی
`daily_records_count`	integer	تعداد رکوردهای روزانه شبیه سازی
`default_page_size`	integer	اندازه صفحه پیش فرض

ساختار هر stage

فیلد	نوع	توضیح
`order`	integer	ترتیب مرحله در timeline
`stage_code`	string	کد فنی مرحله رشد
`stage_name`	string	نام قابل نمایش مرحله
`start_date`	string	تاریخ شروع مرحله
`end_date`	string	تاریخ پایان مرحله
`days_count`	integer	تعداد روزهای این مرحله
`metrics`	object	خلاصه آماری پارامترهای درخواستی

ساختار `metrics` در هر stage

برای هر پارامتر مثل DVS یا LAI:

فیلد	توضیح
`start`	مقدار ابتدای مرحله
`end`	مقدار پایان مرحله
`min`	کمترین مقدار در مرحله
`max`	بیشترین مقدار در مرحله
`avg`	میانگین مقدار در مرحله

ساختار `pagination`

فیلد	نوع	توضیح
`page`	integer	شماره صفحه فعلی
`page_size`	integer	اندازه صفحه فعلی
`total_items`	integer	تعداد کل stage ها
`total_pages`	integer	تعداد کل صفحه ها
`has_next`	boolean	آیا صفحه بعدی وجود دارد
`has_previous`	boolean	آیا صفحه قبلی وجود دارد

پاسخ در حالت `FAILURE`

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "growth-task-1",
    "status": "FAILURE",
    "error": "task crashed"
  }
}

توضیح

فیلد	توضیح
`error`	متن خطای نهایی تسک

4) POST `/api/crop-simulation/harvest-prediction/`

کاربرد

برای پیش بینی زمان تقریبی برداشت بر اساس خروجی شبیه سازی رشد و GDD.

درخواست

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی"
}

فیلدهای ورودی

فیلد	نوع	اجباری	توضیح
`farm_uuid`	string (UUID)	بله	شناسه مزرعه
`plant_name`	string	خیر	نام گیاه

پاسخ موفق

{
  "code": 200,
  "msg": "success",
  "data": {
    "date": "2026-05-14",
    "dateFormatted": "14 May 2026",
    "daysUntil": 43,
    "description": "شبيه ساز نشان مي دهد حدود 43 روز ديگر تا برداشت باقي مانده است.",
    "optimalWindowStart": "2026-05-11",
    "optimalWindowEnd": "2026-05-17",
    "gddDetails": {
      "current_cumulative_gdd": 50.0,
      "required_gdd_for_maturity": 1200.0,
      "remaining_gdd": 1150.0,
      "simulation_engine": "growth_projection"
    }
  }
}

توضیح کامل فیلدهای پاسخ

فیلد	نوع	توضیح
`date`	string	تاریخ تخمینی برداشت با فرمت ISO
`dateFormatted`	string	همان تاریخ به فرمت human-readable
`daysUntil`	integer	تعداد روز باقی مانده تا برداشت
`description`	string	توضیح متنی قابل نمایش برای کاربر
`optimalWindowStart`	string	شروع بازه مناسب برداشت
`optimalWindowEnd`	string	پایان بازه مناسب برداشت
`gddDetails`	object	جزئیات محاسبات GDD و داده های پشتیبان

ساختار `gddDetails`

معمولا شامل این فیلدهاست:

فیلد	نوع	توضیح
`current_cumulative_gdd`	number	GDD تجمعی فعلی
`required_gdd_for_maturity`	number	GDD مورد نیاز برای رسیدن به بلوغ
`remaining_gdd`	number	میزان GDD باقی مانده
`estimated_days_to_harvest`	integer	روزهای برآوردی تا برداشت
`predicted_harvest_date`	string	تاریخ برآوردی برداشت
`predicted_harvest_window`	object	بازه شروع/پایان مناسب برداشت
`daily_gdd_forecast`	array[object]	پیش بینی روزانه GDD
`simulation_engine`	string	موتور شبیه سازی
`simulation_model_name`	string	نام مدل شبیه سازی
`simulation_warning`	string / null	هشدار داخلی شبیه سازی
`scenario_id`	integer / null	شناسه سناریو

ساختار `daily_gdd_forecast`

هر آیتم:

فیلد	نوع	توضیح
`date`	string	تاریخ
`gdd`	number	GDD همان روز
`cumulative_gdd`	number	GDD تجمعی تا آن روز
`development_stage`	number	DVS آن روز

خطاها

400

{
  "code": 400,
  "msg": "داده نامعتبر.",
  "data": {
    "farm_uuid": ["This field is required."]
  }
}

500

{
  "code": 500,
  "msg": "خطا در پیش بینی زمان برداشت: harvest offline",
  "data": null
}

5) GET `/api/crop-simulation/yield-harvest-summary/`

کاربرد

برای برگرداندن داشبورد کامل خلاصه عملکرد و برداشت.
این endpoint ترکیبی از چند block مختلف است:

season highlights
yield prediction
harvest prediction
readiness zones
quality bands
harvest operations
yield chart

این endpoint می تواند علاوه بر داده های deterministic، متن های narrative را هم اضافه کند.

Query Parameters

فیلد	نوع	اجباری	توضیح
`farm_uuid`	string (UUID)	بله	شناسه یکتای مزرعه
`season_year`	integer	خیر	سال زراعی
`crop_name`	string	خیر	نام محصول
`include_narrative`	boolean	خیر	اگر `true` باشد متن های توضیحی RAG هم merge می شوند

نمونه درخواست

GET /api/crop-simulation/yield-harvest-summary/?farm_uuid=11111111-1111-1111-1111-111111111111&season_year=1404&crop_name=wheat&include_narrative=true

پاسخ موفق

نمونه واقعی پاسخ فعلی:

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "season_highlights_card": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "crop_name": "",
      "season_year": "",
      "title": "Season highlights",
      "subtitle": "Projected harvest in 152 days with minimal yield prediction issues due to simulation fallback.",
      "total_predicted_yield": 0.0,
      "yield_unit": "تن",
      "target_harvest_date": "28 September 2026",
      "days_until_harvest": 152,
      "average_readiness": null,
      "primary_quality_grade": "C",
      "estimated_revenue": null,
      "soil_type": "loam"
    },
    "yield_prediction": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "crop_name": "خیار",
      "season_year": "",
      "predicted_yield_tons": 0.0,
      "predicted_yield_raw": 0.0,
      "unit": "تن",
      "source_unit": "kg/ha",
      "simulation_engine": "growth_projection",
      "simulation_model": "growth_projection_v1",
      "scenario_id": null,
      "simulation_warning": "Simulation engine failed, fallback projection used: Value for parameter CVL missing.",
      "secondary_kpis_estimated": true,
      "descriptionSource": "deterministic",
      "farm_context": {
        "soil_type": "loam",
        "soil_data_provider": "mock"
      },
      "supporting_metrics": {
        "yield_estimate": 0.0,
        "biomass": 232.9052,
        "max_lai": 0.1063
      },
      "explanation": "شبيه ساز با محدوديت داده مواجه شد؛ براورد فعلی بدون تضمین و با روش جایگزین انجام شده است."
    },
    "harvest_prediction_card": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "crop_name": "",
      "season_year": "",
      "harvest_date": "2026-09-28",
      "harvest_date_formatted": "28 September 2026",
      "days_until": 152,
      "optimal_window_start": "2026-09-25",
      "optimal_window_end": "2026-10-01",
      "description": "شبيه ساز تا انتهاي forecast هنوز به رسيدگي کامل نرسيده، اما با ميانگين رشد فعلي براورد مي شود خیار حدود 152 روز ديگر به برداشت برسد.",
      "descriptionSource": "deterministic",
      "field_conditions": {
        "soil_moisture": 42.3,
        "soil_temperature": 21.4
      },
      "readiness_metrics": {
        "current_cumulative_gdd": 0.0,
        "required_gdd_for_maturity": 1200.0
      }
    },
    "harvest_readiness_zones": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "observationDate": null,
      "vegetationHealthClass": "Unavailable",
      "meanNdvi": null,
      "ndviTrend": null,
      "averageReadiness": null,
      "zones": [],
      "source": "ndvi_health_service",
      "summary": "خیار هنوز در مراحل اولیه رشد است، 152 روز تا برداشته شدن باقی مانده است. میانگین آمادگی موجود نیست."
    },
    "yield_quality_bands": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "crop_name": "",
      "season_year": "",
      "source": "deterministic_grading_rules",
      "is_estimated": true,
      "protein_content": {
        "value": 9.51,
        "unit": "%"
      },
      "moisture_percentage": {
        "value": 14.03,
        "unit": "%"
      },
      "grade_distribution": [
        {"grade": "A", "share_percent": 16},
        {"grade": "B", "share_percent": 41},
        {"grade": "C", "share_percent": 43}
      ],
      "primary_quality_grade": "C",
      "quality_score": 59,
      "summary": "Primary quality grade is C."
    },
    "harvest_operations_card": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "crop_name": "خیار",
      "season_year": "",
      "stage_label": "early_pre_harvest",
      "phase_name": "vegetative",
      "days_until_harvest": 152,
      "current_dvs": 0.0394,
      "summary": "Operations are prioritized for خیار with 152 days remaining until the predicted harvest window.",
      "rules_source": "deterministic_dvs_rules",
      "field_context": {
        "soil_type": "loam",
        "soil_moisture": 42.3,
        "soil_temperature": 21.4
      },
      "steps": [
        {
          "key": "weekly_monitoring",
          "title": "Run weekly crop maturity checks",
          "status": "active",
          "is_completed": false,
          "estimated_days": 14,
          "note": "Check weekly crop status for any signs of maturity changes."
        }
      ]
    },
    "yield_prediction_chart": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "crop_name": "خیار",
      "season_year": "",
      "series": [
        {
          "name": "Predicted Yield",
          "type": "line",
          "data": [[1777420800000, 0.0]]
        },
        {
          "name": "Biomass",
          "type": "area",
          "data": [[1777420800000, 89.392]]
        }
      ],
      "xAxis": {
        "type": "datetime"
      },
      "meta": {
        "unit": "kg/ha",
        "simulation_engine": "growth_projection",
        "simulation_model": "growth_projection_v1",
        "scenario_id": null,
        "simulation_warning": "Simulation engine failed, fallback projection used: Value for parameter CVL missing.",
        "field_context": {
          "soil_type": "loam",
          "center_coordinates": {
            "lat": 50.0,
            "lon": 50.0
          }
        }
      }
    }
  }
}

توضیح top-level response

فیلد	نوع	توضیح
`farm_uuid`	string	شناسه مزرعه
`season_highlights_card`	object	خلاصه مهم ترین KPI ها
`yield_prediction`	object	خروجی پیش بینی عملکرد
`harvest_prediction_card`	object	تاریخ و وضعیت برداشت
`harvest_readiness_zones`	object	وضعیت آمادگی برداشت در zoneها
`yield_quality_bands`	object	کیفیت برآوردی محصول
`harvest_operations_card`	object	عملیات پیشنهادی برداشت
`yield_prediction_chart`	object	داده نمودار عملکرد و بیوماس

توضیح `season_highlights_card`

فیلد	نوع	توضیح
`title`	string	عنوان کارت
`subtitle`	string	متن توضیحی کوتاه؛ ممکن است از RAG بیاید
`total_predicted_yield`	number / null	عملکرد پیش بینی شده
`yield_unit`	string	واحد عملکرد
`target_harvest_date`	string / null	تاریخ هدف برداشت
`days_until_harvest`	integer / null	روز باقی مانده
`average_readiness`	number / null	میانگین آمادگی zoneها
`primary_quality_grade`	string / null	درجه کیفیت غالب
`estimated_revenue`	number / null	درآمد تخمینی اگر داده اقتصادی موجود باشد
`soil_type`	string / null	نوع خاک

توضیح `yield_prediction`

فیلد	نوع	توضیح
`predicted_yield_tons`	number	عملکرد بر حسب تن
`predicted_yield_raw`	number	عملکرد خام معمولا بر حسب `kg/ha`
`unit`	string	واحد نمایشی
`source_unit`	string	واحد منبع
`simulation_engine`	string / null	موتور شبیه سازی
`simulation_model`	string / null	نام مدل
`scenario_id`	integer / null	شناسه سناریو
`simulation_warning`	string / null	هشدار شبیه سازی
`secondary_kpis_estimated`	boolean	آیا KPIهای ثانویه تخمینی هستند
`descriptionSource`	string	منبع توضیح؛ معمولا `deterministic` یا `rag`
`farm_context`	object	بخشی از context مزرعه
`supporting_metrics`	object	متریک های پشتیبان مثل `yield_estimate` و `biomass`
`explanation`	string	توضیح متنی برای کاربر

توضیح `harvest_prediction_card`

فیلد	نوع	توضیح
`harvest_date`	string	تاریخ ISO برداشت
`harvest_date_formatted`	string	تاریخ قابل نمایش
`days_until`	integer	تعداد روز باقی مانده
`optimal_window_start`	string	شروع پنجره مناسب برداشت
`optimal_window_end`	string	پایان پنجره مناسب برداشت
`description`	string	توضیح متنی
`descriptionSource`	string	منبع متن
`field_conditions`	object	شرایط فعلی مزرعه مثل رطوبت و دما
`readiness_metrics`	object	جزئیات محاسبات readiness/GDD

توضیح `harvest_readiness_zones`

فیلد	نوع	توضیح
`observationDate`	string / null	تاریخ مشاهده NDVI
`vegetationHealthClass`	string / null	کلاس سلامت پوشش گیاهی
`meanNdvi`	number / null	NDVI میانگین
`ndviTrend`	number / null	روند تغییر NDVI
`averageReadiness`	number / null	میانگین آمادگی zoneها
`zones`	array[object]	فهرست zoneها
`source`	string	منبع داده
`summary`	string	توضیح متنی خلاصه

ساختار هر zone

فیلد	نوع	توضیح
`zoneId`	string	شناسه zone
`zoneLabel`	string	نام نمایشی zone
`gridPosition`	object / null	موقعیت zone در grid
`meanNdvi`	number	میانگین NDVI zone
`readiness`	integer	درصد آمادگی برداشت
`daysUntil`	integer	روزهای تخمینی تا آمادگی
`status`	string	وضعیت مثل `ready`, `approaching`, `monitoring`, `not_ready`

توضیح `yield_quality_bands`

فیلد	نوع	توضیح
`source`	string	منبع محاسبه کیفیت
`is_estimated`	boolean	آیا مقادیر تخمینی هستند
`protein_content`	object	درصد پروتئین
`moisture_percentage`	object	درصد رطوبت
`grade_distribution`	array[object]	توزیع درصدی gradeها
`primary_quality_grade`	string	grade غالب
`quality_score`	number	امتیاز کیفیت
`summary`	string	خلاصه متنی کیفیت

ساختار `protein_content` و `moisture_percentage`

فیلد	نوع	توضیح
`value`	number	مقدار
`unit`	string	واحد، معمولا `%`

ساختار `grade_distribution`

فیلد	نوع	توضیح
`grade`	string	گرید کیفیت مثل `A`, `B`, `C`
`share_percent`	integer	سهم درصدی آن گرید

توضیح `harvest_operations_card`

فیلد	نوع	توضیح
`stage_label`	string	برچسب مرحله عملیاتی
`phase_name`	string	نام فاز رشد
`days_until_harvest`	integer	روز باقی مانده تا برداشت
`current_dvs`	number	DVS فعلی
`summary`	string	خلاصه عملیاتی
`rules_source`	string	منبع قواعد تصمیم
`field_context`	object	context مزرعه
`steps`	array[object]	گام های عملیاتی

ساختار هر step

فیلد	نوع	توضیح
`key`	string	کلید فنی step
`title`	string	عنوان عملیات
`status`	string	وضعیت مثل `active`, `upcoming`, `ready`
`is_completed`	boolean	آیا انجام شده
`estimated_days`	integer	روز برآوردی برای انجام / رسیدن
`note`	string	توضیح تکمیلی یا توصیه

توضیح `yield_prediction_chart`

فیلد	نوع	توضیح
`series`	array[object]	سری های نمودار عملکرد و بیوماس
`xAxis`	object	تنظیم محور افقی
`meta`	object	متادیتای chart

ساختار `yield_prediction_chart.series`

فیلد	نوع	توضیح
`name`	string	نام سری
`type`	string	نوع رسم مثل `line` یا `area`
`data`	arraytimestamp, value	داده های نمودار بر پایه timestamp یونیکس میلی ثانیه

توضیح `yield_prediction_chart.meta`

فیلد	نوع	توضیح
`unit`	string	واحد داده chart
`simulation_engine`	string	موتور شبیه سازی
`simulation_model`	string	مدل
`scenario_id`	integer / null	شناسه سناریو
`simulation_warning`	string / null	هشدار شبیه سازی
`field_context`	object	context مزرعه مثل نوع خاک و مختصات

خطاها

400

وقتی farm_uuid ارسال نشده باشد:

{
  "code": 400,
  "msg": "داده نامعتبر.",
  "data": {
    "farm_uuid": ["This field is required."]
  }
}

6) POST `/api/crop-simulation/yield-prediction/`

کاربرد

برای تبدیل خروجی شبیه سازی رشد به پیش بینی عملکرد مزرعه.

درخواست

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی"
}

فیلدهای ورودی

فیلد	نوع	اجباری	توضیح
`farm_uuid`	string (UUID)	بله	شناسه مزرعه
`plant_name`	string	خیر	نام گیاه

پاسخ موفق

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "plant_name": "گوجه‌فرنگی",
    "predictedYieldTons": 5.4,
    "predictedYieldRaw": 5400.0,
    "unit": "تن",
    "sourceUnit": "kg/ha",
    "simulationEngine": "growth_projection",
    "simulationModel": "growth_projection_v1",
    "scenarioId": 12,
    "simulationWarning": null,
    "supportingMetrics": {
      "yield_estimate": 5400.0
    }
  }
}

توضیح کامل فیلدهای پاسخ

فیلد	نوع	توضیح
`farm_uuid`	string	شناسه مزرعه
`plant_name`	string / null	نام گیاه
`predictedYieldTons`	number	عملکرد پیش بینی شده بر حسب تن
`predictedYieldRaw`	number	مقدار خام عملکرد
`unit`	string	واحد نمایشی، معمولا `تن`
`sourceUnit`	string	واحد محاسباتی اصلی، معمولا `kg/ha`
`simulationEngine`	string / null	موتور شبیه سازی
`simulationModel`	string / null	مدل شبیه سازی
`scenarioId`	integer / null	شناسه سناریو
`simulationWarning`	string / null	هشدار شبیه سازی
`supportingMetrics`	object	متریک های پشتیبان مورد استفاده برای محاسبه عملکرد

خطاها

400

{
  "code": 400,
  "msg": "داده نامعتبر.",
  "data": {
    "farm_uuid": ["This field is required."]
  }
}

500

{
  "code": 500,
  "msg": "خطا در پیش بینی عملکرد: yield offline",
  "data": null
}

جمع بندی تفاوت endpoint ها

Endpoint	کاربرد اصلی	sync/async
`POST /current-farm-chart/`	ساخت نمودار وضعیت فعلی مزرعه	sync
`POST /growth/`	شروع شبیه سازی رشد	async
`GET /growth/{task_id}/status/`	بررسی وضعیت و نتیجه شبیه سازی رشد	async status
`POST /harvest-prediction/`	پیش بینی زمان برداشت	sync
`GET /yield-harvest-summary/`	داشبورد کامل عملکرد و برداشت	sync
`POST /yield-prediction/`	پیش بینی عملکرد نهایی	sync

نکات مهم برای frontend

در endpoint growth/status همیشه به data.status نگاه کنید، نه فقط HTTP status.
در پاسخ های chart و summary ممکن است simulation_warning مقدار داشته باشد، حتی اگر HTTP 200 باشد.
در yield-harvest-summary بعضی فیلدها ممکن است null باشند، مخصوصا:
- estimated_revenue
- average_readiness
- scenario_id
- simulation_warning
در yield_prediction_chart.series[].data timestamp ها بر حسب milliseconds هستند.
در yield-harvest-summary اگر include_narrative=true باشد، بعضی متن ها ممکن است از RAG بیایند ولی اعداد deterministic باقی می مانند.

مسیر فایل

این داکیومنت در مسیر زیر ذخیره شده است:

docs/crop_simulation_api_reference.md

36 KiB Raw Blame History

Crop Simulation API Reference

الگوی کلی پاسخ ها

معنی فیلدهای envelope

خطاهای رایج

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

کاربرد

درخواست

Body

فیلدهای ورودی

پاسخ موفق

توضیح کامل فیلدهای پاسخ

ساختار series

ساختار summary

ساختار current_state

ساختار daily_output

خطاها

400

500

2) POST /api/crop-simulation/growth/

کاربرد

درخواست

نمونه با weather مستقیم

نمونه با farm

فیلدهای ورودی

نکته مهم validation

پاسخ موفق

توضیح فیلدهای پاسخ

خطاهای رایج

400

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

کاربرد

Query Parameters

حالت های پاسخ

پاسخ در حالت PENDING

توضیح

پاسخ در حالت PROGRESS

توضیح

پاسخ در حالت SUCCESS

توضیح کامل result

ساختار هر stage

ساختار metrics در هر stage

ساختار pagination

پاسخ در حالت FAILURE

توضیح

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

کاربرد

درخواست

فیلدهای ورودی

پاسخ موفق

توضیح کامل فیلدهای پاسخ

ساختار gddDetails

ساختار daily_gdd_forecast

خطاها

400

500

5) GET /api/crop-simulation/yield-harvest-summary/

کاربرد

Query Parameters

نمونه درخواست

پاسخ موفق

توضیح top-level response

توضیح season_highlights_card

توضیح yield_prediction

توضیح harvest_prediction_card

توضیح harvest_readiness_zones

ساختار هر zone

توضیح yield_quality_bands

ساختار protein_content و moisture_percentage

ساختار grade_distribution

توضیح harvest_operations_card

ساختار هر step

توضیح yield_prediction_chart

ساختار yield_prediction_chart.series

توضیح yield_prediction_chart.meta

خطاها

400

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

کاربرد

درخواست

36 KiB

Raw Blame History

1) POST `/api/crop-simulation/current-farm-chart/`

ساختار `series`

ساختار `summary`

ساختار `current_state`

ساختار `daily_output`

2) POST `/api/crop-simulation/growth/`

3) GET `/api/crop-simulation/growth/{task_id}/status/`

پاسخ در حالت `PENDING`

پاسخ در حالت `PROGRESS`

پاسخ در حالت `SUCCESS`

توضیح کامل `result`

ساختار `metrics` در هر stage

ساختار `pagination`

پاسخ در حالت `FAILURE`

4) POST `/api/crop-simulation/harvest-prediction/`

ساختار `gddDetails`

ساختار `daily_gdd_forecast`

5) GET `/api/crop-simulation/yield-harvest-summary/`

توضیح `season_highlights_card`

توضیح `yield_prediction`

توضیح `harvest_prediction_card`

توضیح `harvest_readiness_zones`

توضیح `yield_quality_bands`

ساختار `protein_content` و `moisture_percentage`

ساختار `grade_distribution`

توضیح `harvest_operations_card`

توضیح `yield_prediction_chart`

ساختار `yield_prediction_chart.series`

توضیح `yield_prediction_chart.meta`

6) POST `/api/crop-simulation/yield-prediction/`