sajad-dev/Ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2d1f7da89e30f1fbed28fae719f485a98f82b92a
Ai/docs/crop_simulation_api_reference.md
T

1184 lines
36 KiB
Markdown
Raw Normal View History

UPDATE
2026-04-30 00:53:47 +03:30
# Crop Simulation API Reference
این فایل توضیح کامل API های ماژول `crop_simulation` را پوشش می دهد:
- `POST /api/crop-simulation/current-farm-chart/`
- `POST /api/crop-simulation/growth/`
- `GET /api/crop-simulation/growth/{task_id}/status/`
- `POST /api/crop-simulation/harvest-prediction/`
- `GET /api/crop-simulation/yield-harvest-summary/`
- `POST /api/crop-simulation/yield-prediction/`
---
## الگوی کلی پاسخ ها
تقریبا همه endpoint ها از الگوی envelope زیر استفاده می کنند:
```json
{
"code": 200,
"msg": "success",
"data": {}
}
```
### معنی فیلدهای envelope
| فیلد | نوع | توضیح |
|---|---|---|
| `code` | integer | کد منطقی پاسخ. معمولا با HTTP status همسو است. |
| `msg` | string | پیام کوتاه پاسخ. در موفقیت معمولا `success` و در خطا متن فارسی خطا است. |
| `data` | object / null | بدنه اصلی داده. در خطاهای validation معمولا شامل جزئیات خطا است. |
### خطاهای رایج
| HTTP Status | `code` | توضیح |
|---|---|---|
| `400` | `400` | ورودی نامعتبر است؛ مثل نبودن `farm_uuid` یا ناقص بودن payload |
| `500` | `500` | اجرای سرویس یا شبیه سازی داخلی با خطا مواجه شده است |
| `202` | `202` | تسک async با موفقیت در صف قرار گرفته است |
---
## 1) POST `/api/crop-simulation/current-farm-chart/`
### کاربرد
برای ساخت chart وضعیت فعلی مزرعه با استفاده از شبیه سازی رشد.
این endpoint داده هایی مثل:
- روند روزانه رشد
- بیوماس
- وزن محصول
- شاخص سطح برگ
- رطوبت خاک
را برمی گرداند.
### درخواست
#### Body
```json
{
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"plant_name": "گوجه‌فرنگی"
}
```
### فیلدهای ورودی
| فیلد | نوع | اجباری | توضیح |
|---|---|---:|---|
| `farm_uuid` | string (UUID) | بله | شناسه یکتای مزرعه |
| `plant_name` | string | خیر | نام گیاه. اگر ارسال نشود سیستم سعی می کند گیاه پیش فرض مزرعه را تشخیص دهد |
### پاسخ موفق
```json
{
"code": 200,
"msg": "success",
"data": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"plant_name": "گوجه‌فرنگی",
"engine": "growth_projection",
"model_name": "growth_projection_v1",
"scenario_id": 12,
"simulation_warning": null,
"categories": ["2026-04-01", "2026-04-02"],
"series": [
{
"name": "تعداد برگ تخمینی",
"key": "leaf_count_estimate",
"data": [120.0, 140.0]
},
{
"name": "وزن بیوماس",
"key": "biomass_weight",
"data": [35.0, 45.0]
}
],
"summary": [
{
"title": "تعداد برگ تخمینی",
"subtitle": "وضعیت فعلی",
"amount": 140.0,
"unit": "leaf",
"avatarColor": "success",
"avatarIcon": "tabler-leaf"
}
],
"current_state": {
"date": "2026-04-02",
"leaf_count_estimate": 140.0,
"leaf_area_index": 0.0117,
"biomass_weight": 45.0,
"storage_organ_weight": 10.0,
"soil_moisture_percent": 41.2,
"development_stage": 0.35,
"gdd": 9.0
},
"metrics": {
"yield_estimate": 10.0
},
"daily_output": []
}
}
```
### توضیح کامل فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| `farm_uuid` | string / null | شناسه مزرعه |
| `plant_name` | string | نام گیاهی که شبیه سازی برای آن انجام شده |
| `engine` | string / null | موتور شبیه سازی استفاده شده |
| `model_name` | string / null | نام مدل شبیه سازی |
| `scenario_id` | integer / null | شناسه سناریو اگر در سیستم ثبت شده باشد |
| `simulation_warning` | string / null | هشدار غیر بحرانی؛ مثلا وقتی fallback استفاده شده |
| `categories` | array[string] | محور زمانی نمودار؛ معمولا تاریخ های روزانه |
| `series` | array[object] | سری های نمودار برای رندر frontend |
| `summary` | array[object] | کارت های خلاصه برای نمایش سریع وضعیت فعلی |
| `current_state` | object | وضعیت آخرین روز شبیه سازی |
| `metrics` | object | شاخص های محاسبه شده نهایی |
| `daily_output` | array[object] | خروجی روزانه خام شبیه سازی |
### ساختار `series`
هر عضو `series` معمولا این ساختار را دارد:
| فیلد | نوع | توضیح |
|---|---|---|
| `name` | string | عنوان سری برای chart |
| `key` | string | کلید فنی سری |
| `data` | array[number] | داده های عددی سری به ترتیب `categories` |
نمونه key های مهم:
- `leaf_count_estimate`
- `biomass_weight`
- `storage_organ_weight`
- `lai`
- `soil_moisture_percent`
### ساختار `summary`
هر آیتم `summary` یک KPI card است:
| فیلد | نوع | توضیح |
|---|---|---|
| `title` | string | عنوان کارت |
| `subtitle` | string | زیرعنوان |
| `amount` | number | مقدار اصلی کارت |
| `unit` | string | واحد |
| `avatarColor` | string | رنگ پیشنهادی برای UI |
| `avatarIcon` | string | آیکن پیشنهادی برای UI |
### ساختار `current_state`
| فیلد | نوع | توضیح |
|---|---|---|
| `date` | string | تاریخ آخرین رکورد |
| `leaf_count_estimate` | number | تعداد برگ تخمینی |
| `leaf_area_index` | number | شاخص سطح برگ (LAI) |
| `biomass_weight` | number | وزن بیوماس |
| `storage_organ_weight` | number | وزن اندام ذخیره ای / محصول |
| `soil_moisture_percent` | number | رطوبت خاک به درصد |
| `development_stage` | number | مرحله رشد گیاه به صورت DVS |
| `gdd` | number | درجه روز رشد همان روز |
### ساختار `daily_output`
این بخش خروجی خام شبیه سازی است و معمولا شامل فیلدهایی مثل این هاست:
- `DAY`
- `DVS`
- `LAI`
- `TAGP`
- `TWSO`
- `SM`
- `GDD`
- `TMIN`
- `TMAX`
- `RAIN`
- `ET0`
### خطاها
#### 400
وقتی `farm_uuid` ارسال نشود:
```json
{
"code": 400,
"msg": "داده نامعتبر.",
"data": {
"farm_uuid": ["This field is required."]
}
}
```
#### 500
وقتی شبیه ساز داخلی fail شود:
```json
{
"code": 500,
"msg": "خطا در اجرای chart شبیه سازی مزرعه: simulator offline",
"data": null
}
```
---
## 2) POST `/api/crop-simulation/growth/`
### کاربرد
برای شروع شبیه سازی رشد گیاه به صورت async.
این endpoint خود نتیجه نهایی را برنمی گرداند؛ فقط یک `task_id` می دهد تا بعدا از endpoint وضعیت استفاده شود.
### درخواست
#### نمونه با weather مستقیم
```json
{
"plant_name": "گوجه‌فرنگی",
"dynamic_parameters": ["DVS", "LAI", "TAGP", "TWSO", "SM"],
"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
},
"page_size": 2
}
```
#### نمونه با farm
```json
{
"plant_name": "گوجه‌فرنگی",
"dynamic_parameters": ["DVS", "LAI", "TAGP"],
"farm_uuid": "11111111-1111-1111-1111-111111111111"
}
```
### فیلدهای ورودی
| فیلد | نوع | اجباری | توضیح |
|---|---|---:|---|
| `plant_name` | string | بله | نام گیاه |
| `dynamic_parameters` | array[string] | بله | پارامترهای رشد که باید در خروجی stageها گزارش شوند |
| `farm_uuid` | string (UUID) | شرطی | اگر weather نفرستید لازم است |
| `weather` | array/object | شرطی | اگر `farm_uuid` نفرستید لازم است |
| `soil_parameters` | object | خیر | پارامترهای خاک |
| `site_parameters` | object | خیر | پارامترهای سایت / مزرعه |
| `crop_parameters` | object | خیر | پارامترهای مدل محصول |
| `agromanagement` | object / array | خیر | مدیریت زراعی |
| `page_size` | integer | خیر | اندازه صفحه stage ها، بین `1` تا `50` |
### نکته مهم validation
حداقل یکی از این دو باید وجود داشته باشد:
- `farm_uuid`
- `weather`
### پاسخ موفق
```json
{
"code": 202,
"msg": "تسک شبیه سازی رشد در صف قرار گرفت.",
"data": {
"task_id": "growth-task-1",
"status_url": "/api/crop-simulation/growth/growth-task-1/status/",
"plant_name": "گوجه‌فرنگی"
}
}
```
### توضیح فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| `task_id` | string | شناسه تسک Celery |
| `status_url` | string | آدرس endpoint وضعیت برای پیگیری نتیجه |
| `plant_name` | string | نام گیاه مربوط به این شبیه سازی |
### خطاهای رایج
#### 400
اگر نه `farm_uuid` و نه `weather` ارسال نشده باشد:
```json
{
"code": 400,
"msg": "داده نامعتبر.",
"data": {
"non_field_errors": ["یکی از farm_uuid یا weather باید ارسال شود."]
}
}
```
---
## 3) GET `/api/crop-simulation/growth/{task_id}/status/`
### کاربرد
برای گرفتن وضعیت تسک async شبیه سازی رشد.
### Query Parameters
| فیلد | نوع | اجباری | توضیح |
|---|---|---:|---|
| `page` | integer | خیر | شماره صفحه stage ها |
| `page_size` | integer | خیر | تعداد stage ها در هر صفحه، حداکثر `50` |
### حالت های پاسخ
این endpoint همیشه HTTP `200` می دهد، ولی فیلد `data.status` تعیین می کند تسک در چه وضعیتی است.
مقادیر مهم:
- `PENDING`
- `PROGRESS`
- `SUCCESS`
- `FAILURE`
---
### پاسخ در حالت `PENDING`
```json
{
"code": 200,
"msg": "success",
"data": {
"task_id": "growth-task-1",
"status": "PENDING",
"message": "تسک در صف یا یافت نشد."
}
}
```
#### توضیح
| فیلد | توضیح |
|---|---|
| `task_id` | شناسه تسک |
| `status` | وضعیت فعلی |
| `message` | پیام کمکی برای کاربر |
---
### پاسخ در حالت `PROGRESS`
```json
{
"code": 200,
"msg": "success",
"data": {
"task_id": "growth-task-1",
"status": "PROGRESS",
"progress": {
"current": 2,
"total": 3,
"message": "simulation finished"
}
}
}
```
#### توضیح
| فیلد | نوع | توضیح |
|---|---|---|
| `progress.current` | integer | مرحله فعلی پردازش |
| `progress.total` | integer | تعداد کل مراحل |
| `progress.message` | string | توضیح مرحله جاری |
---
### پاسخ در حالت `SUCCESS`
```json
{
"code": 200,
"msg": "success",
"data": {
"task_id": "growth-task-1",
"status": "SUCCESS",
"result": {
"plant_name": "گوجه‌فرنگی",
"dynamic_parameters": ["DVS"],
"engine": "growth_projection",
"model_name": "growth_projection_v1",
"scenario_id": null,
"simulation_warning": null,
"summary_metrics": {},
"stage_timeline": [
{
"order": 1,
"stage_code": "establishment",
"stage_name": "استقرار",
"start_date": "2026-04-01",
"end_date": "2026-04-02",
"days_count": 2,
"metrics": {
"DVS": {
"start": 0.1,
"end": 0.2,
"min": 0.1,
"max": 0.2,
"avg": 0.15
}
}
}
],
"stages_page": [
{
"order": 1,
"stage_code": "establishment",
"stage_name": "استقرار",
"start_date": "2026-04-01",
"end_date": "2026-04-02",
"days_count": 2,
"metrics": {
"DVS": {
"start": 0.1,
"end": 0.2,
"min": 0.1,
"max": 0.2,
"avg": 0.15
}
}
}
],
"pagination": {
"page": 1,
"page_size": 1,
"total_items": 3,
"total_pages": 3,
"has_next": true,
"has_previous": false
},
"daily_records_count": 7,
"default_page_size": 1
}
}
}
```
### توضیح کامل `result`
| فیلد | نوع | توضیح |
|---|---|---|
| `plant_name` | string | نام گیاه |
| `dynamic_parameters` | array[string] | پارامترهایی که stage metrics برایشان تولید شده |
| `engine` | string / null | موتور شبیه سازی |
| `model_name` | string / null | نام مدل |
| `scenario_id` | integer / null | شناسه سناریو |
| `simulation_warning` | string / null | هشدار غیر بحرانی |
| `summary_metrics` | object | شاخص های خلاصه |
| `stage_timeline` | array[object] | کل timeline مراحل رشد |
| `stages_page` | array[object] | فقط صفحه فعلی timeline |
| `pagination` | object | اطلاعات صفحه بندی |
| `daily_records_count` | integer | تعداد رکوردهای روزانه شبیه سازی |
| `default_page_size` | integer | اندازه صفحه پیش فرض |
### ساختار هر stage
| فیلد | نوع | توضیح |
|---|---|---|
| `order` | integer | ترتیب مرحله در timeline |
| `stage_code` | string | کد فنی مرحله رشد |
| `stage_name` | string | نام قابل نمایش مرحله |
| `start_date` | string | تاریخ شروع مرحله |
| `end_date` | string | تاریخ پایان مرحله |
| `days_count` | integer | تعداد روزهای این مرحله |
| `metrics` | object | خلاصه آماری پارامترهای درخواستی |
### ساختار `metrics` در هر stage
برای هر پارامتر مثل `DVS` یا `LAI`:
| فیلد | توضیح |
|---|---|
| `start` | مقدار ابتدای مرحله |
| `end` | مقدار پایان مرحله |
| `min` | کمترین مقدار در مرحله |
| `max` | بیشترین مقدار در مرحله |
| `avg` | میانگین مقدار در مرحله |
### ساختار `pagination`
| فیلد | نوع | توضیح |
|---|---|---|
| `page` | integer | شماره صفحه فعلی |
| `page_size` | integer | اندازه صفحه فعلی |
| `total_items` | integer | تعداد کل stage ها |
| `total_pages` | integer | تعداد کل صفحه ها |
| `has_next` | boolean | آیا صفحه بعدی وجود دارد |
| `has_previous` | boolean | آیا صفحه قبلی وجود دارد |
---
### پاسخ در حالت `FAILURE`
```json
{
"code": 200,
"msg": "success",
"data": {
"task_id": "growth-task-1",
"status": "FAILURE",
"error": "task crashed"
}
}
```
#### توضیح
| فیلد | توضیح |
|---|---|
| `error` | متن خطای نهایی تسک |
---
## 4) POST `/api/crop-simulation/harvest-prediction/`
### کاربرد
برای پیش بینی زمان تقریبی برداشت بر اساس خروجی شبیه سازی رشد و GDD.
### درخواست
```json
{
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"plant_name": "گوجه‌فرنگی"
}
```
### فیلدهای ورودی
| فیلد | نوع | اجباری | توضیح |
|---|---|---:|---|
| `farm_uuid` | string (UUID) | بله | شناسه مزرعه |
| `plant_name` | string | خیر | نام گیاه |
### پاسخ موفق
```json
{
"code": 200,
"msg": "success",
"data": {
"date": "2026-05-14",
"dateFormatted": "14 May 2026",
"daysUntil": 43,
"description": "شبيه ساز نشان مي دهد حدود 43 روز ديگر تا برداشت باقي مانده است.",
"optimalWindowStart": "2026-05-11",
"optimalWindowEnd": "2026-05-17",
"gddDetails": {
"current_cumulative_gdd": 50.0,
"required_gdd_for_maturity": 1200.0,
"remaining_gdd": 1150.0,
"simulation_engine": "growth_projection"
}
}
}
```
### توضیح کامل فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| `date` | string | تاریخ تخمینی برداشت با فرمت ISO |
| `dateFormatted` | string | همان تاریخ به فرمت human-readable |
| `daysUntil` | integer | تعداد روز باقی مانده تا برداشت |
| `description` | string | توضیح متنی قابل نمایش برای کاربر |
| `optimalWindowStart` | string | شروع بازه مناسب برداشت |
| `optimalWindowEnd` | string | پایان بازه مناسب برداشت |
| `gddDetails` | object | جزئیات محاسبات GDD و داده های پشتیبان |
### ساختار `gddDetails`
معمولا شامل این فیلدهاست:
| فیلد | نوع | توضیح |
|---|---|---|
| `current_cumulative_gdd` | number | GDD تجمعی فعلی |
| `required_gdd_for_maturity` | number | GDD مورد نیاز برای رسیدن به بلوغ |
| `remaining_gdd` | number | میزان GDD باقی مانده |
| `estimated_days_to_harvest` | integer | روزهای برآوردی تا برداشت |
| `predicted_harvest_date` | string | تاریخ برآوردی برداشت |
| `predicted_harvest_window` | object | بازه شروع/پایان مناسب برداشت |
| `daily_gdd_forecast` | array[object] | پیش بینی روزانه GDD |
| `simulation_engine` | string | موتور شبیه سازی |
| `simulation_model_name` | string | نام مدل شبیه سازی |
| `simulation_warning` | string / null | هشدار داخلی شبیه سازی |
| `scenario_id` | integer / null | شناسه سناریو |
### ساختار `daily_gdd_forecast`
هر آیتم:
| فیلد | نوع | توضیح |
|---|---|---|
| `date` | string | تاریخ |
| `gdd` | number | GDD همان روز |
| `cumulative_gdd` | number | GDD تجمعی تا آن روز |
| `development_stage` | number | DVS آن روز |
### خطاها
#### 400
```json
{
"code": 400,
"msg": "داده نامعتبر.",
"data": {
"farm_uuid": ["This field is required."]
}
}
```
#### 500
```json
{
"code": 500,
"msg": "خطا در پیش بینی زمان برداشت: harvest offline",
"data": null
}
```
---
## 5) GET `/api/crop-simulation/yield-harvest-summary/`
### کاربرد
برای برگرداندن داشبورد کامل خلاصه عملکرد و برداشت.
این endpoint ترکیبی از چند block مختلف است:
- season highlights
- yield prediction
- harvest prediction
- readiness zones
- quality bands
- harvest operations
- yield chart
این endpoint می تواند علاوه بر داده های deterministic، متن های narrative را هم اضافه کند.
### Query Parameters
| فیلد | نوع | اجباری | توضیح |
|---|---|---:|---|
| `farm_uuid` | string (UUID) | بله | شناسه یکتای مزرعه |
| `season_year` | integer | خیر | سال زراعی |
| `crop_name` | string | خیر | نام محصول |
| `include_narrative` | boolean | خیر | اگر `true` باشد متن های توضیحی RAG هم merge می شوند |
### نمونه درخواست
```http
GET /api/crop-simulation/yield-harvest-summary/?farm_uuid=11111111-1111-1111-1111-111111111111&season_year=1404&crop_name=wheat&include_narrative=true
```
### پاسخ موفق
نمونه واقعی پاسخ فعلی:
```json
{
"code": 200,
"msg": "success",
"data": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"season_highlights_card": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"crop_name": "",
"season_year": "",
"title": "Season highlights",
"subtitle": "Projected harvest in 152 days with minimal yield prediction issues due to simulation fallback.",
"total_predicted_yield": 0.0,
"yield_unit": "تن",
"target_harvest_date": "28 September 2026",
"days_until_harvest": 152,
"average_readiness": null,
"primary_quality_grade": "C",
"estimated_revenue": null,
"soil_type": "loam"
},
"yield_prediction": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"crop_name": "خیار",
"season_year": "",
"predicted_yield_tons": 0.0,
"predicted_yield_raw": 0.0,
"unit": "تن",
"source_unit": "kg/ha",
"simulation_engine": "growth_projection",
"simulation_model": "growth_projection_v1",
"scenario_id": null,
"simulation_warning": "Simulation engine failed, fallback projection used: Value for parameter CVL missing.",
"secondary_kpis_estimated": true,
"descriptionSource": "deterministic",
"farm_context": {
"soil_type": "loam",
"soil_data_provider": "mock"
},
"supporting_metrics": {
"yield_estimate": 0.0,
"biomass": 232.9052,
"max_lai": 0.1063
},
"explanation": "شبيه ساز با محدوديت داده مواجه شد؛ براورد فعلی بدون تضمین و با روش جایگزین انجام شده است."
},
"harvest_prediction_card": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"crop_name": "",
"season_year": "",
"harvest_date": "2026-09-28",
"harvest_date_formatted": "28 September 2026",
"days_until": 152,
"optimal_window_start": "2026-09-25",
"optimal_window_end": "2026-10-01",
"description": "شبيه ساز تا انتهاي forecast هنوز به رسيدگي کامل نرسيده، اما با ميانگين رشد فعلي براورد مي شود خیار حدود 152 روز ديگر به برداشت برسد.",
"descriptionSource": "deterministic",
"field_conditions": {
"soil_moisture": 42.3,
"soil_temperature": 21.4
},
"readiness_metrics": {
"current_cumulative_gdd": 0.0,
"required_gdd_for_maturity": 1200.0
}
},
"harvest_readiness_zones": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"observationDate": null,
"vegetationHealthClass": "Unavailable",
"meanNdvi": null,
"ndviTrend": null,
"averageReadiness": null,
"zones": [],
"source": "ndvi_health_service",
"summary": "خیار هنوز در مراحل اولیه رشد است، 152 روز تا برداشته شدن باقی مانده است. میانگین آمادگی موجود نیست."
},
"yield_quality_bands": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"crop_name": "",
"season_year": "",
"source": "deterministic_grading_rules",
"is_estimated": true,
"protein_content": {
"value": 9.51,
"unit": "%"
},
"moisture_percentage": {
"value": 14.03,
"unit": "%"
},
"grade_distribution": [
{"grade": "A", "share_percent": 16},
{"grade": "B", "share_percent": 41},
{"grade": "C", "share_percent": 43}
],
"primary_quality_grade": "C",
"quality_score": 59,
"summary": "Primary quality grade is C."
},
"harvest_operations_card": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"crop_name": "خیار",
"season_year": "",
"stage_label": "early_pre_harvest",
"phase_name": "vegetative",
"days_until_harvest": 152,
"current_dvs": 0.0394,
"summary": "Operations are prioritized for خیار with 152 days remaining until the predicted harvest window.",
"rules_source": "deterministic_dvs_rules",
"field_context": {
"soil_type": "loam",
"soil_moisture": 42.3,
"soil_temperature": 21.4
},
"steps": [
{
"key": "weekly_monitoring",
"title": "Run weekly crop maturity checks",
"status": "active",
"is_completed": false,
"estimated_days": 14,
"note": "Check weekly crop status for any signs of maturity changes."
}
]
},
"yield_prediction_chart": {
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"crop_name": "خیار",
"season_year": "",
"series": [
{
"name": "Predicted Yield",
"type": "line",
"data": [[1777420800000, 0.0]]
},
{
"name": "Biomass",
"type": "area",
"data": [[1777420800000, 89.392]]
}
],
"xAxis": {
"type": "datetime"
},
"meta": {
"unit": "kg/ha",
"simulation_engine": "growth_projection",
"simulation_model": "growth_projection_v1",
"scenario_id": null,
"simulation_warning": "Simulation engine failed, fallback projection used: Value for parameter CVL missing.",
"field_context": {
"soil_type": "loam",
"center_coordinates": {
"lat": 50.0,
"lon": 50.0
}
}
}
}
}
}
```
### توضیح top-level response
| فیلد | نوع | توضیح |
|---|---|---|
| `farm_uuid` | string | شناسه مزرعه |
| `season_highlights_card` | object | خلاصه مهم ترین KPI ها |
| `yield_prediction` | object | خروجی پیش بینی عملکرد |
| `harvest_prediction_card` | object | تاریخ و وضعیت برداشت |
| `harvest_readiness_zones` | object | وضعیت آمادگی برداشت در zoneها |
| `yield_quality_bands` | object | کیفیت برآوردی محصول |
| `harvest_operations_card` | object | عملیات پیشنهادی برداشت |
| `yield_prediction_chart` | object | داده نمودار عملکرد و بیوماس |
### توضیح `season_highlights_card`
| فیلد | نوع | توضیح |
|---|---|---|
| `title` | string | عنوان کارت |
| `subtitle` | string | متن توضیحی کوتاه؛ ممکن است از RAG بیاید |
| `total_predicted_yield` | number / null | عملکرد پیش بینی شده |
| `yield_unit` | string | واحد عملکرد |
| `target_harvest_date` | string / null | تاریخ هدف برداشت |
| `days_until_harvest` | integer / null | روز باقی مانده |
| `average_readiness` | number / null | میانگین آمادگی zoneها |
| `primary_quality_grade` | string / null | درجه کیفیت غالب |
| `estimated_revenue` | number / null | درآمد تخمینی اگر داده اقتصادی موجود باشد |
| `soil_type` | string / null | نوع خاک |
### توضیح `yield_prediction`
| فیلد | نوع | توضیح |
|---|---|---|
| `predicted_yield_tons` | number | عملکرد بر حسب تن |
| `predicted_yield_raw` | number | عملکرد خام معمولا بر حسب `kg/ha` |
| `unit` | string | واحد نمایشی |
| `source_unit` | string | واحد منبع |
| `simulation_engine` | string / null | موتور شبیه سازی |
| `simulation_model` | string / null | نام مدل |
| `scenario_id` | integer / null | شناسه سناریو |
| `simulation_warning` | string / null | هشدار شبیه سازی |
| `secondary_kpis_estimated` | boolean | آیا KPIهای ثانویه تخمینی هستند |
| `descriptionSource` | string | منبع توضیح؛ معمولا `deterministic` یا `rag` |
| `farm_context` | object | بخشی از context مزرعه |
| `supporting_metrics` | object | متریک های پشتیبان مثل `yield_estimate` و `biomass` |
| `explanation` | string | توضیح متنی برای کاربر |
### توضیح `harvest_prediction_card`
| فیلد | نوع | توضیح |
|---|---|---|
| `harvest_date` | string | تاریخ ISO برداشت |
| `harvest_date_formatted` | string | تاریخ قابل نمایش |
| `days_until` | integer | تعداد روز باقی مانده |
| `optimal_window_start` | string | شروع پنجره مناسب برداشت |
| `optimal_window_end` | string | پایان پنجره مناسب برداشت |
| `description` | string | توضیح متنی |
| `descriptionSource` | string | منبع متن |
| `field_conditions` | object | شرایط فعلی مزرعه مثل رطوبت و دما |
| `readiness_metrics` | object | جزئیات محاسبات readiness/GDD |
### توضیح `harvest_readiness_zones`
| فیلد | نوع | توضیح |
|---|---|---|
| `observationDate` | string / null | تاریخ مشاهده NDVI |
| `vegetationHealthClass` | string / null | کلاس سلامت پوشش گیاهی |
| `meanNdvi` | number / null | NDVI میانگین |
| `ndviTrend` | number / null | روند تغییر NDVI |
| `averageReadiness` | number / null | میانگین آمادگی zoneها |
| `zones` | array[object] | فهرست zoneها |
| `source` | string | منبع داده |
| `summary` | string | توضیح متنی خلاصه |
### ساختار هر zone
| فیلد | نوع | توضیح |
|---|---|---|
| `zoneId` | string | شناسه zone |
| `zoneLabel` | string | نام نمایشی zone |
| `gridPosition` | object / null | موقعیت zone در grid |
| `meanNdvi` | number | میانگین NDVI zone |
| `readiness` | integer | درصد آمادگی برداشت |
| `daysUntil` | integer | روزهای تخمینی تا آمادگی |
| `status` | string | وضعیت مثل `ready`, `approaching`, `monitoring`, `not_ready` |
### توضیح `yield_quality_bands`
| فیلد | نوع | توضیح |
|---|---|---|
| `source` | string | منبع محاسبه کیفیت |
| `is_estimated` | boolean | آیا مقادیر تخمینی هستند |
| `protein_content` | object | درصد پروتئین |
| `moisture_percentage` | object | درصد رطوبت |
| `grade_distribution` | array[object] | توزیع درصدی gradeها |
| `primary_quality_grade` | string | grade غالب |
| `quality_score` | number | امتیاز کیفیت |
| `summary` | string | خلاصه متنی کیفیت |
### ساختار `protein_content` و `moisture_percentage`
| فیلد | نوع | توضیح |
|---|---|---|
| `value` | number | مقدار |
| `unit` | string | واحد، معمولا `%` |
### ساختار `grade_distribution`
| فیلد | نوع | توضیح |
|---|---|---|
| `grade` | string | گرید کیفیت مثل `A`, `B`, `C` |
| `share_percent` | integer | سهم درصدی آن گرید |
### توضیح `harvest_operations_card`
| فیلد | نوع | توضیح |
|---|---|---|
| `stage_label` | string | برچسب مرحله عملیاتی |
| `phase_name` | string | نام فاز رشد |
| `days_until_harvest` | integer | روز باقی مانده تا برداشت |
| `current_dvs` | number | DVS فعلی |
| `summary` | string | خلاصه عملیاتی |
| `rules_source` | string | منبع قواعد تصمیم |
| `field_context` | object | context مزرعه |
| `steps` | array[object] | گام های عملیاتی |
### ساختار هر step
| فیلد | نوع | توضیح |
|---|---|---|
| `key` | string | کلید فنی step |
| `title` | string | عنوان عملیات |
| `status` | string | وضعیت مثل `active`, `upcoming`, `ready` |
| `is_completed` | boolean | آیا انجام شده |
| `estimated_days` | integer | روز برآوردی برای انجام / رسیدن |
| `note` | string | توضیح تکمیلی یا توصیه |
### توضیح `yield_prediction_chart`
| فیلد | نوع | توضیح |
|---|---|---|
| `series` | array[object] | سری های نمودار عملکرد و بیوماس |
| `xAxis` | object | تنظیم محور افقی |
| `meta` | object | متادیتای chart |
### ساختار `yield_prediction_chart.series`
| فیلد | نوع | توضیح |
|---|---|---|
| `name` | string | نام سری |
| `type` | string | نوع رسم مثل `line` یا `area` |
| `data` | array[[timestamp, value]] | داده های نمودار بر پایه timestamp یونیکس میلی ثانیه |
### توضیح `yield_prediction_chart.meta`
| فیلد | نوع | توضیح |
|---|---|---|
| `unit` | string | واحد داده chart |
| `simulation_engine` | string | موتور شبیه سازی |
| `simulation_model` | string | مدل |
| `scenario_id` | integer / null | شناسه سناریو |
| `simulation_warning` | string / null | هشدار شبیه سازی |
| `field_context` | object | context مزرعه مثل نوع خاک و مختصات |
### خطاها
#### 400
وقتی `farm_uuid` ارسال نشده باشد:
```json
{
"code": 400,
"msg": "داده نامعتبر.",
"data": {
"farm_uuid": ["This field is required."]
}
}
```
---
## 6) POST `/api/crop-simulation/yield-prediction/`
### کاربرد
برای تبدیل خروجی شبیه سازی رشد به پیش بینی عملکرد مزرعه.
### درخواست
```json
{
"farm_uuid": "11111111-1111-1111-1111-111111111111",
"plant_name": "گوجه‌فرنگی"
}
```
### فیلدهای ورودی
| فیلد | نوع | اجباری | توضیح |
|---|---|---:|---|
| `farm_uuid` | string (UUID) | بله | شناسه مزرعه |
| `plant_name` | string | خیر | نام گیاه |
### پاسخ موفق
```json
{
"code": 200,
"msg": "success",
"data": {
"farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
"plant_name": "گوجه‌فرنگی",
"predictedYieldTons": 5.4,
"predictedYieldRaw": 5400.0,
"unit": "تن",
"sourceUnit": "kg/ha",
"simulationEngine": "growth_projection",
"simulationModel": "growth_projection_v1",
"scenarioId": 12,
"simulationWarning": null,
"supportingMetrics": {
"yield_estimate": 5400.0
}
}
}
```
### توضیح کامل فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| `farm_uuid` | string | شناسه مزرعه |
| `plant_name` | string / null | نام گیاه |
| `predictedYieldTons` | number | عملکرد پیش بینی شده بر حسب تن |
| `predictedYieldRaw` | number | مقدار خام عملکرد |
| `unit` | string | واحد نمایشی، معمولا `تن` |
| `sourceUnit` | string | واحد محاسباتی اصلی، معمولا `kg/ha` |
| `simulationEngine` | string / null | موتور شبیه سازی |
| `simulationModel` | string / null | مدل شبیه سازی |
| `scenarioId` | integer / null | شناسه سناریو |
| `simulationWarning` | string / null | هشدار شبیه سازی |
| `supportingMetrics` | object | متریک های پشتیبان مورد استفاده برای محاسبه عملکرد |
### خطاها
#### 400
```json
{
"code": 400,
"msg": "داده نامعتبر.",
"data": {
"farm_uuid": ["This field is required."]
}
}
```
#### 500
```json
{
"code": 500,
"msg": "خطا در پیش بینی عملکرد: yield offline",
"data": null
}
```
---
## جمع بندی تفاوت endpoint ها
| Endpoint | کاربرد اصلی | sync/async |
|---|---|---|
| `POST /current-farm-chart/` | ساخت نمودار وضعیت فعلی مزرعه | sync |
| `POST /growth/` | شروع شبیه سازی رشد | async |
| `GET /growth/{task_id}/status/` | بررسی وضعیت و نتیجه شبیه سازی رشد | async status |
| `POST /harvest-prediction/` | پیش بینی زمان برداشت | sync |
| `GET /yield-harvest-summary/` | داشبورد کامل عملکرد و برداشت | sync |
| `POST /yield-prediction/` | پیش بینی عملکرد نهایی | sync |
---
## نکات مهم برای frontend
- در endpoint `growth/status` همیشه به `data.status` نگاه کنید، نه فقط HTTP status.
- در پاسخ های chart و summary ممکن است `simulation_warning` مقدار داشته باشد، حتی اگر HTTP `200` باشد.
- در `yield-harvest-summary` بعضی فیلدها ممکن است `null` باشند، مخصوصا:
- `estimated_revenue`
- `average_readiness`
- `scenario_id`
- `simulation_warning`
- در `yield_prediction_chart.series[].data` timestamp ها بر حسب **milliseconds** هستند.
- در `yield-harvest-summary` اگر `include_narrative=true` باشد، بعضی متن ها ممکن است از RAG بیایند ولی اعداد deterministic باقی می مانند.
---
## مسیر فایل
این داکیومنت در مسیر زیر ذخیره شده است:
`docs/crop_simulation_api_reference.md`
Reference in New Issue Copy Permalink