116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# راهنمای استفاده فرانت از سیستم نوتیفیکیشن (SSE + Redis)
|
|
|
|
این سند روش اتصال فرانت به سیستم نوتیفیکیشن جدید را توضیح میدهد.
|
|
|
|
## 1) APIهای موجود
|
|
|
|
- استریم نوتیفیکیشن (SSE):
|
|
- `GET /api/notifications/stream/?channel=<channel_name>`
|
|
- ارسال نوتیفیکیشن (برای تست/ادمین):
|
|
- `POST /api/notifications/publish/`
|
|
|
|
هر دو endpoint نیازمند احراز هویت هستند.
|
|
|
|
## 2) فرمت پیام دریافتی در SSE
|
|
|
|
payload نمونه:
|
|
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
```js
|
|
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) ارسال نوتیفیکیشن (برای تست از فرانت یا پنل ادمین)
|
|
|
|
درخواست:
|
|
|
|
```http
|
|
POST /api/notifications/publish/
|
|
Authorization: Bearer <access_token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
بدنه:
|
|
|
|
```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 شده است.
|