Logic/Modules/Ai/docs/farm_alerts_tracker_response_fields.md

توضیح فیلدهای پاسخ API هشدارهای مزرعه

این سند فیلدهای JSON خروجی POST /api/farm-alerts/tracker/ را توضیح می‌دهد.

ساختار کلی پاسخ

پاسخ API به شکل envelope برمی‌گردد:

{
  "code": 200,
  "msg": "success",
  "data": {}
}

فیلدهای سطح اول

code

• نوع: number
• معنی: کد وضعیت داخلی API
• مقدار رایج:
  • 200: موفق
  • 400: ورودی نامعتبر
  • 500: خطای داخلی

msg

• نوع: string
• معنی: پیام خلاصه وضعیت پاسخ
• نمونه:
  • success
  • داده نامعتبر.
  • خطا در تولید tracker هشدارها: ...

data

• نوع: object | null
• معنی: بدنه اصلی پاسخ
• در موفقیت شامل جزئیات تحلیل مزرعه است
• در بعضی خطاها ممکن است null باشد

فیلدهای داخل data

farm_uuid

• نوع: string
• معنی: شناسه مزرعه‌ای که تحلیل روی آن انجام شده

service_id

• نوع: string
• معنی: شناسه سرویس تولیدکننده پاسخ
• مقدار فعلی: farm_alerts

tracker

• نوع: object
• معنی: خروجی ساختاریافته‌ی موتور tracker قبل از خلاصه‌سازی نهایی AI
• شامل لیست alertها، آمار، خوشه‌بندی و مهم‌ترین مسئله است

headline

• نوع: string
• معنی: تیتر کوتاه و سریع برای وضعیت فعلی مزرعه
• برای نمایش در کارت، header یا لیست اعلان مناسب است

overview

• نوع: string
• معنی: جمع‌بندی کوتاه و اجرایی از مهم‌ترین وضعیت فعلی
• معمولا نسخه‌ی خلاصه‌شده‌ی مهم‌ترین alert یا نتیجه کلی تحلیل است

status_level

• نوع: string
• مقادیر مجاز:
  • info
  • warning
  • danger
• معنی: سطح کلی وضعیت مزرعه از دید AI

notifications

• نوع: array
• معنی: notificationهای نهایی که پس از تحلیل AI ساخته و در دیتابیس ذخیره شده‌اند
• اگر مورد مهمی وجود نداشته باشد، می‌تواند خالی باشد

raw_llm_response

• نوع: string | null
• معنی: پاسخ خام JSON که مدل زبانی تولید کرده است
• بیشتر برای debug، audit یا بررسی رفتار AI مفید است

structured_context

• نوع: object
• معنی: کانتکست ساختاریافته‌ای که به مدل داده شده است
• شامل اطلاعات مزرعه، tracker، forecastها و alertهای ورودی است

فیلدهای tracker

tracker.totalAlerts

• نوع: number
• معنی: تعداد کل alertهای شناسایی‌شده توسط tracker

tracker.alerts

• نوع: array
• معنی: لیست خام alertهای تشخیص‌داده‌شده

هر آیتم در tracker.alerts:

metric_type

• نوع: string
• معنی: نوع شاخصی که alert از آن آمده
• نمونه:
  • moisture
  • temperature
  • ph
  • ec
  • fungal_risk

title

• نوع: string
• معنی: عنوان انسانی alert

current_value

• نوع: number
• معنی: مقدار فعلی شاخص

threshold_value

• نوع: number | string
• معنی: آستانه مرجع برای تشخیص alert

severity

• نوع: string
• مقادیر رایج:
  • low
  • medium
  • high
  • critical
• معنی: شدت alert در لایه tracker

duration_hours

• نوع: number
• معنی: مدت تداوم وضعیت هشدار به ساعت

duration

• نوع: string
• معنی: نسخه خوانای duration_hours
• نمونه: 3 ساعت

timestamp

• نوع: string
• معنی: زمان مرجع alert با فرمت ISO datetime

sensor_id

• نوع: string
• معنی: شناسه مزرعه/سنسوری که alert برای آن محاسبه شده

zone_id

• نوع: string | null
• معنی: شناسه ناحیه، اگر alert مربوط به ناحیه خاصی باشد

domain

• نوع: string
• معنی: دامنه عملیاتی alert
• نمونه:
  • water_balance
  • temperature_stress
  • root_chemistry
  • disease_pressure

direction

• نوع: string
• معنی: جهت عبور از آستانه
• نمونه:
  • below: مقدار از حد مجاز کمتر شده
  • above: مقدار از حد مجاز بیشتر شده

unit

• نوع: string
• معنی: واحد شاخص
• نمونه:
  • %
  • °C
  • pH
  • dS/m

icon

• نوع: string
• معنی: نام آیکن پیشنهادی برای UI

summary

• نوع: string
• معنی: خلاصه انسانی و کوتاه alert

recommended_action

• نوع: string
• معنی: اقدام عملیاتی پیشنهادی tracker

explanation

• نوع: string
• معنی: توضیح قابل‌فهم درباره چرایی ایجاد alert

metadata

• نوع: object
• معنی: داده تکمیلی برای توسعه‌های بعدی

فیلدهای tracker.alertStats

• نوع: array
• معنی: خلاصه آماری alertها برای نمایش سریع در UI

هر آیتم:

title

• عنوان دسته alert

count

• نوع: string
• تعداد alertها در آن دسته

avatarColor

• نوع: string
• رنگ پیشنهادی UI

avatarIcon

• نوع: string
• آیکن پیشنهادی UI

severity

• نوع: string
• بالاترین شدت در آن دسته

topSummary

• نوع: string
• مهم‌ترین خلاصه در آن دسته

فیلدهای tracker.alertClusters

• نوع: array
• معنی: گروه‌بندی alertها بر اساس domain

هر آیتم:

domain

• نوع: string
• نام دامنه خوشه

title

• نوع: string
• عنوان انسانی خوشه

alert_count

• نوع: number
• تعداد alertهای این خوشه

highest_severity

• نوع: string
• بیشترین شدت بین alertهای این خوشه

primary_metric

• نوع: string
• مهم‌ترین metric در آن خوشه

summary

• نوع: string
• خلاصه وضعیت خوشه

alert_ids

• نوع: array
• معنی: شناسه‌های alertهای عضو خوشه

فیلد tracker.mostCriticalIssue

• نوع: object | null
• معنی: مهم‌ترین مسئله‌ای که tracker پیدا کرده
• ساختار آن مشابه هر آیتم در tracker.alerts است

فیلدهای خلاصه‌ای tracker

tracker.prioritizedAlertSummaries

• نوع: array
• معنی: لیستی از summaryهای مهم به ترتیب اولویت

tracker.recommendedOperationalActions

• نوع: array
• معنی: لیستی از اقدام‌های عملیاتی پیشنهادی

tracker.humanReadableExplanations

• نوع: array
• معنی: توضیح‌های متنی قابل‌خواندن برای نمایش یا گزارش

فیلدهای notifications

• نوع: array
• معنی: اعلان‌های نهایی ذخیره‌شده در سیستم

هر آیتم در notifications:

id

• نوع: number
• معنی: شناسه داخلی notification

uuid

• نوع: string
• معنی: شناسه یکتای notification

farm_uuid

• نوع: string
• معنی: شناسه مزرعه مربوط به notification

since_id

• نوع: number | null
• معنی: شناسه مرجع برای زنجیره یا گروه‌بندی notificationها در سیستم

endpoint

• نوع: string
• معنی: endpoint تولیدکننده notification
• مقدار فعلی: tracker

title

• نوع: string
• معنی: عنوان notification

message

• نوع: string
• معنی: متن اصلی notification

level

• نوع: string
• مقادیر مجاز:
  • info
  • warning
  • danger
• معنی: سطح notification

suggested_action

• نوع: string
• معنی: اقدام پیشنهادی نهایی برای کاربر

source_alert_id

• نوع: string
• معنی: شناسه alert مبنا که notification از آن ساخته شده

source_metric_type

• نوع: string
• معنی: نوع metric مبنا

payload

• نوع: object
• معنی: داده تکمیلی notification

is_read

• نوع: boolean
• معنی: آیا notification توسط کاربر خوانده شده یا نه

metadata

• نوع: object
• معنی: اطلاعات جانبی درباره منبع یا نحوه تولید notification
• نمونه:
  • source: farm_alerts_tracker_ai

created_at

• نوع: string
• معنی: زمان ایجاد notification

updated_at

• نوع: string
• معنی: زمان آخرین به‌روزرسانی notification

فیلدهای structured_context

این بخش برای debug و audit مفید است و نشان می‌دهد چه داده‌ای به مدل داده شده است.

structured_context.farm_profile

• اطلاعات پایه مزرعه

فیلدهای مهم:

• farm_uuid: شناسه مزرعه
• location.latitude: عرض جغرافیایی
• location.longitude: طول جغرافیایی
• plant_names: لیست گیاه‌های ثبت‌شده
• irrigation_method: روش آبیاری یا null
• last_sensor_update: زمان آخرین داده سنسور

structured_context.tracker

• همان داده tracker که به AI داده شده است

structured_context.forecasts

• نوع: array
• معنی: پیش‌بینی‌های هواشناسی کوتاه‌مدت

هر آیتم:

• date: تاریخ پیش‌بینی
• temperature_min: کمینه دما
• temperature_max: بیشینه دما
• humidity_mean: میانگین رطوبت
• precipitation: بارش
• et0: تبخیر-تعرق مرجع

structured_context.incoming_alerts

• نوع: array
• معنی: alertهایی که از request به API ارسال شده و در تحلیل استفاده شده‌اند
• اگر چیزی ارسال نشده باشد، آرایه خالی است

تفاوت severity و level

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

• severity: شدت داخلی alert در tracker با مقادیر low/medium/high/critical
• level: سطح نهایی notification یا status کلی با مقادیر info/warning/danger

به طور معمول:

• low معمولا به info نزدیک است
• medium معمولا به warning نزدیک است
• high و critical معمولا به danger نزدیک هستند

نکته عملی

اگر می‌خواهید در frontend فقط پیام نهایی را نمایش دهید، معمولا این فیلدها کافی هستند:

• data.headline
• data.overview
• data.status_level
• data.notifications

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

• data.tracker.alerts
• data.tracker.alertStats
• data.tracker.alertClusters
• data.structured_context.forecasts