UPDATE

2026-04-29 02:58:45 +03:30
parent 27bdad0111
commit 64abf40be9
6 changed files with 257 additions and 64 deletions
@@ -0,0 +1,180 @@
+# راهنمای استفاده از 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 کامل‌تر شود.