sajad-dev/Ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1740c20ddb455653aa6929ccdafff48f5039e6be
Ai/docs/updated_pcse_apis_reference.md
T
sajad-dev ef593153ba UPDATE
2026-05-02 14:03:48 +03:30

19 KiB
Raw Blame History

مستند کامل APIهای آپدیت‌شده مرتبط با PCSE

این فایل APIهایی را توضیح می‌دهد که اخیراً آپدیت شده‌اند تا بتوانند برنامه آبیاری و برنامه کودهی را از ورودی بگیرند و به شبیه‌سازی PCSE پاس بدهند.

APIهای این سند:

  • POST /api/crop-simulation/growth/
  • GET /api/crop-simulation/growth/<task_id>/status/
  • POST /api/crop-simulation/current-farm-chart/
  • POST /api/crop-simulation/yield-prediction/
  • POST /api/crop-simulation/harvest-prediction/
  • GET /api/crop-simulation/yield-harvest-summary/
  • POST /api/irrigation/water-stress/

فرمت مشترک irrigation_recommendation

این فیلد در APIهای این سند می‌تواند ارسال شود:

{
  "events": [
    {
      "date": "2026-04-25",
      "amount": 2.5,
      "efficiency": 0.8
    }
  ]
}

توضیح فیلدها

  • events: آرایه‌ای از رویدادهای آبیاری
  • date: تاریخ اجرای آبیاری
  • amount: مقدار آبیاری برای event
  • efficiency: راندمان آبیاری، اختیاری

رفتار در PCSE

این داده‌ها به TimedEvents با سیگنال irrigate تبدیل می‌شوند.

فرمت مشترک fertilization_recommendation

{
  "events": [
    {
      "date": "2026-04-20",
      "N_amount": 45,
      "N_recovery": 0.7
    }
  ]
}

توضیح فیلدها

  • events: آرایه‌ای از رویدادهای کودهی
  • date: تاریخ اجرای کودهی
  • N_amount: مقدار نیتروژن
  • N_recovery: ضریب بازیافت/جذب نیتروژن

رفتار در PCSE

این داده‌ها به TimedEvents با سیگنال apply_n تبدیل می‌شوند.

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

کاربرد

شروع شبیه‌سازی رشد گیاه به‌صورت async و برگرداندن task_id.

ورودی

{
  "plant_name": "گوجه‌فرنگی",
  "dynamic_parameters": ["DVS", "LAI", "TAGP", "TWSO", "SM"],
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "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
  },
  "crop_parameters": {},
  "agromanagement": {},
  "irrigation_recommendation": {
    "events": [
      {
        "date": "2026-04-02",
        "amount": 2.5
      }
    ]
  },
  "fertilization_recommendation": {
    "events": [
      {
        "date": "2026-04-02",
        "N_amount": 45,
        "N_recovery": 0.7
      }
    ]
  },
  "page_size": 2
}

توضیح پارامترهای ورودی

  • plant_name: نام گیاه
  • dynamic_parameters: لیست پارامترهای دینامیک موردنیاز در خروجی
  • farm_uuid: شناسه مزرعه؛ اگر باشد، داده مزرعه و forecast از سیستم خوانده می‌شود
  • weather: آب‌وهوا به‌صورت مستقیم؛ اگر farm_uuid نباشد لازم است
  • soil_parameters: override برای پارامترهای خاک
  • site_parameters: override برای پارامترهای site
  • crop_parameters: override برای پارامترهای crop
  • agromanagement: override برای تقویم زراعی
  • irrigation_recommendation: برنامه آبیاری برای تزریق به PCSE
  • fertilization_recommendation: برنامه کودهی برای تزریق به PCSE
  • page_size: اندازه صفحه مراحل رشد در endpoint وضعیت task

اعتبارسنجی

  • حداقل یکی از farm_uuid یا weather باید ارسال شود
  • dynamic_parameters نباید خالی باشد
  • page_size باید بین 1 تا 50 باشد

پاسخ موفق

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

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

  • code: کد داخلی پاسخ
  • msg: پیام پاسخ
  • data.task_id: شناسه task
  • data.status_url: آدرس پیگیری وضعیت task
  • data.plant_name: نام گیاه

2) GET /api/crop-simulation/growth/<task_id>/status/

کاربرد

بررسی وضعیت اجرای شبیه‌سازی رشد و دریافت نتیجه نهایی.

پارامترهای Query

  • page: شماره صفحه
  • page_size: اندازه صفحه

پاسخ موفق

