Frontend/SMART_IRRIGATION_BACKEND_INTEGRATION.md

# Smart Irrigation Backend Integration

این فایل مشخص می کند صفحه
`src/views/dashboards/farm/smartIrrigation/SmartIrrigationRecommendation.tsx`
برای کار کامل با بک‌اند دقیقا چه داده هایی لازم دارد و از کدام endpointها باید استفاده کند.

هدف این سند:
- حذف داده های ماک
- مشخص شدن contract حداقلی بین فرانت و بک‌اند
- معلوم شدن این که هر بخش UI از کدام فیلد تغذیه می شود

---

## 1) دریافت محصولات انتخاب شده مزرعه

### Endpoint

`GET /api/plants/selected/?farm_uuid=<uuid>`

### کاربرد در UI

برای این بخش ها استفاده می شود:
- نمایش لیست محصول ها برای انتخاب
- گرفتن stageهای هر محصول
- انتخاب مقدار اولیه `selectedCrop`
- انتخاب مقدار اولیه `growthStage`

### فیلدهای لازم از response

```json
{
  "data": [
    {
      "name": "گوجه فرنگی",
      "icon": "tabler-carrot",
      "growth_stages": ["رویشی", "گلدهی", "میوه دهی"]
    }
  ]
}
```

### فیلدهای مصرفی

- `data[].name`
  - برای `crop.id`
  - برای `crop.name`
- `data[].icon`
  - برای آیکن کارت محصول
- `data[].growth_stages[]`
  - برای لیست stageها

---

## 2) تولید recommendation آبیاری

### Endpoint

`POST /api/irrigation/recommend/`

### Request payload مورد نیاز فرانت

```json
{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "plant_name": "گوجه فرنگی",
  "growth_stage": "گلدهی"
}
```

### نکته مهم

در UI فعلی برای recommendation فقط این سه فیلد برای request لازم هستند:
- `farm_uuid`
- `plant_name`
- `growth_stage`

---

## 3) فیلدهای لازم از response recommendation

فرانت در وضعیت فعلی فقط این بخش ها را برای نمایش نتیجه لازم دارد.

### ساختار کلی مورد نیاز

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "recommendation_uuid": "uuid",
    "crop_id": "گوجه فرنگی",
    "plant_name": "گوجه فرنگی",
    "growth_stage": "گلدهی",
    "irrigation_method_name": "آبیاری قطره ای",
    "status": "pending_confirmation",
    "status_label": "منتظر تایید",
    "plan": {},
    "water_balance": {},
    "timeline": [],
    "sections": []
  }
}
```

---

## 4) مصرف دقیق هر فیلد در UI recommendation

## 4.1) هدر صفحه نتیجه

برای نوار بالای صفحه نتیجه:

- `data.plant_name`
- `data.growth_stage`

کاربرد:
- ساخت `resultContext`
- نمایش عنوان بالای صفحه بعد از تولید recommendation

---

## 4.2) کارت Instruction Details

این کارت از این فیلدها تغذیه می شود:

### از `plan`
- `plan.frequencyPerWeek`
- `plan.durationMinutes`
- `plan.bestTimeOfDay`
- `plan.moistureLevel`

### از `water_balance`
- `water_balance.daily[].gross_irrigation_mm`

### نمونه حداقلی

```json
{
  "plan": {
    "frequencyPerWeek": 4,
    "durationMinutes": 38,
    "bestTimeOfDay": "05:30 تا 08:00 صبح",
    "moistureLevel": 72,
    "warning": "در ساعات گرم روز آبیاری انجام نشود"
  },
  "water_balance": {
    "daily": [
      {
        "gross_irrigation_mm": 17
      }
    ]
  }
}
```

### نکته

در UI فعلی مقدار `Water Amount` با تکیه بر:
- `water_balance.daily[0].gross_irrigation_mm`
- و مساحت انتخابی در فرانت
محاسبه می شود.

اگر بخواهید محاسبه دقیق تر و backend-driven شود، بهتر است بک‌اند یکی از این دو را هم بدهد:
- `recommended_liters_per_hectare`
- یا `recommended_total_liters`

اما فعلا UI بدون اینها هم کار می کند.

---

## 4.3) Gauge / Circular Indicator

برای gauge فقط این دو مقدار لازم است:

- `plan.moistureLevel`
- `water_balance.daily` لازم نیست

و اگر بخواهید target هم از بک‌اند بیاید، بهتر است این فیلد اضافه شود:

- `target_moisture`

### وضعیت فعلی

در نسخه فعلی فرانت هنوز یک target mock-style استفاده می کند.
برای اتصال کامل بهتر است بک‌اند این فیلد را هم داخل `plan` برگرداند:

```json
{
  "plan": {
    "moistureLevel": 72,
    "targetMoisture": 78
  }
}
```

### پیشنهاد

اگر ممکن است این فیلد به response اضافه شود:
- `plan.targetMoisture`

---

## 4.4) تراز آب و نیاز روزانه

این بخش مستقیما از `water_balance` استفاده می کند.

### فیلدهای لازم

```json
{
  "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"
      }
    ]
  }
}
```

### فیلدهای مصرفی

#### از `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 اصلی مستقیم رندر نمی شود، ولی برای آینده مفید است

---

## 4.5) Stepper مراحل و دستورالعمل اجرا

برای این بخش فقط `timeline` لازم است.

### ساختار لازم

