# مستندات 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"` و پیام مناسب برگردد.