{
  "code": 200,
  "msg": "موفق",
  "data": {
    "task_id": "growth-task-1",
    "status": "SUCCESS",
    "status_fa": "موفق",
    "result": {
      "plant_name": "گوجه‌فرنگی",
      "dynamic_parameters": ["DVS", "LAI", "TAGP"],
      "engine": "موتور شبیه سازی PCSE",
      "model_name": "مدل ووفوست",
      "scenario_id": 12,
      "simulation_warning": null,
      "summary_metrics": {
        "yield_estimate": 5400.0,
        "biomass": 9800.0,
        "max_lai": 4.2
      },
      "stage_timeline": [
        {
          "order": 1,
          "stage_code": "vegetative",
          "stage_name": "رشد رویشی",
          "start_date": "2026-04-01",
          "end_date": "2026-04-05",
          "days_count": 5,
          "metrics": {
            "DVS": {
              "start": 0.1,
              "end": 0.8,
              "min": 0.1,
              "max": 0.8,
              "avg": 0.45
            }
          }
        }
      ],
      "stages_page": [],
      "pagination": {
        "page": 1,
        "page_size": 10,
        "total_items": 1,
        "total_pages": 1,
        "has_next": false,
        "has_previous": false
      },
      "daily_records_count": 14,
      "default_page_size": 10
    }
  }
}

توضیح کامل فیلدهای result

  • plant_name: نام گیاه
  • dynamic_parameters: پارامترهای پویا
  • engine: نام فارسی موتور اجرا
  • model_name: نام فارسی مدل
  • scenario_id: شناسه سناریوی ذخیره‌شده
  • simulation_warning: هشدار fallback یا خطای غیرکشنده
  • summary_metrics.yield_estimate: برآورد عملکرد
  • summary_metrics.biomass: بیوماس
  • summary_metrics.max_lai: بیشینه شاخص سطح برگ
  • stage_timeline: خلاصه مراحل رشد
  • stages_page: همان stage_timeline به‌صورت صفحه‌بندی‌شده
  • pagination: متادیتای صفحه‌بندی
  • daily_records_count: تعداد رکوردهای روزانه
  • default_page_size: اندازه صفحه پیش‌فرض

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

کاربرد

ساخت chart وضعیت فعلی مزرعه بر اساس شبیه‌سازی.

ورودی

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "irrigation_recommendation": {
    "events": [
      {
        "date": "2026-04-25",
        "amount": 2.5
      }
    ]
  },
  "fertilization_recommendation": {
    "events": [
      {
        "date": "2026-04-20",
        "N_amount": 45,
        "N_recovery": 0.7
      }
    ]
  }
}

توضیح ورودی

  • farm_uuid: شناسه مزرعه
  • plant_name: نام گیاه، اختیاری
  • irrigation_recommendation: برنامه آبیاری
  • fertilization_recommendation: برنامه کودهی

پاسخ موفق

{
  "code": 200,
  "msg": "موفق",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "plant_name": "گوجه‌فرنگی",
    "engine": "موتور شبیه سازی PCSE",
    "model_name": "مدل ووفوست",
    "scenario_id": 15,
    "simulation_warning": null,
    "categories": ["2026-04-01", "2026-04-02"],
    "series": [
      {
        "name": "تعداد برگ تخمینی",
        "key": "leaf_count_estimate",
        "data": [2400, 3600]
      }
    ],
    "summary": [
      {
        "title": "تعداد برگ تخمینی",
        "subtitle": "وضعیت فعلی",
        "amount": 3600,
        "unit": "برگ",
        "avatarColor": "success",
        "avatarIcon": "tabler-leaf"
      }
    ],
    "current_state": {
      "date": "2026-04-02",
      "leaf_count_estimate": 3600,
      "leaf_area_index": 0.3,
      "biomass_weight": 120.5,
      "storage_organ_weight": 0.0,
      "soil_moisture_percent": 41.2,
      "development_stage": 0.15,
      "gdd": 12.5
    },
    "metrics": {
      "yield_estimate": 5400,
      "biomass": 9800,
      "max_lai": 4.2
    },
    "daily_output": []
  }
}

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

  • categories: محور تاریخ chart
  • series: سری‌های نمودار
  • summary: کارت‌های summary
  • current_state: وضعیت آخرین روز شبیه‌سازی
  • metrics: متریک‌های خلاصه شبیه‌سازی
  • daily_output: خروجی روزانه کامل PCSE

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

کاربرد

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

ورودی

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "irrigation_recommendation": {
    "events": [
      {
        "date": "2026-04-25",
        "amount": 2.5
      }
    ]
  },
  "fertilization_recommendation": {
    "events": [
      {
        "date": "2026-04-20",
        "N_amount": 45,
        "N_recovery": 0.7
      }
    ]
  }
}

پاسخ موفق

