docs/cms/email-sms-configuration.md

راهنمای پیکربندی Email و SMS

قالب‌های پیامک (SmsTemplates)

فایل: CMSMicroservice.Domain/Common/SmsTemplates.cs

همه قالب‌های پیامک در یک کلاس متمرکز شده‌اند:

public static class SmsTemplates
{
    // وام دایا
    public static string DayaLoanReceived(string? firstName, long amount)
        => $"{GetUserName(firstName)} عزیز، مبلغ {amount:N0} ریال وام دایا به کیف پول شما واریز شد. کارابازار";

    // فعال‌سازی باشگاه
    public static string ClubActivated(string? firstName)
        => $"{GetUserName(firstName)} عزیز، حساب باشگاه شما فعال شد. کارابازار";

    // خرید پکیج
    public static string PackagePurchased(string? firstName, string packageName)
        => $"{GetUserName(firstName)} عزیز، پکیج {packageName} با موفقیت خریداری شد. کارابازار";

    // واریز کمیسیون
    public static string CommissionDeposited(string? firstName, long amount)
        => $"{GetUserName(firstName)} عزیز، مبلغ {amount:N0} ریال کمیسیون به کیف پول شما واریز شد. کارابازار";

    // برداشت موفق
    public static string WithdrawalSuccess(string? firstName, long amount)
        => $"{GetUserName(firstName)} عزیز، درخواست برداشت {amount:N0} ریال با موفقیت انجام شد. کارابازار";

    // پیوستن به شبکه
    public static string NetworkJoined(string? firstName, string referrerName)
        => $"{GetUserName(firstName)} عزیز، به شبکه {referrerName} پیوستید. کارابازار";

    // زیرمجموعه جدید
    public static string NewDownline(string? firstName, string newMemberName)
        => $"{GetUserName(firstName)} عزیز، {newMemberName} به زیرمجموعه شما اضافه شد. کارابازار";

    // کد OTP
    public static string OtpCode(string code)
        => $"کد تأیید شما: {code}\nکارابازار";

    // خوش‌آمدگویی
    public static string Welcome(string? firstName)
        => $"{GetUserName(firstName)} عزیز، به کارابازار خوش آمدید!";
}

نحوه استفاده:

// تزریق سرویس
private readonly IKavenegarService _smsService;

// ارسال پیامک
var message = SmsTemplates.DayaLoanReceived(user.FirstName, 56_000_000);
await _smsService.SendAsync(user.PhoneNumber, message);

---

تنظیمات Email (Gmail)

مرحله 1: ایجاد App Password در Gmail

1. به Google Account Security بروید
2. گزینه "2-Step Verification" را فعال کنید
3. به بخش "App passwords" بروید
4. یک App Password جدید با نام "FourSat CMS" ایجاد کنید
5. پسورد 16 رقمی را در appsettings.Production.json در فیلد SmtpPassword قرار دهید

مرحله 2: تنظیم appsettings.Production.json

"Email": {
  "Enabled": true,
  "SmtpHost": "smtp.gmail.com",
  "SmtpPort": 587,
  "SmtpUsername": "your-email@gmail.com",  // ایمیل Gmail خود
  "SmtpPassword": "your-16-digit-app-password",  // App Password از مرحله 1
  "FromEmail": "noreply@foursat.com",  // ایمیل فرستنده (می‌تواند همان Gmail باشد)
  "FromName": "FourSat CMS",
  "EnableSsl": true
}

سایر سرویس‌های SMTP:

Outlook/Microsoft 365:

"SmtpHost": "smtp.office365.com",
"SmtpPort": 587

Yahoo Mail:

"SmtpHost": "smtp.mail.yahoo.com",
"SmtpPort": 587

---

تنظیمات SMS (کاوه نگار)

مرحله 1: ثبت‌نام در کاوه نگار

1. به Kavenegar.com بروید
2. ثبت‌نام کنید و حساب خود را تأیید کنید
3. از پنل، API Key خود را کپی کنید

مرحله 2: تنظیم appsettings.Production.json

"Sms": {
  "Enabled": true,
  "Provider": "Kavenegar",
  "KavenegarApiKey": "YOUR_KAVENEGAR_API_KEY",  // API Key از پنل کاوه نگار
  "Sender": "10008663"  // شماره ارسال‌کننده (از پنل کاوه نگار)
}

نکات مهم:

• شماره Sender باید از پنل کاوه نگار تهیه شود
• برای تست می‌توانید از شماره‌های رایگان استفاده کنید
• هزینه هر پیامک بسته به نوع خط متفاوت است

---

تست کردن

تست Email:

# در محیط Development
curl -X POST "http://localhost:5133/api/admin/trigger-weekly-calculation"

تست SMS:

همان دستور بالا را اجرا کنید. سیستم به صورت خودکار:

• Email ارسال می‌کند (اگر User.Email پر باشد)
• SMS ارسال می‌کند (اگر User.Mobile پر باشد)

بررسی Log ها:

# در ترمینال سرویس CMS
# پیام‌های زیر را مشاهده کنید:
# 📧 Email sent to {Email}: {Subject}
# 📱 SMS sent to {PhoneNumber}: {MessageId}

---

امنیت

⚠️ مهم:

1. فایل appsettings.Production.json را به Git اضافه نکنید
2. از Environment Variables یا Azure Key Vault استفاده کنید
3. API Key ها را هرگز در کد سورس قرار ندهید

استفاده از Environment Variables:

# Linux/Mac
export Email__SmtpPassword="your-app-password"
export Sms__KavenegarApiKey="your-api-key"

# Windows
set Email__SmtpPassword=your-app-password
set Sms__KavenegarApiKey=your-api-key

---

خطایابی (Troubleshooting)

Email ارسال نمی‌شود:

1. App Password را صحیح وارد کرده‌اید؟
2. 2-Step Verification در Gmail فعال است؟
3. Port 587 باز است؟
4. EnableSsl: true تنظیم شده؟

SMS ارسال نمی‌شود:

1. API Key صحیح است؟
2. اعتبار حساب کاوه نگار کافی است؟
3. شماره Sender معتبر است؟
4. فرمت شماره موبایل صحیح است؟ (09xxxxxxxxx)

Log ها را بررسی کنید:

tail -f /tmp/cms_run.log