Add error handling and new API methods for farm assistant features

- Introduced error messages in Persian for image analysis and chat functionalities in FarmAiAssistantChat and PlantPestDetection components. - Implemented a new postFormData method in ApiClient for handling file uploads. - Enhanced SmartFertilizationRecommendation and SmartIrrigationRecommendation components to fetch configuration data from the API, improving user experience with loading states and error handling. - Refactored components to utilize updated API services for better data management and responsiveness.
2026-02-25 23:39:08 +03:30
parent 83b0f88d6e
commit aad5b1c2bd
12 changed files with 778 additions and 160 deletions
@@ -0,0 +1,126 @@
+# مستندات APIهای دستیار هوشمند مزرعه (Farm AI Assistant)
+
+این سند تمام APIهای مورد نیاز برای صفحه **Farm AI Assistant** را شرح می‌دهد: ورودی‌ها، خروجی‌ها و استفاده در UI.
+
+**مسیر صفحه:** `(dashboard)/(private)/farm-ai-assistant`  
+**کامپوننت اصلی:** `FarmAiAssistantChat`
+
+---
+
+## نمای کلی
+
+دستیار هوشمند مزرعه برای کار به موارد زیر نیاز دارد:
+
+| ردیف | API | هدف |
+|------|-----|------|
+| ۱ | **ارسال پیام به دستیار (Chat/Complete)** | دریافت پاسخ ساخت‌یافته (توصیه، لیست، هشدار) بر اساس پیام کاربر و زمینه مزرعه |
+| ۲ | **دریافت زمینه مزرعه (Farm Context)** | پر کردن نوار «زمینه مزرعه» (نوع خاک، EC آب، محصول، مرحله رشد، آخرین آبیاری) |
+| ۳ | **توصیه آبیاری** | در صورت درخواست کاربر یا تصمیم دستیار برای توصیه آبیاری |
+| ۴ | **توصیه کوددهی** | در صورت درخواست کاربر یا توصیه کود |
+| ۵ | **تشخیص آفت از تصویر** | وقتی کاربر تصویر گیاه را ارسال می‌کند |
+
+---
+
+## ۱. API ارسال پیام به دستیار (Farm AI Chat)
+
+این API هسته اصلی دستیار است و در حال حاضر در فرانت با پاسخ دمو شبیه‌سازی شده است؛ باید با API واقعی جایگزین شود.
+
+### ۱.۱ مشخصات
+
+- **متد:** `POST`
+- **آدرس پیشنهادی:** `POST /api/farm-ai-assistant/chat/` یا `POST /api/farm-ai-assistant/messages/`
+- **هدف:** ارسال پیام کاربر (و در صورت وجود تصویر) به همراه زمینه مزرعه و دریافت پاسخ ساخت‌یافته دستیار.
+
+### ۱.۲ ورودی (Request Body)
+
+| فیلد | نوع | اجباری | توضیح |
+|------|-----|--------|--------|
+| `content` | string | بله | متن پیام کاربر |
+| `images` | string[] یا base64[] | خیر | آرایه آدرس تصاویر یا داده base64 (در صورت استفاده از آپلود تصویر دوربین در چت) |
+| `conversation_id` | string | خیر | شناسه مکالمه برای ادامه گفتگو؛ در اولین پیام ارسال نشود |
+| `farm_context` | object | توصیه | زمینه مزرعه برای پاسخ شخصی‌سازی‌شده (در صورت نبودن، بک‌اند می‌تواند از پیش‌فرض استفاده کند) |
+
+ساختار پیشنهادی `farm_context` (هم‌خوان با `FarmContext` در فرانت):
+
+```json
+{
+  "content": "برنامه آبیاری برای گوجه در مرحله گلدهی چطور باشد؟",
+  "farm_context": {
+    "soilType": "Loamy",
+    "waterEC": "1.2 dS/m",
+    "selectedCrop": "Tomato",
+    "growthStage": "Flowering",
+    "lastIrrigationStatus": "2 days ago"
+  }
+}
+```
+
+اگر از **تصویر** استفاده شود (دکمه دوربین در input):
+
+```json
+{
+  "content": "این برگ زرد شده، چه مشکلی داره؟",
+  "images": ["data:image/jpeg;base64,..."],
+  "farm_context": { ... }
+}
+```
+
+### ۱.۳ خروجی (Response Body)
+
+پاسخ باید شامل **بخش‌های ساخت‌یافته** (sections) باشد تا در UI به صورت کارت (توصیه، لیست، هشدار) رندر شود.
+
+**قالب پیشنهادی:**
+
+```json
+{
+  "status": "success",
+  "data": {
+    "message_id": "a-1739123456789",
+    "conversation_id": "conv-abc123",
+    "content": "",
+    "sections": [
+      {
+        "type": "recommendation",
+        "title": "Irrigation recommendation",
+        "icon": "droplet",
+        "frequency": "3 times per week",
+        "amount": "15–20 L per plant",
+        "timing": "Early morning (05:00–07:00)",
+        "expandableExplanation": "Your loamy soil holds moisture well..."
+      },
+      {
+        "type": "list",
+        "title": "Key points",
+        "icon": "leaf",
+        "items": [
+          "Avoid midday watering to reduce evaporation",
+          "Drip irrigation preferred for root zone targeting"
+        ]
+      },
+      {
+        "type": "warning",
+        "title": "Weather advisory",
+        "icon": "warning",
+        "content": "High temps forecasted next week. Consider increasing frequency."
+      }
+    ]
+  }
+}
+```
+
+**ساختار هر بخش (Section) مطابق `AIResponseSection` در فرانت:**
+
+| فیلد | نوع | اجباری | توضیح |
+|------|-----|--------|--------|
+| `type` | string | بله | یکی از: `text` \| `list` \| `recommendation` \| `warning` |
+| `title` | string | خیر | عنوان بخش |
+| `content` | string | خیر | برای `type: "text"` یا `type: "warning"` |
+| `items` | string[] | خیر | برای `type: "list"` |
+| `icon` | string | خیر | یکی از: `droplet` \| `leaf` \| `warning` \| `fertilizer` \| `calendar` |
+| `frequency` | string | خیر | فقط برای `recommendation`: تعداد دفعات (مثلاً در هفته) |
+| `amount` | string | خیر | فقط برای `recommendation`: مقدار (مثلاً لیتر یا کیلوگرم) |
+| `timing` | string | خیر | فقط برای `recommendation`: زمان پیشنهادی |
+| `expandableExplanation` | string | خیر | فقط برای `recommendation`: توضیح قابل گسترش «چرا این توصیه» |
+
+- اگر `content` خالی باشد و فقط `sections` برگردد، در UI فقط کارت‌ها نمایش داده می‌شوند (مطابق پیاده‌سازی فعلی).
+- در صورت خطا انتظار می‌رود پاسخ با `status: "error"` و پیام مناسب برگردد.