Backend/NOTIFICATIONS_FRONTEND_API.md

راهنمای استفاده فرانت از APIهای Notifications

این فایل برای تیم فرانت نوشته شده تا بدون بررسی کد بک‌اند، بتواند APIهای ماژول notifications را مصرف کند.

---

خلاصه خیلی کوتاه

• تمام APIهای فعلی نوتیفیکیشن بر اساس farm_uuid کار می‌کنند.
• برای گرفتن نوتیفیکیشن‌ها باید GET /api/notifications/long-poll/ را صدا بزنید.
• در هر آیتم نوتیفیکیشن، فیلد since_id برگردانده می‌شود.
• برای علامت‌زدن نوتیفیکیشن‌ها به‌عنوان خوانده‌شده باید POST /api/notifications/mark-as-read/ را با farm_uuid و slice_id صدا بزنید.
• هر نوتیفیکیشن دارای وضعیت is_read است:
  • false یعنی خوانده نشده
  • true یعنی خوانده شده

---

Base Path

/api/notifications/

---

احراز هویت

هر دو API فعلی نیاز به کاربر لاگین‌شده دارند.

یعنی فرانت باید توکن کاربر را مثل بقیه endpointهای protected ارسال کند.

---

1) گرفتن نوتیفیکیشن‌ها

Endpoint

GET /api/notifications/long-poll/?farm_uuid=<farm_uuid>&since_id=<since_id>&timeout=<seconds>

Query Params

نام	اجباری	توضیح
farm_uuid	بله	شناسه مزرعه انتخاب‌شده
since_id	خیر	فقط نوتیفیکیشن‌های جدیدتر از این مقدار برگردانده می‌شوند
timeout	خیر	زمان long-poll بر حسب ثانیه، بین 0 تا 60

رفتار

• اگر since_id ارسال نشود، همه نوتیفیکیشن‌های مزرعه برمی‌گردند.
• اگر since_id ارسال شود، فقط نوتیفیکیشن‌هایی که id > since_id دارند برمی‌گردند.
• اگر نوتیفیکیشن جدیدی وجود نداشته باشد، تا زمان timeout منتظر می‌ماند و بعد آرایه خالی برمی‌گرداند.
• این endpoint فقط برای مزرعه‌ای جواب می‌دهد که متعلق به همان کاربر باشد.

نمونه درخواست

GET /api/notifications/long-poll/?farm_uuid=550e8400-e29b-41d4-a716-446655440000&since_id=12&timeout=15

نمونه response موفق

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "uuid": "0d4f68d0-8a49-4d5c-9d1c-1d4fd6d5e3a1",
      "farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "since_id": 13,
      "title": "هشدار آبیاری",
      "message": "رطوبت خاک پایین است",
      "level": "warning",
      "is_read": false,
      "metadata": {
        "sensor": "soil-1"
      },
      "created_at": "2025-02-20T10:30:00Z"
    }
  ]
}

معنی فیلدهای مهم

فیلد	توضیح
since_id	شناسه ترتیبی نوتیفیکیشن برای polling بعدی
is_read	وضعیت خوانده‌شدن نوتیفیکیشن
level	سطح نوتیفیکیشن مثل info، warning، critical
metadata	اطلاعات تکمیلی برای UI یا رفتارهای خاص

نکته مهم برای فرانت

بعد از هر بار دریافت response:

1. اگر data خالی نبود، since_id آخرین آیتم را نگه دارید.
2. در درخواست بعدی، همان مقدار را به‌عنوان since_id بفرستید.
3. برای badge یا شمارنده unread، از is_read استفاده کنید.

---

2) خوانده‌کردن نوتیفیکیشن‌ها

Endpoint

POST /api/notifications/mark-as-read/

Body

{
  "farm_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "slice_id": 13
}

معنی slice_id

slice_id یعنی:

• همه نوتیفیکیشن‌های همان مزرعه که id <= slice_id دارند
• و هنوز is_read=false هستند
• به is_read=true تغییر می‌کنند

به بیان ساده، اگر کاربر تا یک نقطه از لیست نوتیفیکیشن‌ها را دیده، فرانت می‌تواند since_id آخرین آیتم دیده‌شده را به‌عنوان slice_id ارسال کند.

نمونه response موفق

{
  "code": 200,
  "msg": "success",
  "marked_count": 4
}

معنی marked_count

تعداد نوتیفیکیشن‌هایی که واقعا در دیتابیس از unread به read تغییر کرده‌اند.

---

خطاهای رایج

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

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

{
  "code": 404,
  "msg": "Farm not found."
}

جدول نوتیفیکیشن آماده نیست

اگر migrationهای بک‌اند اجرا نشده باشند:

{
  "code": 503,
  "msg": "Notifications table is not ready. Run migrations."
}

---

پیشنهاد Flow برای فرانت

سناریوی پیشنهادی

1. کاربر یک مزرعه active انتخاب می‌کند.
2. فرانت farm_uuid آن مزرعه را در state نگه می‌دارد.
3. اولین بار:

GET /api/notifications/long-poll/?farm_uuid=<farm_uuid>&timeout=0

4. آخرین since_id را ذخیره می‌کند.
5. بعد از آن polling را با since_id ادامه می‌دهد:

GET /api/notifications/long-poll/?farm_uuid=<farm_uuid>&since_id=<last_since_id>&timeout=15

6. وقتی کاربر نوتیفیکیشن‌ها را دید، فرانت آخرین آیتم دیده‌شده را با slice_id به endpoint خوانده‌شدن می‌فرستد.

---

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

• برای هر farm_uuid یک last_since_id جدا نگه دارید.
• لیست نوتیفیکیشن‌ها را per-farm در state نگه دارید.
• unread count را از روی آیتم‌هایی که is_read=false دارند محاسبه کنید.
• وقتی کاربر صفحه نوتیفیکیشن را باز کرد یا لیست را تا انتها دید، slice_id آخرین آیتم دیده‌شده را ارسال کنید.

---

routeهای فعال فعلی

Method	Path	توضیح
GET	/api/notifications/long-poll/	دریافت نوتیفیکیشن‌ها با پشتیبانی از since_id
POST	/api/notifications/mark-as-read/	خوانده‌کردن نوتیفیکیشن‌ها تا slice_id