Hướng dẫn cài đặt — In-App Message

Yêu cầu hệ thống

Thành phần	Yêu cầu
plugin-notification-manager	Đã kích hoạt (bắt buộc — hub trung tâm)

Bước 1: Kích hoạt Plugin

Truy cập Settings → Plugin Manager, tìm plugin-notification-in-app-message và bật plugin. Khởi động lại server.

Bước 2: Tự động đăng ký

Plugin tự động đăng ký kênh in-app-message vào NotificationManager khi load. Không cần cấu hình thêm — kênh in-app hoạt động ngay sau khi bật plugin.

Bước 3: Kiểm tra hoạt động

1. Gửi thông báo in-app qua API hoặc Workflow
2. Người nhận sẽ thấy biểu tượng chuông trên thanh header với badge đếm số thông báo chưa đọc
3. Click chuông để mở danh sách thông báo
4. Click vào thông báo để xem chi tiết và đánh dấu đã đọc

Giao diện người dùng

Desktop

Thành phần	Mô tả
Notification Bell	Biểu tượng chuông trên header bar, hiển thị badge đếm chưa đọc
Inbox Popup	Dropdown danh sách thông báo khi click chuông
Message Detail	Chi tiết thông báo khi click vào một mục
Mark as Read	Đánh dấu đã đọc (từng cái hoặc tất cả)

Mobile

Thành phần	Mô tả
Tab Bar Badge	Badge đếm trên tab thông báo (antd-mobile)
Inbox Page	Trang inbox toàn màn hình
Swipe actions	Vuốt để đánh dấu đã đọc hoặc xoá

Cơ chế Real-time (SSE)

Plugin sử dụng Server-Sent Events (SSE) thay vì WebSocket để push thông báo real-time:

Đặc điểm	Chi tiết
Giao thức	HTTP SSE (text/event-stream)
Hướng	Một chiều: Server → Client
Kết nối	Mỗi user một stream, tự động reconnect
Tương thích	Hoạt động tốt với proxy, load balancer, CDN
Filtering	Chỉ push đến đúng userId

Ưu điểm so với WebSocket

Tiêu chí	SSE	WebSocket
Thiết lập	Đơn giản (HTTP thuần)	Phức tạp (upgrade protocol)
Proxy/LB	Tương thích tốt	Cần cấu hình đặc biệt
Reconnect	Tự động (built-in)	Cần tự implement
Hướng	Một chiều (đủ cho notification)	Hai chiều

Gửi thông báo in-app

Qua API

await api.resource('messages').send({
  values: {
    channelName: 'in-app-message',
    to: [userId1, userId2],
    title: 'Đơn hàng mới',
    content: {
      text: 'Bạn có đơn hàng mới #1234',
      link: '/orders/1234',
    },
  },
});

Từ Workflow

Trong workflow editor, sử dụng node Send Notification:

1. Chọn Channel: Kênh in-app đã đăng ký
2. Người nhận: userId từ workflow context
3. Nội dung: Template có biến động

Lưu ý khi triển khai

• SSE và Nginx: Cần cấu hình proxy_buffering off cho endpoint SSE, nếu không thông báo bị buffer và không real-time
• Thông báo không mất khi offline: Message được lưu trong database — khi user online lại, sẽ thấy tất cả thông báo chưa đọc
• State management: Client sử dụng immer để quản lý state danh sách thông báo hiệu quả
• Mobile support: Plugin đăng ký route mobile và tab bar riêng cho inbox thông báo