UPDATE

2026-04-28 19:00:11 +03:30
parent ffac636648
commit fa832e14b5
9 changed files with 1899 additions and 755 deletions
@@ -0,0 +1,216 @@
+# Backend data needed only for irrigation recommendation
+
+این فایل فقط اطلاعاتی را لیست می کند که فرانت برای بخش `recommendation` در صفحه
+`src/views/dashboards/farm/smartIrrigation/SmartIrrigationRecommendation.tsx`
+از بک اند نیاز دارد.
+
+این سند شامل داده های `config`، `history`، یا اکشن های جانبی نیست؛ فقط داده های لازم برای
+ساخت نتیجه توصیه آبیاری را پوشش می دهد.
+
+## Request payload
+
+فرانت برای گرفتن توصیه فقط به این فیلدها نیاز دارد:
+
+```json
+{
+  "farm_uuid": "string",
+  "plant_name": "string",
+  "growth_stage": "string"
+}
+```
+
+## Response fields used by UI
+
+فرانت در وضعیت فعلی فقط از این فیلدها در پاسخ recommendation استفاده می کند:
+
+```json
+{
+  "plan": {
+    "frequencyPerWeek": 4,
+    "durationMinutes": 38,
+    "bestTimeOfDay": "05:30 تا 08:00 صبح",
+    "moistureLevel": 72,
+    "warning": "string"
+  },
+  "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": "string",
+      "description": "string"
+    }
+  ],
+  "sections": [
+    {
+      "title": "string",
+      "icon": "string",
+      "type": "warning | tip",
+      "content": "string"
+    }
+  ]
+}
+```
+
+## Field-by-field usage
+
+### 1) `plan`
+
+برای نمایش خلاصه نسخه و هشدارها:
+
+- `plan.frequencyPerWeek`
+  - نمایش تعداد نوبت آبیاری
+- `plan.durationMinutes`
+  - نمایش مدت هر نوبت
+- `plan.bestTimeOfDay`
+  - نمایش بهترین بازه زمانی آبیاری
+- `plan.moistureLevel`
+  - نمایش مقدار رطوبت فعلی در gauge
+- `plan.warning`
+  - نمایش هشدار اصلی در بخش warnings
+
+### 2) `water_balance`
+
+برای نمایش تراز آب و داده های روزانه:
+
+- `water_balance.daily[]`
+  - `forecast_date`
+  - `gross_irrigation_mm`
+  - `irrigation_timing`
+  - `et0_mm`
+  - `etc_mm`
+  - `effective_rainfall_mm`
+- `water_balance.crop_profile`
+  - `kc_initial`
+  - `kc_mid`
+  - `kc_end`
+- `water_balance.active_kc`
+  - فعلا در UI فعلی استفاده مستقیم ندارد، اما بهتر است بماند اگر قرار است بعدا نمایش داده شود
+
+### 3) `timeline`
+
+برای نمایش Stepper مراحل اجرا:
+
+- `timeline[].step_number`
+- `timeline[].title`
+- `timeline[].description`
+
+نکته:
+- در UI فعلی فقط همین سه فیلد لازم است.
+- `time_label` و `state` قبلا در ماک استفاده شده بودند ولی در نسخه فعلی UI دیگر مصرف نمی شوند.
+
+### 4) `sections`
+
+برای هشدارها و نکات تکمیلی:
+
+- `sections[].type`
+  - فقط این مقادیر فعلا مصرف می شوند:
+    - `warning`
+    - `tip`
+- `sections[].title`
+  - برای کارت tip
+- `sections[].icon`
+  - برای کارت tip
+- `sections[].content`
+  - برای متن warning و tip
+
+## Minimum response required
+
+اگر بخواهیم حداقل پاسخ قابل استفاده برای UI فعلی را تعریف کنیم، این ساختار کافی است:
+
+```json
+{
+  "plan": {
+    "frequencyPerWeek": 4,
+    "durationMinutes": 38,
+    "bestTimeOfDay": "05:30 تا 08:00 صبح",
+    "moistureLevel": 72,
+    "warning": "در ساعات گرم روز آبیاری انجام نشود"
+  },
+  "water_balance": {
+    "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": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
+    }
+  ]
+}
+```
+
+## Fields currently not required by this UI
+
+فیلدهای زیر در نسخه فعلی صفحه برای نمایش recommendation لازم نیستند:
+
+- `raw_response`
+- `status`
+- `generated_at`
+- `recommendation_title`
+- `recommendation_subtitle`
+- `final_verdict`
+- `primary_method`
+- `usage_summary`
+- `alternative_plans`
+- `sections[].type = schedule`
+- `sections[].type = method`
+
+## Practical backend recommendation
+
+اگر هدف فقط راه اندازی همین UI فعلی است، بهتر است endpoint recommendation حداقل این 4 بخش را برگرداند:
+
+- `plan`
+- `water_balance`
+- `timeline`
+- `sections`
+
+و در `sections` فعلا حداقل این دو نوع را پشتیبانی کند:
+
+- `warning`
+- `tip`
+