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 ارسال شوند.

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

{
  "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

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 زیر برمی‌گردد:

{
  "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 ارسال نشود:

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

خطای داخلی

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

{
  "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 کامل‌تر شود.