Ai/docs/farm_alerts_tracker_api.md

# راهنمای استفاده از API هشدارهای مزرعه

این سند نحوه کار با API فعال هشدارهای مزرعه را توضیح می‌دهد.

## Endpoint فعال

- `POST /api/farm-alerts/tracker/`

نکته:
- endpoint `POST /api/farm-alerts/timeline/` حذف شده و دیگر قابل استفاده نیست.

## کاربرد API

این API با دریافت `farm_uuid` و یک لیست از `alerts`:

- وضعیت فعلی هشدارهای مزرعه را تحلیل می‌کند
- context مزرعه را همراه با alertهای ارسالی به RAG می‌فرستد
- فقط notificationهای مهم را تولید می‌کند
- notificationهای تولیدشده را در دیتابیس ذخیره می‌کند

## ساختار درخواست

فیلدهای ورودی:

- `farm_uuid`: شناسه مزرعه
- `alerts`: لیست alertهای ورودی برای تحلیل

فیلد `farm_uuid` الزامی است.

## ساختار هر alert

هر آیتم داخل `alerts` می‌تواند این فیلدها را داشته باشد:

- `alert_id`: شناسه هشدار
- `level`: سطح هشدار مثل `info` یا `warning` یا `danger`
- `title`: عنوان هشدار
- `message`: توضیح هشدار
- `suggested_action`: اقدام پیشنهادی
- `source_metric_type`: نوع شاخص مثل `moisture`
- `timestamp`: زمان هشدار با فرمت datetime
- `payload`: داده تکمیلی به صورت JSON object

همه فیلدهای داخل هر alert اختیاری هستند، ولی بهتر است برای تحلیل دقیق‌تر حداقل `title` یا `message` و در صورت امکان `level` و `source_metric_type` ارسال شوند.

## نمونه درخواست

```json
{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "alerts": [
    {
      "alert_id": "soil-moisture-001",
      "level": "warning",
      "title": "افت رطوبت خاک",
      "message": "رطوبت خاک کمتر از حد مطلوب گزارش شده است.",
      "suggested_action": "آبیاری اصلاحی بررسی شود.",
      "source_metric_type": "moisture",
      "timestamp": "2025-02-14T09:30:00Z",
      "payload": {
        "window": "3d",
        "current_value": 38.5,
        "threshold": 45
      }
    },
    {
      "alert_id": "fungal-risk-002",
      "level": "danger",
      "title": "ریسک قارچی بالا",
      "message": "شرایط محیطی برای بیماری قارچی شدید شده است.",
      "suggested_action": "بازدید و اقدام پیشگیرانه فوری انجام شود.",
      "source_metric_type": "fungal_risk",
      "timestamp": "2025-02-14T10:00:00Z",
      "payload": {
        "humidity": 89,
        "duration_hours": 18
      }
    }
  ]
}
```

## نمونه درخواست با curl

```bash
curl -X POST http://localhost:8000/api/farm-alerts/tracker/ \
  -H "Content-Type: application/json" \
  -d '{
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "alerts": [
      {
        "alert_id": "soil-moisture-001",
        "level": "warning",
        "title": "افت رطوبت خاک",
        "message": "رطوبت خاک کمتر از حد مطلوب گزارش شده است.",
        "suggested_action": "آبیاری اصلاحی بررسی شود.",
        "source_metric_type": "moisture"
      }
    ]
  }'
```

## ساختار پاسخ موفق

پاسخ HTTP با envelope زیر برمی‌گردد:

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "service_id": "farm_alerts",
    "tracker": {},
    "headline": "جمع بندی کوتاه وضعیت هشدارها",
    "overview": "توضیح کوتاه و اجرایی از مهم ترین وضعیت مزرعه",
    "status_level": "warning",
    "notifications": [
      {
        "id": 12,
        "farm_uuid": "11111111-1111-1111-1111-111111111111",
        "endpoint": "tracker",
        "level": "warning",
        "title": "افت رطوبت خاک",
        "message": "تنش رطوبتی در مزرعه ادامه دارد.",
        "suggested_action": "آبیاری جبرانی کوتاه مدت اجرا شود.",
        "source_alert_id": "soil-moisture-001",
        "source_metric_type": "moisture",
        "payload": {},
        "created_at": "2025-02-14T10:15:00+00:00",
        "updated_at": "2025-02-14T10:15:00+00:00"
      }
    ],
    "raw_llm_response": "{\"headline\":\"...\"}",
    "structured_context": {}
  }
}
```

## وضعیت‌های خطا

### خطای ورودی نامعتبر

اگر `farm_uuid` ارسال نشود:

```json
{
  "code": 400,
  "msg": "داده نامعتبر.",
  "data": {
    "farm_uuid": [
      "farm_uuid الزامی است."
    ]
  }
}
```

### خطای داخلی

اگر در مرحله تحلیل RAG یا تولید پاسخ خطایی رخ دهد:

```json
{
  "code": 500,
  "msg": "خطا در تولید tracker هشدارها: ...",
  "data": null
}
```

## نکات رفتاری API

- اگر `alerts` ارسال نشود، API آن را به صورت آرایه خالی در نظر می‌گیرد.
- notificationهای ساخته‌شده برای endpoint `tracker` در دیتابیس ذخیره می‌شوند.
- مدل باید notification تکراری نسازد و اگر مورد مهمی وجود نداشته باشد، خروجی notification می‌تواند خالی باشد.
- تحلیل فقط روی endpoint `tracker` فعال است.

## پیشنهاد برای مصرف‌کننده API

- برای هر alert یک `alert_id` پایدار بفرستید تا ردیابی و جلوگیری از تکرار بهتر انجام شود.
- برای alertهای حساس، `timestamp` و `source_metric_type` را حتما ارسال کنید.
- اگر داده تکمیلی دارید، آن را داخل `payload` بفرستید تا RAG context کامل‌تر شود.