Backend/farm_alerts/TRACKER_API_FRONTEND.md

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

این سند برای تیم فرانت نوشته شده تا بداند endpoint tracker چه ورودی‌ای می‌گیرد، چه کاری انجام می‌دهد، و response آن را چطور باید در UI مصرف کند.

Endpoint

• POST /api/farm-alerts/tracker/

احراز هویت

• این API نیاز به Bearer Token دارد.
• کاربر فقط به مزرعه‌های متعلق به خودش دسترسی دارد.

کاربرد API

فرانت با ارسال alertهای جدید مربوط به یک مزرعه:

• alertها را در بک‌اند ذخیره می‌کند
• notificationهای 3 روز اخیر همان مزرعه را هم به context اضافه می‌کند
• همه داده‌ها را برای AI می‌فرستد
• AI یک جمع‌بندی کوتاه، وضعیت کلی، و notificationهای مهم برمی‌گرداند
• notificationهای خروجی AI هم در دیتابیس ذخیره می‌شوند

این endpoint هم برای تحلیل وضعیت هشدارها مناسب است، هم برای ساخت کارت summary، هم برای notification center.

Request Body

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

• farm_uuid: شناسه مزرعه - اجباری
• alerts: لیست هشدارهای جدید - اختیاری

ساختار هر alert

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

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

نمونه request

{
  "farm_uuid": "11111111-1111-1111-1111-111111111111",
  "alerts": [
    {
      "alert_id": "soil-moisture-001",
      "level": "warning",
      "title": "افت رطوبت خاک",
      "message": "رطوبت خاک کمتر از حد مطلوب گزارش شده است.",
      "suggested_action": "آبیاری اصلاحی بررسی شود.",
      "source_metric_type": "moisture"
    }
  ]
}

نمونه curl

curl -X POST \
  'http://localhost:8000/api/farm-alerts/tracker/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -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"
      }
    ]
  }'

رفتار بک‌اند

بعد از دریافت request:

1. مزرعه را با farm_uuid پیدا می‌کند و ownership را چک می‌کند.
2. alertهای ارسالی را در جدول farm_alerts ذخیره می‌کند.
3. حداکثر 10 notification ثبت‌شده در 3 روز اخیر همان مزرعه را برمی‌دارد.
4. alerts جدید + recent_notifications را برای AI می‌فرستد.
5. notificationهای مهم تولیدشده توسط AI را در جدول farm_notifications ذخیره می‌کند.
6. response نهایی را به فرانت برمی‌گرداند.

ساختار response موفق

response داخل envelope استاندارد برمی‌گردد:

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "service_id": "farm_alerts",
    "tracker": {},
    "headline": "بررسی رطوبت خاک در مزرعه",
    "overview": "افت خفیف رطوبت خاک گزارش شده است که نیاز به پایش دارد.",
    "status_level": "warning",
    "notifications": [],
    "raw_llm_response": "...",
    "structured_context": {}
  }
}

توضیح فیلدهای اصلی response

farm_uuid

شناسه مزرعه‌ای که تحلیل برای آن انجام شده است.

service_id

شناسه سرویس. فعلا مقدار آن farm_alerts است.

tracker

بخش اصلی داده برای ساخت UI هشدارها.

این بخش ممکن است شامل این فیلدها باشد:

• totalAlerts: تعداد کل alertهای فعلی
• alerts: لیست alertهای تحلیل‌شده
• alertStats: آمار خلاصه برای کارت‌ها
• alertClusters: گروه‌بندی alertها
• mostCriticalIssue: مهم‌ترین هشدار فعلی
• prioritizedAlertSummaries: خلاصه‌های اولویت‌دار
• recommendedOperationalActions: اقدام‌های عملیاتی پیشنهادی
• humanReadableExplanations: توضیح‌های متنی ساده برای کاربر

headline

تیتر کوتاه برای بالای کارت یا صفحه.

overview

جمع‌بندی کوتاه و اجرایی برای کاربر.

status_level

وضعیت کلی تحلیل برای رنگ‌بندی UI.

مقادیر معمول:

• info
• warning
• error
• success

notifications

