Gửi SMS

govex-cloud-sms là khung gửi SMS theo provider: cấu hình dịch vụ trong bảng setting, chọn mẫu tin nhắn theo loại, gửi bất đồng bộ qua event và lưu vết kết quả gửi vào bảng sms_send_record.

Khi nào sử dụng

• Service cần gửi SMS giao dịch như OTP xác thực, cảnh báo, thông báo trạng thái.
• Muốn quản lý provider và mẫu tin nhắn theo loại trong database thay vì hard-code trong code.
• Cần lưu vết nội dung, trạng thái gửi và kết quả trả về của từng tin nhắn.

Cài đặt

Thêm dependency vào pom.xml — không khai version vì đã được quản lý qua BOM:

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-sms</artifactId>
</dependency>

Nếu ứng dụng chưa dùng parent/BOM của Govex Cloud, xem hướng dẫn tại Cài đặt.

Cấu hình

Cấu hình provider nằm trong bảng setting của govex-cloud-config:

Key setting	Nội dung	Ghi chú
govex.message.setting.sms_provider	JSON cấu hình gửi SMS	Gồm provider (hiện có VIETTEL), language, config (JSON riêng theo provider) và templates — danh sách {type, code} ánh xạ loại SMS sang mã template của provider

• Giá trị được serialize kèm thông tin @class của từng object; bản ghi tạo thủ công cần giữ đúng định dạng này để dependency deserialize được.
• Cấu hình có thể lưu/tắt qua SmsSettingService (saveSmsProviderConfig, disableSmsProvider, getSmsProviderConfig) và được áp dụng ngay khi refresh.

Sử dụng

Khai báo loại SMS bằng cách implement SmsType:

public enum OtpSmsType implements SmsType {

    OTP_VERIFICATION("OTP_VERIFICATION", "Xác thực OTP");

    private final String code;
    private final String desc;

    OtpSmsType(String code, String desc) {
        this.code = code;
        this.desc = desc;
    }

    @Override public String getCode() { return code; }
    @Override public String getDesc() { return desc; }
}

Gửi SMS qua SmsMsgEventPublish — tham số truyền vào là LinkedHashMap và trở thành biến cho template của provider:

@Service
@RequiredArgsConstructor
public class OtpService {

    private final SmsMsgEventPublish smsMsgEventPublish;

    public void sendOtp(String phone, String otp) {
        LinkedHashMap<String, String> params = new LinkedHashMap<>();
        params.put("otp", otp);
        smsMsgEventPublish.publish(OtpSmsType.OTP_VERIFICATION, phone, params);
    }
}

• publish tra cứu templates trong cấu hình theo type; không tìm thấy sẽ ném SMS_TEMPLATE_NOT_CONFIGURED.
• Số điện thoại trống thì bỏ qua và ghi log cảnh báo.
• Việc gửi chạy bất đồng bộ; kết quả được ghi vào sms_send_record gồm số điện thoại, nội dung, loại, provider, trạng thái thành công và kết quả trả về.

Lưu ý

• Dependency hiện là khung tích hợp, chưa có provider gửi thật: chưa có triển khai SmsProviderSend cho VIETTEL, nên khi đã cấu hình provider thao tác gửi sẽ lỗi SMS_PROVIDER_UNSUPPORTED. Cần bổ sung implementation cho provider trước khi dùng thực tế.
• SmsSettingService.saveSmsProviderConfig hiện chưa lưu được cấu hình ở bản này — cần tạo sẵn bản ghi setting govex.message.setting.sms_provider (hoặc chờ xử lý) trước khi gửi.
• Auto-configuration chỉ component scan converter, mapper, service; listener gửi SMS nằm ngoài phạm vi đó. Ứng dụng host cần thêm vn.govex.cloud.sms vào component scan để listener được đăng ký và xử lý event.
• Cần có govex-cloud-config (bảng setting), govex-cloud-data-jpa; bảng sms_send_record phải tồn tại trước khi dùng.
• Việc gửi chạy @Async nên phụ thuộc cấu hình async của ứng dụng host.