Tích hợp MQ-SMS

@nx/mq-sms là thư viện quản lý SMS đa nhà cung cấp. Nó bọc các API của nhà cung cấp SMS sau một interface thống nhất với mô hình client registry. Hiện hỗ trợ VnPay là nhà cung cấp SMS duy nhất.

Tham chiếu nhanh

Thuộc tính	Giá trị
Package	@nx/mq-sms
Vị trí	third-parties/mq-sms/
Loại	Thư viện (được sử dụng như một component bởi các service khác)
Được sử dụng bởi	@nx/identity (gửi OTP)

Kiến trúc

Nhà cung cấp

Nhà cung cấp	Mã	Trạng thái
VnPay	MQSMSProviders.VNPAY = 'vnpay'	Đang hoạt động

Cấu hình VnPay

Trường	Mục đích
username / password	Xác thực API
partnerCode / secretKey	Định danh đối tác
keyword	Từ khóa/tên thương hiệu SMS
brandName	Tên hiển thị người gửi
encryptIv	IV cho chế độ SMS mã hóa (tùy chọn)
partnerPrivateKeyPath	RSA private key cho chế độ bảo mật (tùy chọn)

Các endpoint VnPay được sử dụng:

• /login — xác thực (client tự quản lý)
• /send-sms — gửi SMS đơn
• /v2/send-sms-security — gửi SMS đơn mã hóa
• /send-sms-list — gửi SMS batch
• /v2/send-sms-list-security — gửi SMS batch mã hóa

SMSService

Các phương thức chính của service:

Phương thức	Mục đích
sendSMS(request, clientName?)	Gửi SMS đơn qua client mặc định hoặc theo tên
sendSMSSecurity(request, clientName?)	Gửi SMS đơn có mã hóa
sendSMSList(requests, clientName?)	Gửi SMS batch
sendSMSListSecurity(requests, clientName?)	Gửi SMS batch có mã hóa

Định dạng request

interface TSendSmsRequest {
  messageId?: string;     // optional correlation ID
  destination: string;    // phone number
  content: string;        // message body
}

MQSMSClientRegistryService

Quản lý nhiều instance client theo nhà cung cấp:

Phương thức	Mục đích
registerClient(name, client)	Đăng ký một client nhà cung cấp
unregisterClient(name)	Gỡ bỏ một client
getClient(name?)	Lấy client theo tên (hoặc client mặc định)
getDefaultClient()	Lấy client mặc định hiện tại
setDefaultClient(name)	Chuyển client mặc định

Mỗi client đã đăng ký theo dõi: token, thời điểm hết hạn token, timestamp sử dụng gần nhất.

REST Controller (Tùy chọn)

Khi enableControllers: true được đặt trong options của MQSMSComponent, một SMSController sẽ được đăng ký:

Method	Path	Mục đích
POST	/mq-sms/sms/send	Gửi SMS đơn
POST	/mq-sms/sms/send-security	Gửi SMS đơn mã hóa
POST	/mq-sms/sms/send-list	Gửi SMS batch
POST	/mq-sms/sms/send-list-security	Gửi SMS batch mã hóa

Mọi endpoint đều chấp nhận tham số query clientName tùy chọn để chọn một client nhà cung cấp cụ thể.

Tích hợp với Identity

Service identity sử dụng MQ-SMS để gửi OTP (One-Time Password):

1. SMSComponent trong identity đăng ký MQSMSComponent khi khởi động
2. Cấu hình nhà cung cấp được nạp từ cơ sở dữ liệu (seed bởi identity-0006-seed-sms-configurations)
3. SMSOTPSender inject SMSService và gọi sendSMS() để gửi mã xác thực
4. Cấu hình SMS hỗ trợ nhiều client VnPay (các brand name/tài khoản khác nhau)

Binding Keys

Key	Mục đích
MQSMSBindingKeys.MQ_SMS_CLIENT_OPTIONS	Cấu hình component
MQSMSBindingKeys.MQ_SMS_CLIENT_PROVIDER	Hàm factory tạo client
MQSMSBindingKeys.MQ_SMS_CLIENT_REGISTRY	Instance của registry service

Mã phản hồi VnPay

Mã	Ý nghĩa
00	Thành công
02	Độ dài không hợp lệ
04	Xác thực không hợp lệ
05	Nhà cung cấp mất kết nối
06	IP chưa được đăng ký
21	Không đủ số dư
85	Người gửi không hợp lệ
86	Keyword không hợp lệ
90	Tin nhắn trùng lặp

Các trang liên quan

Trang	Mô tả
Identity — Authentication	Gửi OTP qua MQ-SMS
MQ-Pay	Thanh toán đa nhà cung cấp (cùng pattern registry)