UPDATE
This commit is contained in:
@@ -0,0 +1,534 @@
|
||||
# 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`
|
||||
|
||||
Reference in New Issue
Block a user