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` تزریق می‌شوند