docs/archive/03-BACKEND/CMS/email-sms-configuration.md

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

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

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

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

```csharp
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)} عزیز، به کارابازار خوش آمدید!";
}
```

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

```csharp
// تزریق سرویس
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](https://myaccount.google.com/security) بروید
2. گزینه "2-Step Verification" را فعال کنید
3. به بخش "App passwords" بروید
4. یک App Password جدید با نام "FourSat CMS" ایجاد کنید
5. پسورد 16 رقمی را در `appsettings.Production.json` در فیلد `SmtpPassword` قرار دهید

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

```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:
```json
"SmtpHost": "smtp.office365.com",
"SmtpPort": 587
```

#### Yahoo Mail:
```json
"SmtpHost": "smtp.mail.yahoo.com",
"SmtpPort": 587
```

---

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

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

1. به [Kavenegar.com](https://panel.kavenegar.com/client/membership/register) بروید
2. ثبت‌نام کنید و حساب خود را تأیید کنید
3. از پنل، API Key خود را کپی کنید

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

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

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

---

## تست کردن

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

### تست SMS:
همان دستور بالا را اجرا کنید. سیستم به صورت خودکار:
- Email ارسال می‌کند (اگر User.Email پر باشد)
- SMS ارسال می‌کند (اگر User.Mobile پر باشد)

### بررسی Log ها:
```bash
# در ترمینال سرویس 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:

```bash
# 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 ها را بررسی کنید:
```bash
tail -f /tmp/cms_run.log
```