UPDATE
This commit is contained in:
@@ -0,0 +1,492 @@
|
||||
# توضیح فیلدهای پاسخ 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`
|
||||
Reference in New Issue
Block a user