Logic/Modules/Ai/docs/pcse_api_list.md

لیست APIهایی که با استفاده از PCSE تحلیل انجام می‌دهند

این فایل APIهایی را فهرست می‌کند که در این پروژه یا مستقیماً از PCSE استفاده می‌کنند، یا بخشی از تحلیلشان به خروجی‌های شبیه‌سازی PCSE وابسته است.
همچنین مشخص می‌کند:

• از چه مدل PCSE استفاده می‌شود
• ورودی‌های لازم PCSE در این پروژه از کجا تأمین می‌شوند
• برنامه آبیاری، برنامه کودهی و داده آب‌وهوا چطور به مدل تزریق می‌شوند

مدل PCSE مورد استفاده در پروژه

مدل پیش‌فرضی که در سرویس شبیه‌سازی استفاده می‌شود این است:

• Wofost81_NWLP_CWB_CNB

توضیح کوتاه:

• Wofost81: نسخه 8.1 از خانواده مدل‌های WOFOST
• NWLP: شبیه‌سازی با محدودیت نیتروژن
• CWB: water balance
• CNB: carbon/nitrogen balance

بنابراین APIهایی که واقعاً از موتور اصلی شبیه‌سازی استفاده می‌کنند، عملاً روی این مدل اجرا می‌شوند مگر اینکه بعداً در کد override شده باشد.

PCSE در این پروژه چه ورودی‌هایی می‌خواهد؟

در این پروژه لایه شبیه‌سازی برای اجرای PCSE این ورودی‌ها را می‌سازد:

1. weather

رکوردهای آب‌وهوا با فیلدهای زیر:

• DAY
• LAT
• LON
• ELEV
• IRRAD
• TMIN
• TMAX
• VAP
• WIND
• RAIN
• E0
• ES0
• ET0

2. soil

پارامترهای خاک، از جمله:

• SMFCF
• SMW
• SM0
• RDMSOL
• CRAIRC
• SOPE
• KSUB

و در این پروژه بعضی شاخص‌های کمکی هم کنار آن نگهداری می‌شوند، مثل:

• nitrogen
• phosphorus
• potassium
• soil_ph
• electrical_conductivity

3. site_parameters

پارامترهای سایت/شرایط اولیه، از جمله:

• WAV
• SMLIM
• IFUNRN
• NOTINF
• SSI
• SSMAX
• NAVAILI

4. crop_parameters

پارامترهای محصول. این‌ها یا از پروفایل شبیه‌سازی گیاه می‌آیند، یا اگر موجود نباشند به‌صورت default ساخته می‌شوند. مهم‌ترین defaultها:

• crop_name
• TSUM1
• TSUM2
• YIELD_SCALE
• MAX_LAI
• MAX_BIOMASS

5. agromanagement

تقویم و رویدادهای زراعی، شامل:

• CropCalendar
• TimedEvents
• StateEvents

همین بخش جایی است که برنامه آبیاری و برنامه کودهی به شبیه‌سازی تزریق می‌شود.

ورودی‌ها از کجا می‌آیند؟

آب‌وهوا

منبع اصلی:

• جدول WeatherForecast

مسیر تولید:

• با farm_uuid مزرعه پیدا می‌شود
• از center_location مزرعه، forecastها خوانده می‌شوند
• معمولاً تا 14 روز آینده برداشته می‌شوند
• داده‌های precipitation و et0 که در دیتابیس به mm/day هستند، برای PCSE به cm/day تبدیل می‌شوند

فیلدهایی که از forecast استفاده می‌شوند:

• forecast_date → DAY
• temperature_min → TMIN
• temperature_max یا temperature_mean → TMAX
• humidity_mean → VAP
• wind_speed_max → WIND
• precipitation → RAIN
• et0 → E0, ES0, ET0

اگر کاربر خودش weather را مستقیم بدهد، همان ورودی مستقیم استفاده می‌شود.

خاک و وضعیت سایت

منبع اصلی:

• جدول SensorData
• رابطه center_location.depths
• بخشی از sensor_payload

نحوه ساخت:

• از لایه سطحی خاک (top_depth) پارامترهایی مثل wv0033, wv1500, porosity خوانده می‌شوند
• از روی آن‌ها SMFCF, SMW, SM0 ساخته می‌شود
• از sensor_payload، شاخص‌هایی مثل soil_moisture, nitrogen, phosphorus, potassium, soil_ph, electrical_conductivity استخراج می‌شود
• سپس از این‌ها soil و site_parameters نهایی ساخته می‌شود

پارامترهای محصول

منبع اصلی:

• مدل Plant

اولویت تأمین:

1. simulation profile داخل یکی از این profileها:
   • growth_profile.simulation
   • irrigation_profile.simulation
   • health_profile.simulation
2. اگر profile آماده وجود نداشته باشد، پارامترهای پیش‌فرض از روی اطلاعات رشد گیاه ساخته می‌شوند

تقویم زراعی agromanagement

منبع اصلی:

• اگر در simulation profile گیاه موجود باشد، از همان استفاده می‌شود
• وگرنه به‌صورت پیش‌فرض از بازه زمانی آب‌وهوای موجود ساخته می‌شود

ساختار پیش‌فرض:

• crop_start_date از اولین روز forecast
• crop_end_date از آخرین روز forecast یا کمی بعد از آن
• TimedEvents و StateEvents به‌صورت اولیه خالی هستند

1) APIهای مستقیم و قطعی مبتنی بر PCSE

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

• کاربرد: اجرای شبیه‌سازی رشد گیاه.
• نقش PCSE: هسته اصلی این API اجرای مدل شبیه‌سازی PCSE/WOFOST است.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• ورودی‌ها:
  • آب‌وهوا: از WeatherForecast یا ورودی مستقیم weather
  • خاک: از SensorData و center_location.depths
  • crop parameters: از Plant و simulation profile یا default
  • agromanagement: از simulation profile یا default
• نوع استفاده: مستقیم.

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

• کاربرد: دریافت وضعیت و نتیجه شبیه‌سازی رشد.
• نقش PCSE: نتیجه‌ای که برمی‌گرداند خروجی همان شبیه‌سازی مبتنی بر PCSE است.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• نوع استفاده: مستقیم.

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

• کاربرد: تولید chart وضعیت فعلی مزرعه.
• نقش PCSE: داده‌های chart مثل LAI، TAGP، TWSO، SM و daily_output از شبیه‌سازی PCSE ساخته می‌شوند.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• ورودی‌ها:
  • farm_uuid
  • آب‌وهوا از WeatherForecast
  • خاک/سایت از SensorData و داده‌های خاک location
  • پارامتر گیاه از Plant
• نوع استفاده: مستقیم.

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

• کاربرد: پیش‌بینی عملکرد مزرعه.
• نقش PCSE: عملکرد پیش‌بینی‌شده از خروجی شبیه‌سازی رشد/خروجی‌های PCSE استخراج می‌شود.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• ورودی‌ها: همان ورودی‌های current-farm-chart
• نوع استفاده: مستقیم.

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

• کاربرد: پیش‌بینی زمان تقریبی برداشت.
• نقش PCSE: با استفاده از daily_output، DVS و سایر خروجی‌های شبیه‌سازی، زمان رسیدن به برداشت برآورد می‌شود.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• ورودی‌ها: همان ورودی‌های شبیه‌سازی رشد مزرعه
• نوع استفاده: مستقیم.

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

• کاربرد: خلاصه عملکرد و برداشت.
• نقش PCSE: چند بخش این API مثل yield_prediction، harvest_prediction_card و yield_prediction_chart از خروجی‌های شبیه‌سازی PCSE تغذیه می‌شوند.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• ورودی‌ها:
  • خروجی yield_prediction
  • خروجی harvest_prediction
  • خروجی current-farm-chart
  • همگی در نهایت متکی به همان ورودی‌های farm/weather/soil/plant هستند
• نوع استفاده: مستقیم/ترکیبی.

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