لیست notificationهای مهمی که AI تولید کرده و در دیتابیس ذخیره شده‌اند.

هر notification ممکن است این فیلدها را داشته باشد:

• id: شناسه دیتابیسی
• uuid: شناسه یکتا
• farm_uuid: شناسه مزرعه
• since_id: همان id برای برخی flowهای polling
• endpoint: منبع notification، اینجا معمولا tracker
• title: عنوان
• message: متن
• level: شدت
• suggested_action: اقدام پیشنهادی
• source_alert_id: شناسه alert اصلی
• source_metric_type: نوع شاخص
• payload: داده تکمیلی
• is_read: خوانده شده یا نه
• metadata: اطلاعات داخلی
• created_at: زمان ایجاد
• updated_at: زمان آخرین به‌روزرسانی

raw_llm_response

پاسخ خام AI برای debug یا audit.

برای UI اصلی معمولا لازم نیست مستقیم نمایش داده شود.

structured_context

context تکمیلی که برای AI ساخته شده.

ممکن است شامل این بخش‌ها باشد:

• farm_profile
• tracker
• forecasts
• incoming_alerts

این فیلد بیشتر برای debug، مانیتورینگ، یا صفحه‌های تخصصی مفید است.

استفاده پیشنهادی در فرانت

هدر صفحه یا کارت summary

از این فیلدها استفاده کنید:

• headline
• overview
• status_level

لیست هشدارهای فعلی

از:

• tracker.alerts

مهم‌ترین هشدار

از:

• tracker.mostCriticalIssue

کارت آمار هشدار

از:

• tracker.totalAlerts
• tracker.alertStats

اقدام‌های پیشنهادی

از:

• tracker.recommendedOperationalActions

توضیح ساده برای کاربر

از:

• tracker.humanReadableExplanations

notification center یا drawer

از:

• notifications

نمونه mapping برای فرانت

const result = response.data.data;

const headerTitle = result.headline;
const headerText = result.overview;
const severity = result.status_level;

const totalAlerts = result.tracker.totalAlerts;
const alerts = result.tracker.alerts;
const stats = result.tracker.alertStats;
const criticalIssue = result.tracker.mostCriticalIssue;
const suggestedActions = result.tracker.recommendedOperationalActions;
const notifications = result.notifications;

نمونه response واقعی