{
  "code": 200,
  "msg": "موفق",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "plant_name": "گوجه‌فرنگی",
    "predictedYieldTons": 5.4,
    "predictedYieldRaw": 5400.0,
    "unit": "تن",
    "sourceUnit": "کیلوگرم در هکتار",
    "simulationEngine": "موتور شبیه سازی PCSE",
    "simulationModel": "مدل ووفوست",
    "scenarioId": 15,
    "simulationWarning": null,
    "supportingMetrics": {
      "yield_estimate": 5400.0,
      "biomass": 9800.0,
      "max_lai": 4.2
    }
  }
}

توضیح فیلدها

  • predictedYieldTons: عملکرد پیش‌بینی‌شده بر حسب تن
  • predictedYieldRaw: عملکرد خام بر حسب کیلوگرم در هکتار
  • unit: واحد نهایی
  • sourceUnit: واحد منبع
  • simulationEngine: نام موتور
  • simulationModel: نام مدل
  • scenarioId: شناسه سناریو
  • simulationWarning: هشدار احتمالی
  • supportingMetrics: متریک‌های پشتیبان شبیه‌سازی

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

کاربرد

پیش‌بینی زمان تقریبی برداشت.

ورودی

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "irrigation_recommendation": {
    "events": [
      {
        "date": "2026-04-25",
        "amount": 2.5
      }
    ]
  },
  "fertilization_recommendation": {
    "events": [
      {
        "date": "2026-04-20",
        "N_amount": 45,
        "N_recovery": 0.7
      }
    ]
  }
}

پاسخ موفق

{
  "code": 200,
  "msg": "موفق",
  "data": {
    "date": "2026-05-14",
    "dateFormatted": "14 May 2026",
    "daysUntil": 23,
    "description": "توضیح زمان برداشت",
    "optimalWindowStart": "2026-05-11",
    "optimalWindowEnd": "2026-05-17",
    "gddDetails": {
      "current_cumulative_gdd": 50,
      "required_gdd_for_maturity": 1200,
      "remaining_gdd": 1150,
      "estimated_days_to_harvest": 23,
      "predicted_harvest_date": "2026-05-14",
      "predicted_harvest_window": {
        "start": "2026-05-11",
        "end": "2026-05-17"
      },
      "daily_gdd_forecast": [],
      "simulation_engine": "pcse",
      "simulation_model_name": "Wofost81_NWLP_CWB_CNB",
      "simulation_warning": null,
      "scenario_id": 18
    }
  }
}

توضیح فیلدها

  • date: تاریخ برداشت پیش‌بینی‌شده
  • dateFormatted: تاریخ فرمت‌شده برای UI
  • daysUntil: تعداد روز تا برداشت
  • description: توضیح خلاصه
  • optimalWindowStart: شروع بازه بهینه برداشت
  • optimalWindowEnd: پایان بازه بهینه برداشت
  • gddDetails: جزئیات مبتنی بر GDD و شبیه‌سازی

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

کاربرد

ساخت داشبورد خلاصه عملکرد و برداشت.

ورودی

این API از query string استفاده می‌کند.

پارامترهای query

  • farm_uuid: شناسه مزرعه
  • season_year: سال زراعی
  • crop_name: نام محصول
  • include_narrative: اگر true باشد، تلاش برای تولید narrative می‌شود
  • irrigation_recommendation: JSON string برنامه آبیاری
  • fertilization_recommendation: JSON string برنامه کودهی

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

GET /api/crop-simulation/yield-harvest-summary/?farm_uuid=11111111-1111-1111-1111-111111111111&season_year=1404&crop_name=wheat&include_narrative=true&irrigation_recommendation={"events":[{"date":"2026-04-25","amount":2.5}]}&fertilization_recommendation={"events":[{"date":"2026-04-20","N_amount":45,"N_recovery":0.7}]}

پاسخ موفق

{
  "code": 200,
  "msg": "موفق",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "season_highlights_card": {
      "farm_uuid": "11111111-1111-1111-1111-111111111111",
      "crop_name": "wheat",
      "season_year": "1404",
      "title": "خلاصه فصل",
      "subtitle": "",
      "total_predicted_yield": 5.4,
      "yield_unit": "تن",
      "target_harvest_date": "2026-05-14",
      "days_until_harvest": 23,
      "average_readiness": 74,
      "primary_quality_grade": "A",
      "estimated_revenue": null,
      "soil_type": "loam"
    },
    "yield_prediction": {},
    "harvest_prediction_card": {},
    "harvest_readiness_zones": {},
    "yield_quality_bands": {},
    "harvest_operations_card": {},
    "yield_prediction_chart": {}
  }
}

