From 03afe5dc5dcd8f5de7a8724a0ccd8619b5871060 Mon Sep 17 00:00:00 2001
From: Mohammad Sajad Pourajam <prj.sajad85@gmail.com>
Date: Wed, 29 Apr 2026 03:48:02 +0330
Subject: [PATCH] UPDATE

---
 config/tones/farm_alerts_tone.txt           |  14 +-
 docs/farm_alerts_tracker_response_fields.md | 492 ++++++++++++++++++++
 farm_alerts/views.py                        |   1 -
 3 files changed, 503 insertions(+), 4 deletions(-)
 create mode 100644 docs/farm_alerts_tracker_response_fields.md

diff --git a/config/tones/farm_alerts_tone.txt b/config/tones/farm_alerts_tone.txt
index 9566166..5d9c29e 100644
--- a/config/tones/farm_alerts_tone.txt
+++ b/config/tones/farm_alerts_tone.txt
@@ -53,9 +53,17 @@
 }
 
 قواعد تکميلي:
-- اگر در کانتکست، notificationهاي قبلي براي بازه اي بين 1 روز تا 7 روز گذشته ارسال شده بود، آن ها را بررسي کن و notification تکراري يا هم معنا دوباره نساز.
-- فقط وقتي notification جديد بساز که وضعيت واقعا جديد باشد، شدت هشدار تغيير معنادار کرده باشد، يا اقدام پيشنهادي جديد و مهم لازم باشد.
-- اگر هشدار مهمي وجود ندارد، آرايه هاي `notifications` يا `timeline` را خالي برگردان و در `headline` و `overview` شفاف بگو که فعلا مورد مهمي براي اعلام وجود ندارد.
+- در کانتکست، `incoming_alerts` ممکن است شامل alertها يا سابقه alertهاي چند ساعت تا چند روز گذشته باشد؛ آن ها را بررسي کن و notification تکراري يا هم معنا نساز.
+- notification تکراري، هم معنا، يا با اقدام يکسان نسبت به alertهاي موجود در `incoming_alerts` نساز؛ مگر اينکه وضعيت واقعا جديد شده باشد يا شدت هشدار به شکل معنادار تغيير کرده باشد.
+- فقط وقتي notification جديد بساز که يک رخداد مهم، جديد، غيرتکراري و قابل اقدام وجود داشته باشد.
+- اگر مورد مهم يا جديدي براي گفتن وجود ندارد، `notifications` را خالي برگردان و در `headline` و `overview` صريح و کوتاه بگو که فعلا notification مهم جديدي وجود ندارد.
+- اگر alertها خفيف، تکراري يا بدون اقدام تازه هستند، به جاي ساخت notification جديد، همان خروجی بدون notification بده.
+- [TEMP_FORCE_MIN_NOTIFICATION_START]
+- اين يک قاعده موقت است: اگر هيچ notification مهمي هم وجود نداشت، باز هم حداقل يک notification بساز.
+- در اين حالت، يک notification با `level` برابر `info` توليد کن که صريح بگويد فعلا مورد مهم جديدي شناسايي نشده است.
+- براي اين notification حداقلي، `title` کوتاه و خنثي باشد، `message` شفاف بگويد هشدار مهم جديدي وجود ندارد، و `suggested_action` فقط يک اقدام پايشي سبک و مشخص باشد.
+- اين notification حداقلي فقط وقتي استفاده شود که خروجي در غير اين صورت خالي مي شد.
+- [TEMP_FORCE_MIN_NOTIFICATION_END]
 - `headline` و `overview` هميشه الزامي هستند.
 - عنوان ها کوتاه و عملياتي باشند.
 - `suggested_action` بايد يک اقدام مشخص مزرعه اي باشد، نه توصيه کلي.
diff --git a/docs/farm_alerts_tracker_response_fields.md b/docs/farm_alerts_tracker_response_fields.md
new file mode 100644
index 0000000..19bad34
--- /dev/null
+++ b/docs/farm_alerts_tracker_response_fields.md
@@ -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`
diff --git a/farm_alerts/views.py b/farm_alerts/views.py
index 0240e01..cfc029d 100644
--- a/farm_alerts/views.py
+++ b/farm_alerts/views.py
@@ -66,7 +66,6 @@ class FarmAlertsTrackerView(APIView):
         try:
             result = get_farm_alerts_tracker(
                 farm_uuid=validated["farm_uuid"],
-                query=validated.get("query"),
                 alerts=validated.get("alerts"),
             )
         except Exception as exc: