Ai/docs/farm_alerts_tracker_response_fields.md

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

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

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

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

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