```json
{
  "timeline": [
    {
      "step_number": 1,
      "title": "بررسی فشار",
      "description": "فشار ابتدا و انتهای لاین کنترل شود"
    }
  ]
}
```

### فیلدهای مصرفی

- `timeline[].step_number`
- `timeline[].title`
- `timeline[].description`

### نکته

در UI فعلی این فیلدها کافی هستند.
فیلدهایی مثل `time_label` یا `state` فعلا لازم نیستند.

---

## 4.6) هشدارها و نکات

این بخش از `plan.warning` و `sections` استفاده می کند.

### فیلدهای لازم

```json
{
  "plan": {
    "warning": "در ساعات گرم روز آبیاری انجام نشود"
  },
  "sections": [
    {
      "title": "هشدار تبخیر بالا",
      "icon": "tabler-alert-triangle",
      "type": "warning",
      "content": "در ساعات گرم روز آبیاری انجام نشود"
    },
    {
      "title": "نکته بهره وری",
      "icon": "tabler-bulb",
      "type": "tip",
      "content": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
    }
  ]
}
```

### مصرف در UI

#### هشدارها
- `plan.warning`
- `sections[].type === "warning"`
- `sections[].content`

#### نکات پایین صفحه
- `sections[].type === "tip"`
- `sections[].title`
- `sections[].icon`
- `sections[].content`

---

## 5) حداقل response پیشنهادی برای recommendation

اگر هدف فقط راه افتادن UI فعلی recommendation باشد، این حداقل پاسخ کافی است:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "recommendation_uuid": "8a4c22d8-3f75-4aef-8e04-b40f6b4a2d11",
    "crop_id": "گوجه فرنگی",
    "plant_name": "گوجه فرنگی",
    "growth_stage": "گلدهی",
    "irrigation_method_name": "آبیاری قطره ای",
    "status": "pending_confirmation",
    "status_label": "منتظر تایید",
    "plan": {
      "frequencyPerWeek": 4,
      "durationMinutes": 38,
      "bestTimeOfDay": "05:30 تا 08:00 صبح",
      "moistureLevel": 72,
      "targetMoisture": 78,
      "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": "شست وشوی فیلترها به یکنواختی آبیاری کمک می کند"
      }
    ]
  }
}
```

---

## 6) history recommendationهای آبیاری

### Endpoint

`GET /api/irrigation/recommendations/?farm_uuid=<uuid>&page=1&page_size=10`

### کاربرد در UI

برای جدول history پایین فرم استفاده می شود.

### فیلدهای لازم هر آیتم

```json
{
  "recommendation_uuid": "uuid",
  "plant_name": "گوجه فرنگی",
  "growth_stage": "گلدهی",
  "irrigation_method_name": "آبیاری قطره ای",
  "status": "pending_confirmation",
  "status_label": "منتظر تایید",
  "requested_at": "2025-02-12T09:30:00Z"
}
```

### نکته مهم برای فرانت فعلی

در کد فعلی جدول history این فیلد را به عنوان ستون روش آبیاری می خواهد:

- `irrigation_method`

اما طبق contract بک‌اند، فیلد موجود این است:

- `irrigation_method_name`

### نتیجه

برای اتصال کامل یکی از این دو کار باید انجام شود:

1. یا فرانت `irrigation_method_name` را بخواند
2. یا بک‌اند علاوه بر آن، فیلد `irrigation_method` هم برگرداند

پیشنهاد بهتر:
- فرانت را با `irrigation_method_name` align کنید

### pagination لازم

```json
{
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_pages": 1,
    "total_items": 1,
    "has_next": false,
    "has_previous": false,
    "next": null,
    "previous": null
  }
}
```

---

## 7) جزئیات یک recommendation

### Endpoint

`GET /api/irrigation/recommendations/{recommendation_uuid}/`

### کاربرد در UI

وقتی کاربر از جدول history روی آیکن گزارش کلیک می کند، این endpoint باید صدا زده شود.

### ساختار لازم

خروجی این endpoint باید همان shape endpoint recommendation اصلی را برگرداند؛ یعنی:

- `recommendation_uuid`
- `plant_name`
- `growth_stage`
- `irrigation_method_name`
- `status`
- `status_label`
- `plan`
- `water_balance`
- `timeline`
- `sections`

---

## 8) فیلدهایی که فعلا در UI لازم نیستند

این فیلدها در نسخه فعلی صفحه ضروری نیستند:

- `raw_response`
- `crop_id` (اگر `plant_name` وجود داشته باشد)
- `sensor_uuid`
- `status` در خود recommendation result page
- `generated_at`
- `final_verdict`
- `recommendation_title`
- `recommendation_subtitle`
- `primary_method`
- `usage_summary`
- `alternative_plans`
- `sections[].type = schedule`
- `sections[].type = method`

---

## 9) جمع بندی نهایی

برای این صفحه اگر بخواهیم فقط داده های ضروری از بک‌اند بگیریم، این endpointها کافی هستند:

1. `GET /api/plants/selected/`
2. `POST /api/irrigation/recommend/`
3. `GET /api/irrigation/recommendations/`
4. `GET /api/irrigation/recommendations/{recommendation_uuid}/`

و برای recommendation page حداقل این بخش های response باید حتما وجود داشته باشند:

- `plant_name`
- `growth_stage`
- `plan`
- `water_balance`
- `timeline`
- `sections`

و برای history:

- `recommendation_uuid`
- `plant_name`
- `growth_stage`
- `irrigation_method_name`
- `status`
- `status_label`
- `requested_at`
- `pagination`