ساختار response

  • season_highlights_card: خلاصه فصل
  • yield_prediction: بلوک پیش‌بینی عملکرد
  • harvest_prediction_card: بلوک پیش‌بینی برداشت
  • harvest_readiness_zones: آمادگی برداشت نواحی
  • yield_quality_bands: باندهای کیفیت محصول
  • harvest_operations_card: پیشنهاد عملیات برداشت
  • yield_prediction_chart: نمودار عملکرد و بیوماس

توضیح مهم

این API بخش‌هایی از response را از چند سرویس مختلف می‌سازد، بنابراین بعضی بلوک‌ها ساختار nested و بزرگ دارند. مخصوصاً:

  • yield_prediction
  • harvest_prediction_card
  • yield_prediction_chart

این سه بخش مستقیماً تحت تأثیر irrigation_recommendation و fertilization_recommendation قرار می‌گیرند چون از اجرای PCSE استفاده می‌کنند.

7) POST /api/irrigation/water-stress/

کاربرد

محاسبه شاخص تنش آبی با استفاده از خروجی شبیه‌سازی.

ورودی

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه‌فرنگی",
  "irrigation_recommendation": {
    "events": [
      {
        "date": "2026-04-25",
        "amount": 2.5
      }
    ]
  },
  "fertilization_recommendation": {
    "events": [
      {
        "date": "2026-04-20",
        "N_amount": 45,
        "N_recovery": 0.7
      }
    ]
  }
}

توضیح ورودی

  • farm_uuid: شناسه مزرعه
  • sensor_uuid: نام قدیمی برای farm_uuid
  • plant_name: نام گیاه، اختیاری
  • irrigation_recommendation: برنامه آبیاری
  • fertilization_recommendation: برنامه کودهی

پاسخ موفق

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "plant_name": "گوجه‌فرنگی",
    "waterStressIndex": 37,
    "level": "متوسط",
    "sourceMetric": {
      "soilMoisturePercent": 46.0,
      "availableWaterRatio": 0.72,
      "fieldCapacity": 0.34,
      "wiltingPoint": 0.14,
      "rootDepthCm": 120.0,
      "recentEt0": 0.33,
      "recentRain": 1.0,
      "soilMoistureDrop": 4.2,
      "developmentStage": 1.02,
      "stageCode": "flowering",
      "stageSensitivity": 1.2,
      "engine": "crop_simulation",
      "formula": "stress = clamp(((moisture_deficit + et0_pressure + trend_pressure - rainfall_relief - root_depth_relief) * stage_sensitivity), 0, 100)"
    }
  }
}

توضیح فیلدهای response

  • farm_uuid: شناسه مزرعه
  • plant_name: نام گیاه resolved شده
  • waterStressIndex: شاخص نهایی تنش آبی بین 0 تا 100
  • level: سطح تنش آبی (پایین، متوسط، بالا)
  • sourceMetric: جزئیات محاسبه

توضیح sourceMetric

  • soilMoisturePercent: درصد رطوبت خاک
  • availableWaterRatio: نسبت آب قابل استفاده
  • fieldCapacity: ظرفیت مزرعه
  • wiltingPoint: نقطه پژمردگی
  • rootDepthCm: عمق ریشه
  • recentEt0: تبخیر و تعرق مرجع اخیر
  • recentRain: بارش اخیر
  • soilMoistureDrop: افت رطوبت خاک
  • developmentStage: مرحله رشد عددی
  • stageCode: کد مرحله رشد
  • stageSensitivity: حساسیت مرحله رشد
  • engine: منبع محاسبه
  • formula: فرمول محاسبه شاخص

خطاهای رایج

خطای 400

وقتی ورودی نامعتبر باشد:

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

خطای 404

بیشتر در water-stress وقتی مزرعه پیدا نشود:

{
  "code": 404,
  "msg": "Farm not found.",
  "data": null
}

خطای 500

وقتی اجرای شبیه‌سازی یا ساخت response شکست بخورد:

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

جمع‌بندی

APIهایی که در این سند توضیح داده شدند، حالا می‌توانند از ورودی کاربر:

  • irrigation_recommendation
  • fertilization_recommendation

را دریافت کنند و آن‌ها را به لایه شبیه‌سازی PCSE پاس بدهند. این یعنی خروجی‌های:

  • رشد
  • chart مزرعه
  • پیش‌بینی عملکرد
  • پیش‌بینی برداشت
  • خلاصه Yield/Harvest
  • شاخص تنش آبی

می‌توانند تحت تأثیر برنامه آبیاری و برنامه کودهی ارسالی کاربر قرار بگیرند.

Reference in New Issue View Git Blame Copy Permalink