Thiết kế Kỹ thuật
Module Dịch vụ SMS
SMS
1. Tổng quan
1.1 Mục đích
Tài liệu này mô tả các quyết định thiết kế kỹ thuật cho module Dịch vụ SMS.
1.2 Yêu cầu được giải quyết
| Danh mục | Mã Yêu cầu | Phần Thiết kế |
|---|
| Chức năng | FR-001 - FR-004 | Phần 3, 5 |
| Phi chức năng | NFR-001 - NFR-004 | Phần 5 |
2. Kiến trúc
2.1 Kiểu Kiến trúc
| Khía cạnh | Quyết định | Giải quyết |
|---|
| Mẫu | NestJS Worker (Driving bởi Sự kiện) | NFR-001 |
| Nhà cung cấp SMS | Twilio | FR-001 |
| Hàng đợi Tin nhắn | RabbitMQ | NFR-002 |
| Cơ sở dữ liệu | PostgreSQL (sms_db) | NFR-004 |
2.2 Quyết định Thiết kế Chính
| # | Quyết định | Lý do | Giải quyết |
|---|
| 1 | Twilio cho SMS |
Nhà cung cấp đáng tin cậy, API tốt, hỗ trợ số Việt Nam |
FR-001, NFR-002 |
| 2 | RabbitMQ cho bất đồng bộ |
Tách việc gửi SMS khỏi API, thử lại khi thất bại |
NFR-001, NFR-002 |
| 3 | Cơ sở dữ liệu riêng sms_db |
Tách log kiểm toán khỏi dữ liệu xác thực |
NFR-004 |
3. Thiết kế Thành phần
3.1 Sơ đồ Thành phần
Hình 1: Các Thành phần Module SMS
3.2 Cấu trúc Module
src/
sms/
sms.module.ts
sms.controller.ts # Webhook receiver từ Twilio
sms.service.ts # Business logic
sms.consumer.ts # RabbitMQ consumer
sms-producer.ts # RabbitMQ producer
dto/
external/
twilio.service.ts # Twilio API wrapper
3.3 Ánh xạ Thành phần đến Yêu cầu
| Thành phần | Trách nhiệm | Giải quyết |
|---|
| SmsService | Gửi SMS, xác minh OTP, ghi log giao dịch | FR-001, FR-002, FR-003 |
| SmsController | Nhận webhook giao dịch từ Twilio | FR-003 |
| SmsConsumer | Xử lý tin nhắn từ hàng đợi RabbitMQ | NFR-001 |
| TwilioService | Tích hợp API Twilio | FR-001 |
4. Kiến trúc Dữ liệu
4.1 Cơ sở dữ liệu
Cơ sở dữ liệu: sms_db (PostgreSQL)
Xem thêm: Thiết kế Cơ sở dữ liệu
4.2 Giải quyết Yêu cầu Dữ liệu
| Yêu cầu SRS | Giải pháp Thiết kế | Bảng CSDL |
|---|
| FR-001 Gửi SMS OTP | Chèn log SMS, gửi đến RabbitMQ | sms_logs |
| FR-003 Ghi log Giao dịch | Cập nhật log SMS với trạng thái giao | sms_logs |
5. Luồng Tích hợp
5.1 Luồng Giao SMS
Hình 1: Sơ đồ Sequence Giao SMS
5.2 Sự kiện Webhook
| Sự kiện | Hướng | Giao thức | Mô tả |
|---|
| verification.requested | Đầu vào (từ AUTH) | RabbitMQ | Nhận yêu cầu gửi SMS từ module AUTH |
| verification.delivered | Đầu ra (đến AUTH) | Webhook HTTP | Thông báo trạng thái giao SMS cho AUTH |
5.3 Dịch vụ Bên ngoài
| Dịch vụ | Giao thức | Mục đích |
|---|
| Twilio | REST API | Gửi tin nhắn SMS |
| Twilio | Webhook | Nhận callback trạng thái giao dịch |
6. Tóm tắt Truy suất
| Mã YC SRS | Yêu cầu | Phần TDS | Quyết định Thiết kế |
|---|
| FR-001 | Gửi SMS OTP | 2.2, 3.2 | Twilio + RabbitMQ bất đồng bộ |
| FR-002 | Xác minh OTP | 3.2 | SmsService.verifyOtp() |
| FR-003 | Ghi log Giao dịch SMS | 3.2, 5.1 | Bảng sms_logs + Twilio webhook |
| FR-004 | Truy vấn Trạng thái SMS | 3.2 | SmsService.getStatus() |
| NFR-001 | SMS < 3s | 2.1 | Bất đồng bộ qua RabbitMQ |
| NFR-002 | 99% giao thành công | 2.2 | Twilio + cơ chế thử lại |
| NFR-003 | OTP hết hạn 5 phút | 3.2 | Trường expires_at trong sms_logs |
| NFR-004 | Lưu trữ 90 ngày | 4.1 | Chính sách lưu trữ trong sms_db |
