Ai/docs/updated_pcse_apis_reference.md

# مستند کامل 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
- شاخص تنش آبی

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