Cài đặt và sử dụng — Notifications (Legacy)

Tổng quan

@digiforce-nc/plugin-notifications là hệ thống thông báo đời đầu của Digiforce, sử dụng nodemailer để gửi email. Plugin quản lý ba Collection chính: notifications (nội dung thông báo), notification_services (cấu hình SMTP transport), và notification_logs (nhật ký gửi).

Cảnh báo: Plugin này đã deprecated. Các dự án mới nên dùng @digiforce-nc/plugin-notification-manager để có multi-channel, template engine nâng cao, và kiến trúc mở rộng tốt hơn.

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

Vào Settings → Plugin Manager, tìm plugin-notifications và bật lên. Sau khi kích hoạt, hệ thống tự động tạo ba bảng trong Database:

Bảng	Mục đích
notifications	Lưu trữ nội dung thông báo (subject, body, receiver_options)
notification_services	Cấu hình dịch vụ gửi email (SMTP host, port, auth)
notification_logs	Ghi lại kết quả gửi (thành công / thất bại) cho từng người nhận

Bước 2: Cấu hình Notification Service (SMTP)

Plugin sử dụng nodemailer.createTransport() để thiết lập kết nối SMTP. Bạn cần tạo một bản ghi trong Collection notification_services với các thông tin sau:

Trường	Kiểu	Mô tả	Ví dụ
type	string	Loại dịch vụ	"email"
title	string	Tên hiển thị	"SMTP chính"
options	json	Cấu hình nodemailer transport	Xem bên dưới

Ví dụ cấu hình options cho Gmail SMTP

{
  "host": "smtp.gmail.com",
  "port": 465,
  "secure": true,
  "from": "noreply@company.com",
  "auth": {
    "user": "noreply@company.com",
    "pass": "app-specific-password"
  }
}

Ví dụ cấu hình cho SMTP nội bộ (không TLS)

{
  "host": "mail.internal.company.com",
  "port": 25,
  "secure": false,
  "from": "system@company.com"
}

Lưu ý: Trường from trong options là địa chỉ gửi mặc định. Nó được merge vào mọi email gửi đi trừ khi bị override.

Bước 3: Tạo Notification

Tạo bản ghi trong Collection notifications để định nghĩa một thông báo:

Trường	Kiểu	Mô tả
name	uid (tự sinh)	ID dạng n_xxxx, tự động tạo
subject	string	Tiêu đề email
body	text	Nội dung HTML, hỗ trợ lodash.template
receiver_options	json	Cách xác định người nhận (xem bên dưới)
service	belongsTo	Liên kết tới notification_services

Receiver Options

Plugin hỗ trợ hai cách xác định danh sách người nhận:

Cách 1 — Truyền trực tiếp danh sách email:

{
  "data": ["user1@example.com", "user2@example.com"]
}

Cách 2 — Truy vấn từ Collection khác:

{
  "fromTable": "users",
  "filter": { "role": "admin" },
  "dataField": "email"
}

Khi gọi notification.send(), plugin sẽ:

1. Lấy danh sách người nhận từ receiver_options
2. Merge thêm người nhận từ tham số to (nếu có)
3. Gửi email lần lượt cho từng người nhận qua SMTP transport
4. Ghi log kết quả vào notification_logs

Bước 4: Gửi thông báo qua API

Gọi từ code server

const notification = await db.getRepository('notifications').findOne({
  filter: { name: 'n_welcome' },
  appends: ['service'],
});

await notification.send({
  to: 'newuser@example.com',
});

Template body với lodash

Plugin sử dụng lodash.template để render nội dung email. Bạn có thể truyền dữ liệu khi gọi send():

// Body template trong DB: "<p>Xin chào <%= name %>, đơn hàng #<%= orderId %> đã được xác nhận.</p>"

await notification.send({
  name: 'Nguyễn Văn A',
  orderId: '12345',
});

Xử lý lỗi gửi email

Khi gửi thất bại (SMTP timeout, địa chỉ không hợp lệ, v.v.), plugin sẽ:

• Ghi log với state: 'fail' vào notification_logs
• Tiếp tục gửi cho người nhận tiếp theo (không dừng toàn bộ batch)
• In lỗi ra console qua console.error

Lỗi thường gặp	Nguyên nhân	Cách xử lý
ECONNREFUSED	SMTP server không phản hồi	Kiểm tra host, port, firewall
EAUTH	Sai thông tin đăng nhập	Kiểm tra user/pass trong options
Invalid recipient	Địa chỉ email sai định dạng	Kiểm tra receiver_options hoặc tham số to

Lưu ý quan trọng

• Plugin gửi email tuần tự cho từng người nhận với delay 100ms giữa mỗi lần gửi — không phù hợp cho batch lớn (hàng ngàn email)
• Không có cơ chế retry tự động — email thất bại chỉ được ghi log
• Body template dùng lodash.template — cẩn thận với XSS nếu truyền dữ liệu từ user input
• Plugin không có UI quản trị riêng trên client — mọi thao tác qua Collection Manager hoặc API