• کاربرد: محاسبه شاخص تنش آبی مزرعه.
• نقش PCSE: این API از شبیه‌سازی crop_simulation استفاده می‌کند و شاخص تنش آبی را با تکیه بر خروجی‌هایی مثل SM، DVS، ET0 و RAIN می‌سازد.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• ورودی‌ها:
  • آب‌وهوا از WeatherForecast
  • خاک و رطوبت خاک از SensorData
  • پارامتر گیاه از Plant
• نوع استفاده: مستقیم، ولی شاخص نهایی یک فرمول داخلی روی خروجی شبیه‌سازی است.

2) APIهایی که بخشی از تحلیلشان ممکن است با PCSE انجام شود

8. POST /api/irrigation/recommend/

• کاربرد: تولید توصیه آبیاری.
• نقش PCSE: در صورت موجود بودن simulation profile، داده مزرعه و forecast مناسب، optimizer ابتدا سناریوهای آبیاری را با PCSE ارزیابی می‌کند.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• برنامه آبیاری از کجا می‌آید؟
  • ابتدا در خود سیستم چند strategy ساخته می‌شود
  • بر اساس daily_water_needs و تعداد eventها، برای هر سناریو irrigation_events ساخته می‌شود
  • این eventها به شکل TimedEvents با سیگنال irrigate وارد agromanagement می‌شوند
• آب‌وهوا از کجا می‌آید؟
  • از forecastهای جدول WeatherForecast
• سایر ورودی‌ها از کجا می‌آیند؟
  • خاک و رطوبت و مواد غذایی: از SensorData
  • گیاه و simulation profile: از Plant
• نکته: اگر شرایط کافی نباشد، به مسیر heuristic برمی‌گردد.
• نوع استفاده: مشروط/جزئی.

9. POST /api/fertilization/recommend/

• کاربرد: تولید توصیه کودهی.
• نقش PCSE: در صورت موجود بودن simulation profile و forecast، سناریوهای کودهی با PCSE شبیه‌سازی و امتیازدهی می‌شوند.
• مدل PCSE: Wofost81_NWLP_CWB_CNB
• برنامه کودهی از کجا می‌آید؟
  • optimizer چند سناریوی کودهی می‌سازد
  • برای هر سناریو event کودهی به شکل TimedEvents
  • با سیگنال apply_n
  • و payload شامل N_amount و N_recovery
  • وارد agromanagement می‌شود
• آب‌وهوا از کجا می‌آید؟
  • از forecastهای جدول WeatherForecast
• سایر ورودی‌ها از کجا می‌آیند؟
  • خاک و وضعیت عناصر از SensorData
  • پروفایل گیاه از Plant
• نکته: اگر PCSE یا داده کافی در دسترس نباشد، fallback heuristic استفاده می‌شود.
• نوع استفاده: مشروط/جزئی.

3) APIهایی که از PCSE استفاده نمی‌کنند

این endpointها در همین حوزه هستند اما خودشان تحلیل مبتنی بر PCSE انجام نمی‌دهند:

• POST /api/irrigation/plan-from-text/
• POST /api/fertilization/plan-from-text/

این دو بیشتر parser متن آزاد هستند و برنامه را از متن به JSON ساختاریافته تبدیل می‌کنند.

جمع‌بندی کوتاه

اگر بخواهیم فقط APIهایی را نام ببریم که واقعاً تحلیل یا شبیه‌سازی وابسته به PCSE دارند، مهم‌ترین‌ها این‌ها هستند:

• 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/
• POST /api/irrigation/recommend/ (مشروط)
• POST /api/fertilization/recommend/ (مشروط)

جمع‌بندی فنی خیلی کوتاه

• مدل اصلی PCSE در این پروژه: Wofost81_NWLP_CWB_CNB
• آب‌وهوا عمدتاً از WeatherForecast می‌آید
• خاک و رطوبت و بخشی از وضعیت تغذیه از SensorData و داده‌های خاک location می‌آید
• پارامترهای گیاه و setup شبیه‌سازی از Plant و simulation profile می‌آید
• برنامه آبیاری و کودهی در optimizer ساخته می‌شوند و از طریق TimedEvents داخل agromanagement به PCSE تزریق می‌شوند