{
  "code": 200,
  "msg": "success",
  "data": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111",
    "service_id": "farm_alerts",
    "tracker": {
      "totalAlerts": 1,
      "alerts": [
        {
          "metric_type": "moisture",
          "title": "تنش رطوبتی",
          "current_value": 42.3,
          "threshold_value": 45,
          "severity": "low",
          "duration_hours": 2.8,
          "duration": "3 ساعت",
          "timestamp": "2026-04-28T20:31:39.594431+00:00",
          "sensor_id": "11111111-1111-1111-1111-111111111111",
          "zone_id": null,
          "domain": "water_balance",
          "direction": "below",
          "unit": "%",
          "icon": "tabler-droplet-half-2",
          "summary": "افت رطوبت خاک ثبت شده و نیاز به پایش نزدیک‌تر دارد.",
          "recommended_action": "روند رطوبت را در نوبت بعدی کنترل و یکنواختی آبیاری را بررسی کنید.",
          "explanation": "رطوبت فعلی 42.3% به زیر آستانه 45.0% رسیده است و این وضعیت 3 ساعت ادامه داشته است.",
          "metadata": {}
        }
      ],
      "alertStats": [
        {
          "title": "تنش رطوبتی",
          "count": "1",
          "avatarColor": "info",
          "avatarIcon": "tabler-droplet-half-2",
          "severity": "low",
          "topSummary": "افت رطوبت خاک ثبت شده و نیاز به پایش نزدیک‌تر دارد."
        }
      ],
      "alertClusters": [
        {
          "domain": "water_balance",
          "title": "تعادل آب",
          "alert_count": 1,
          "highest_severity": "low",
          "primary_metric": "moisture",
          "summary": "افت رطوبت خاک ثبت شده و نیاز به پایش نزدیک‌تر دارد.",
          "alert_ids": [
            "moisture:2026-04-28T20:31:39.594431+00:00"
          ]
        }
      ],
      "mostCriticalIssue": {
        "metric_type": "moisture",
        "title": "تنش رطوبتی",
        "current_value": 42.3,
        "threshold_value": 45,
        "severity": "low",
        "duration_hours": 2.8,
        "duration": "3 ساعت",
        "timestamp": "2026-04-28T20:31:39.594431+00:00",
        "sensor_id": "11111111-1111-1111-1111-111111111111",
        "zone_id": null,
        "domain": "water_balance",
        "direction": "below",
        "unit": "%",
        "icon": "tabler-droplet-half-2",
        "summary": "افت رطوبت خاک ثبت شده و نیاز به پایش نزدیک‌تر دارد.",
        "recommended_action": "روند رطوبت را در نوبت بعدی کنترل و یکنواختی آبیاری را بررسی کنید.",
        "explanation": "رطوبت فعلی 42.3% به زیر آستانه 45.0% رسیده است و این وضعیت 3 ساعت ادامه داشته است.",
        "metadata": {}
      },
      "prioritizedAlertSummaries": [
        "افت رطوبت خاک ثبت شده و نیاز به پایش نزدیک‌تر دارد."
      ],
      "recommendedOperationalActions": [
        "روند رطوبت را در نوبت بعدی کنترل و یکنواختی آبیاری را بررسی کنید."
      ],
      "humanReadableExplanations": [
        "رطوبت فعلی 42.3% به زیر آستانه 45.0% رسیده است و این وضعیت 3 ساعت ادامه داشته است."
      ]
    },
    "headline": "بررسی رطوبت خاک در مزرعه",
    "overview": "افت خفیف رطوبت خاک گزارش شده است که نیاز به پایش دارد.",
    "status_level": "warning",
    "notifications": [
      {
        "id": 1,
        "uuid": "640e6187-49d9-4256-ad0d-18927712d496",
        "farm_uuid": "11111111-1111-1111-1111-111111111111",
        "since_id": 1,
        "endpoint": "tracker",
        "title": "افت رطوبت خاک",
        "message": "رطوبت خاک کمتر از حد مطلوب گزارش شده است.",
        "level": "warning",
        "suggested_action": "روند رطوبت را در نوبت بعدی کنترل و یکنواختی آبیاری را بررسی کنید.",
        "source_alert_id": "soil-moisture-001",
        "source_metric_type": "moisture",
        "payload": {},
        "is_read": false,
        "metadata": {
          "source": "farm_alerts_tracker_ai"
        },
        "created_at": "2026-04-28T23:20:19.750658Z",
        "updated_at": "2026-04-28T23:20:19.750719Z"
      }
    ],
    "raw_llm_response": "{...}",
    "structured_context": {
      "incoming_alerts": [
        {
          "alert_id": "soil-moisture-001",
          "level": "warning",
          "title": "افت رطوبت خاک",
          "message": "رطوبت خاک کمتر از حد مطلوب گزارش شده است.",
          "suggested_action": "آبیاری اصلاحی بررسی شود.",
          "source_metric_type": "moisture",
          "timestamp": null,
          "payload": {}
        }
      ]
    }
  }
}

خطاهای متداول

مزرعه پیدا نشد

اگر farm_uuid متعلق به کاربر نباشد یا وجود نداشته باشد:

{
  "farm_uuid": [
    "Farm not found."
  ]
}

بدنه نامعتبر

اگر فیلدهای نامعتبر بفرستید:

{
  "unexpected_field": [
    "This field is not allowed."
  ]
}

احراز هویت نامعتبر

• در صورت نبود token یا نامعتبر بودن آن، پاسخ 401 Unauthorized برمی‌گردد.

توصیه برای فرانت

• برای هر alert یک alert_id پایدار بفرستید.
• اگر alert جدیدی ندارید، می‌توانید فقط farm_uuid بفرستید.
• از headline و overview برای summary UI استفاده کنید.
• از notifications برای notification list یا toast استفاده کنید.
• از tracker.mostCriticalIssue و tracker.recommendedOperationalActions برای CTA و نمایش اقدام فوری استفاده کنید.