UPDATE

2026-05-11 03:27:21 +03:30
parent cf7cbb937c
commit d0e68a1a56
854 changed files with 102985 additions and 76 deletions
@@ -0,0 +1,290 @@
+# لیست 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` تزریق می‌شوند