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,363 @@
+# Irrigation Recommendation API Fields
+
+این فایل فقط فیلدهای API مربوط به `POST /api/irrigation/recommend/` را توضیح می‌دهد.
+
+## Endpoint
+
+`POST /api/irrigation/recommend/`
+
+## کاربرد
+
+این endpoint برای تولید recommendation آبیاری استفاده می‌شود و خروجی آن با UI فعلی صفحه
+`src/views/dashboards/farm/smartIrrigation/SmartIrrigationRecommendation.tsx`
+هماهنگ شده است.
+
+## ساختار کلی پاسخ
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "plan": {},
+    "water_balance": {},
+    "timeline": [],
+    "sections": []
+  }
+}
+```
+
+## Request
+
+### حداقل payload پیشنهادی
+
+```json
+{
+  "farm_uuid": "11111111-1111-1111-1111-111111111111",
+  "plant_name": "گوجه‌فرنگی",
+  "growth_stage": "گلدهی",
+  "irrigation_type": "آبیاری قطره‌ای"
+}
+```
+
+### فیلدهای Request
+
+### `farm_uuid`
+- نوع: `string`
+- اجباری: بله
+- توضیح: شناسه یکتای مزرعه.
+
+### `sensor_uuid`
+- نوع: `string`
+- اجباری: خیر
+- توضیح: نام قدیمی برای `farm_uuid`. اگر `farm_uuid` ارسال نشده باشد، این مقدار به جای آن استفاده می‌شود.
+
+### `plant_name`
+- نوع: `string`
+- اجباری: خیر
+- توضیح: نام گیاه هدف برای تولید توصیه. اگر ارسال نشود، سیستم در صورت امکان گیاه ثبت‌شده روی مزرعه را استفاده می‌کند.
+
+### `growth_stage`
+- نوع: `string`
+- اجباری: خیر
+- توضیح: مرحله رشد گیاه مثل `رویشی`، `گلدهی` یا `میوه‌دهی`.
+
+### `irrigation_type`
+- نوع: `string`
+- اجباری: خیر
+- توضیح: نوع یا نام روش آبیاری مورد نظر فرانت. این فیلد برای UI فعلی پیشنهاد می‌شود.
+
+### `irrigation_method_name`
+- نوع: `string`
+- اجباری: خیر
+- توضیح: نام روش آبیاری. این فیلد با `irrigation_type` هم‌ارز است و در بک‌اند به همان ورودی نهایی نرمال می‌شود.
+
+
+## Response
+
+## فیلدهای لایه اول Response
+
+### `code`
+- نوع: `number`
+- توضیح: کد وضعیت پاسخ در قالب استاندارد API پروژه.
+
+### `msg`
+- نوع: `string`
+- توضیح: پیام وضعیت پاسخ. در حالت موفق معمولاً `success` است.
+
+### `data`
+- نوع: `object`
+- توضیح: بدنه اصلی recommendation آبیاری.
+
+## فیلدهای `data`
+
+### `plan`
+- نوع: `object`
+- توضیح: خلاصه اصلی recommendation برای نمایش در کارت بالای UI.
+
+### `water_balance`
+- نوع: `object`
+- توضیح: تراز آب و خروجی محاسبات روزانه FAO-56.
+
+### `timeline`
+- نوع: `array`
+- توضیح: مراحل اجرایی recommendation برای Stepper.
+
+### `sections`
+- نوع: `array`
+- توضیح: نکات تکمیلی و هشدارها. در UI فعلی فقط `warning` و `tip` مصرف می‌شوند.
+
+## فیلدهای `data.plan`
+
+```json
+{
+  "frequencyPerWeek": 4,
+  "durationMinutes": 38,
+  "bestTimeOfDay": "05:30 تا 08:00 صبح",
+  "moistureLevel": 72,
+  "warning": "در ساعات گرم روز آبیاری انجام نشود"
+}
+```
+
+### `frequencyPerWeek`
+- نوع: `number`
+- توضیح: تعداد نوبت آبیاری در هفته.
+
+### `durationMinutes`
+- نوع: `number`
+- توضیح: مدت هر نوبت آبیاری بر حسب دقیقه.
+
+### `bestTimeOfDay`
+- نوع: `string`
+- توضیح: بهترین بازه زمانی اجرای آبیاری.
+
+### `moistureLevel`
+- نوع: `number`
+- توضیح: سطح رطوبت فعلی یا هدف خاک برای نمایش در gauge.
+
+### `warning`
+- نوع: `string`
+- توضیح: هشدار اصلی recommendation.
+
+## فیلدهای `data.water_balance`
+
+```json
+{
+  "active_kc": 0.93,
+  "crop_profile": {
+    "kc_initial": 0.55,
+    "kc_mid": 1.05,
+    "kc_end": 0.78
+  },
+  "daily": [
+    {
+      "forecast_date": "2025-02-12",
+      "et0_mm": 5.4,
+      "etc_mm": 4.9,
+      "effective_rainfall_mm": 0,
+      "gross_irrigation_mm": 17,
+      "irrigation_timing": "05:30 - 07:00"
+    }
+  ]
+}
+```
+
+### `active_kc`
+- نوع: `number`
+- توضیح: ضریب Kc فعال برای مرحله رشد فعلی.
+
+### `crop_profile`
+- نوع: `object`
+- توضیح: پروفایل Kc گیاه در مراحل مختلف.
+
+### `daily`
+- نوع: `array`
+- توضیح: داده‌های روزانه مورد استفاده در جدول یا نمودار تراز آب.
+
+## فیلدهای `data.water_balance.crop_profile`
+
+### `kc_initial`
+- نوع: `number`
+- توضیح: Kc مرحله ابتدایی رشد.
+
+### `kc_mid`
+- نوع: `number`
+- توضیح: Kc مرحله میانی رشد.
+
+### `kc_end`
+- نوع: `number`
+- توضیح: Kc مرحله پایانی رشد.
+
+## فیلدهای هر آیتم در `data.water_balance.daily[]`
+
+### `forecast_date`
+- نوع: `string`
+- توضیح: تاریخ پیش‌بینی.
+
+### `et0_mm`
+- نوع: `number`
+- توضیح: تبخیر و تعرق مرجع روزانه.
+
+### `etc_mm`
+- نوع: `number`
+- توضیح: تبخیر و تعرق گیاه.
+
+### `effective_rainfall_mm`
+- نوع: `number`
+- توضیح: بارش مؤثر محاسبه‌شده.
+
+### `gross_irrigation_mm`
+- نوع: `number`
+- توضیح: مقدار آبیاری ناخالص پیشنهادی برای آن روز.
+
+### `irrigation_timing`
+- نوع: `string`
+- توضیح: زمان پیشنهادی اجرای آبیاری برای آن روز.
+
+## فیلدهای `data.timeline`
+
+```json
+[
+  {
+    "step_number": 1,
+    "title": "بررسی فشار",
+    "description": "فشار ابتدا و انتهای لاین کنترل شود"
+  }
+]
+```
+
+### `step_number`
+- نوع: `number`
+- توضیح: شماره مرحله.
+
+### `title`
+- نوع: `string`
+- توضیح: عنوان مرحله.
+
+### `description`
+- نوع: `string`
+- توضیح: توضیح اجرایی مرحله.
+
+## فیلدهای `data.sections`
+
+```json
+[
+  {
+    "title": "هشدار تبخیر بالا",
+    "icon": "tabler-alert-triangle",
+    "type": "warning",
+    "content": "در ساعات گرم روز آبیاری انجام نشود"
+  },
+  {
+    "title": "نکته بهره وری",
+    "icon": "tabler-bulb",
+    "type": "tip",
+    "content": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
+  }
+]
+```
+
+### `title`
+- نوع: `string`
+- توضیح: عنوان کارت.
+
+### `icon`
+- نوع: `string`
+- توضیح: نام آیکون مورد استفاده در UI.
+
+### `type`
+- نوع: `string`
+- توضیح: نوع سکشن. در UI فعلی فقط این مقادیر مصرف می‌شوند:
+  - `warning`
+  - `tip`
+
+### `content`
+- نوع: `string`
+- توضیح: متن هشدار یا نکته.
+
+## حداقل پاسخ قابل استفاده برای UI فعلی
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "plan": {
+      "frequencyPerWeek": 4,
+      "durationMinutes": 38,
+      "bestTimeOfDay": "05:30 تا 08:00 صبح",
+      "moistureLevel": 72,
+      "warning": "در ساعات گرم روز آبیاری انجام نشود"
+    },
+    "water_balance": {
+      "active_kc": 0.93,
+      "crop_profile": {
+        "kc_initial": 0.55,
+        "kc_mid": 1.05,
+        "kc_end": 0.78
+      },
+      "daily": [
+        {
+          "forecast_date": "2025-02-12",
+          "et0_mm": 5.4,
+          "etc_mm": 4.9,
+          "effective_rainfall_mm": 0,
+          "gross_irrigation_mm": 17,
+          "irrigation_timing": "05:30 - 07:00"
+        }
+      ]
+    },
+    "timeline": [
+      {
+        "step_number": 1,
+        "title": "بررسی فشار",
+        "description": "فشار ابتدا و انتهای لاین کنترل شود"
+      }
+    ],
+    "sections": [
+      {
+        "title": "هشدار تبخیر بالا",
+        "icon": "tabler-alert-triangle",
+        "type": "warning",
+        "content": "در ساعات گرم روز آبیاری انجام نشود"
+      },
+      {
+        "title": "نکته بهره وری",
+        "icon": "tabler-bulb",
+        "type": "tip",
+        "content": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
+      }
+    ]
+  }
+}
+```
+
+## فیلدهایی که فرانت فعلی لازم ندارد
+
+فیلدهای زیر برای UI فعلی recommendation لازم نیستند و نباید به عنوان dependency فرانت در نظر گرفته شوند:
+
+- `raw_response`
+- `status`
+- `generated_at`
+- `recommendation_title`
+- `recommendation_subtitle`
+- `final_verdict`
+- `primary_method`
+- `usage_summary`
+- `alternative_plans`
+- `sections[].type = schedule`
+- `sections[].type = method`
+
+## نمونه cURL
+
+```bash
+curl -s -X POST "http://localhost:8000/api/irrigation/recommend/" \
+  -H "accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "farm_uuid": "11111111-1111-1111-1111-111111111111",
+    "plant_name": "گوجه‌فرنگی",
+    "growth_stage": "گلدهی",
+    "irrigation_type": "آبیاری قطره‌ای"
+  }'
+```