UPDATE

2026-05-02 14:03:48 +03:30
parent f704e1188c
commit ef593153ba
14 changed files with 1286 additions and 18 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` تزریق می‌شوند
@@ -0,0 +1,743 @@
+# مستند کامل 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های این سند می‌تواند ارسال شود:
+
+```json
+{
+  "events": [
+    {
+      "date": "2026-04-25",
+      "amount": 2.5,
+      "efficiency": 0.8
+    }
+  ]
+}
+```
+
+### توضیح فیلدها
+
+- `events`: آرایه‌ای از رویدادهای آبیاری
+- `date`: تاریخ اجرای آبیاری
+- `amount`: مقدار آبیاری برای event
+- `efficiency`: راندمان آبیاری، اختیاری
+
+### رفتار در PCSE
+
+این داده‌ها به `TimedEvents` با سیگنال `irrigate` تبدیل می‌شوند.
+
+---
+
+## فرمت مشترک `fertilization_recommendation`
+
+```json
+{
+  "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`.
+
+### ورودی
+
+```json
+{
+  "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` باشد
+
+### پاسخ موفق
+
+```json
+{
+  "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`: اندازه صفحه
+
+### پاسخ موفق
+
+```json
+{
+  "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 وضعیت فعلی مزرعه بر اساس شبیه‌سازی.
+
+### ورودی
+
+```json
+{
+  "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`: برنامه کودهی
+
+### پاسخ موفق
+
+```json
+{
+  "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/`
+
+### کاربرد
+
+تبدیل خروجی شبیه‌سازی به پیش‌بینی عملکرد.
+
+### ورودی
+
+```json
+{
+  "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
+      }
+    ]
+  }
+}
+```
+
+### پاسخ موفق
+
+```json
+{
+  "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/`
+
+### کاربرد
+
+پیش‌بینی زمان تقریبی برداشت.
+
+### ورودی
+
+```json
+{
+  "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
+      }
+    ]
+  }
+}
+```
+
+### پاسخ موفق
+
+```json
+{
+  "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 برنامه کودهی
+
+### نمونه درخواست
+
+```text
+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}]}
+```
+
+### پاسخ موفق
+
+```json
+{
+  "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/`
+
+### کاربرد
+
+محاسبه شاخص تنش آبی با استفاده از خروجی شبیه‌سازی.
+
+### ورودی
+
+```json
+{
+  "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`: برنامه کودهی
+
+### پاسخ موفق
+
+```json
+{
+  "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
+
+وقتی ورودی نامعتبر باشد:
+
+```json
+{
+  "code": 400,
+  "msg": "داده نامعتبر.",
+  "data": {
+    "farm_uuid": ["farm_uuid الزامی است."]
+  }
+}
+```
+
+### خطای 404
+
+بیشتر در `water-stress` وقتی مزرعه پیدا نشود:
+
+```json
+{
+  "code": 404,
+  "msg": "Farm not found.",
+  "data": null
+}
+```
+
+### خطای 500
+
+وقتی اجرای شبیه‌سازی یا ساخت response شکست بخورد:
+
+```json
+{
+  "code": 500,
+  "msg": "خطا در پیش بینی عملکرد: ...",
+  "data": null
+}
+```
+
+---
+
+## جمع‌بندی
+
+APIهایی که در این سند توضیح داده شدند، حالا می‌توانند از ورودی کاربر:
+
+- `irrigation_recommendation`
+- `fertilization_recommendation`
+
+را دریافت کنند و آن‌ها را به لایه شبیه‌سازی `PCSE` پاس بدهند. این یعنی خروجی‌های:
+
+- رشد
+- chart مزرعه
+- پیش‌بینی عملکرد
+- پیش‌بینی برداشت
+- خلاصه Yield/Harvest
+- شاخص تنش آبی
+
+می‌توانند تحت تأثیر برنامه آبیاری و برنامه کودهی ارسالی کاربر قرار بگیرند.