راهنمای استفاده فرانت از سیستم نوتیفیکیشن (SSE + Redis)

این سند روش اتصال فرانت به سیستم نوتیفیکیشن جدید را توضیح می‌دهد.

1) APIهای موجود

استریم نوتیفیکیشن (SSE):
- GET /api/notifications/stream/?channel=<channel_name>
ارسال نوتیفیکیشن (برای تست/ادمین):
- POST /api/notifications/publish/

هر دو endpoint نیازمند احراز هویت هستند.

2) فرمت پیام دریافتی در SSE

payload نمونه:

{
  "id": "f6f5d6ca-54f1-4d0e-8d29-5ef5760a3b40",
  "event": "notification",
  "title": "آبیاری",
  "message": "زمان آبیاری مزرعه فرا رسیده است.",
  "level": "info",
  "metadata": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111"
  },
  "created_at": "2026-04-03T20:00:00.000000+00:00"
}

event به‌صورت SSE event name هم ارسال می‌شود.

3) انتخاب channel

الگوی پیشنهادی:

کانال کاربر: user-<user_id>
کانال مزرعه: farm-<farm_uuid>

در وضعیت فعلی backend اگر channel نفرستید، پیش‌فرض روی user-<current_user_id> است.

4) اتصال در فرانت

نکته مهم: چون backend روی JWT (Authorization: Bearer ...) است، EventSource پیش‌فرض مرورگر امکان ارسال header سفارشی ندارد.
پس یا از polyfill/library استفاده کنید، یا مکانیزم auth مبتنی بر cookie داشته باشید.

نمونه با @microsoft/fetch-event-source:

import { fetchEventSource } from "@microsoft/fetch-event-source";

const API_BASE = "https://your-domain.com";
const token = localStorage.getItem("access_token");
const channel = "user-123";

await fetchEventSource(`${API_BASE}/api/notifications/stream/?channel=${channel}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "text/event-stream"
  },
  onopen(response) {
    if (!response.ok) throw new Error("SSE connection failed");
  },
  onmessage(event) {
    if (!event.data) return;
    const payload = JSON.parse(event.data);
    // نمایش toast / badge / in-app notification
    console.log("notification:", payload);
  },
  onerror(err) {
    console.error("SSE error", err);
    // کتابخانه به شکل پیش‌فرض reconnect می‌کند
  }
});

5) ارسال نوتیفیکیشن (برای تست از فرانت یا پنل ادمین)

درخواست:

POST /api/notifications/publish/
Authorization: Bearer <access_token>
Content-Type: application/json

بدنه:

{
  "channel": "user-123",
  "title": "نمونه نوتیف",
  "message": "این پیام تستی است",
  "level": "info",
  "event": "notification",
  "metadata": {
    "farm_uuid": "11111111-1111-1111-1111-111111111111"
  }
}

6) پیشنهاد UX در فرانت

روی level، رنگ‌بندی toast انجام دهید (info/success/warning/error).
metadata را برای deep-link استفاده کنید (مثلاً رفتن به صفحه مزرعه).
هنگام logout، اتصال SSE را قطع کنید.
هنگام تغییر کاربر یا مزرعه، channel را عوض کنید و اتصال قبلی را ببندید.

7) خطاهای رایج

401 Unauthorized: توکن نامعتبر/منقضی شده.
403 Forbidden: کاربر دسترسی لازم به endpoint ندارد.
اتصال برقرار می‌شود ولی پیامی نمی‌آید: channel اشتباه است یا پیام روی channel دیگری publish شده است.

3.6 KiB Raw Blame History