arc/docs/NOTIFICATION_TEMPLATES_OTP_GUIDE.md

# راهنمای کامل: ایجاد و استفاده از قالب ناتیفیکیشن برای ورود با OTP

## خلاصه
این راهنما به شما نشان می‌دهد چطور قالب‌های ناتیفیکیشن را برای سیستم ورود با OTP ایجاد کنید و پارامترها را خودکار جایگزین کنید.

---

## مرحله 1: ایجاد قالب‌های ناتیفیکیشن در پنل ادمین

### 1.1 قالب برای SMS

1. وارد پنل ادمین شوید
2. به بخش **تنظیمات سیستم > قالب‌های ناتیفیکیشن** بروید
3. روی **"ایجاد قالب جدید"** کلیک کنید
4. مقادیر زیر را وارد کنید:

```
کلید رویداد: auth.otp_login
کانال: sms
زبان: fa (یا خالی بگذارید)
موضوع: (خالی بگذارید - SMS موضوع ندارد)
محتوا: 
کد ورود یک بار مصرف شما: {{ code }}
این کد تا {{ expiry_minutes }} دقیقه اعتبار دارد.
وضعیت: فعال ✓
```

5. روی **"ذخیره"** کلیک کنید

### 1.2 قالب برای Email

1. قالب جدید دیگری ایجاد کنید:

```
کلید رویداد: auth.otp_login
کانال: email
زبان: fa (یا خالی بگذارید)
موضوع: کد ورود به حساب کاربری
محتوا: 
سلام،

کد ورود یک بار مصرف شما: {{ code }}

این کد تا {{ expiry_minutes }} دقیقه اعتبار دارد.

اگر شما این درخواست را نکرده‌اید، لطفاً این ایمیل را نادیده بگیرید.

با تشکر
تیم حاسبیکس
وضعیت: فعال ✓
```

### 1.3 قالب برای Telegram

1. قالب جدید دیگری ایجاد کنید:

```
کلید رویداد: auth.otp_login
کانال: telegram
زبان: fa (یا خالی بگذارید)
موضوع: (خالی بگذارید)
محتوا: 
🔐 کد ورود شما: {{ code }}

⏰ اعتبار: {{ expiry_minutes }} دقیقه
وضعیت: فعال ✓
```

---

## مرحله 2: تست قالب با پیش‌نمایش

1. در صفحه ویرایش قالب، روی **"پارامترهای پیش‌نمایش"** کلیک کنید
2. JSON زیر را وارد کنید:

```json
{
  "code": "31524",
  "expiry_minutes": 5
}
```

3. روی **"پیش‌نمایش قالب"** کلیک کنید
4. باید نتیجه زیر را ببینید:

**SMS:**
```
کد ورود یک بار مصرف شما: 31524
این کد تا 5 دقیقه اعتبار دارد.
```

**Email:**
- **موضوع:** کد ورود به حساب کاربری
- **محتوا:** (همان متن بالا با جایگزینی پارامترها)

**Telegram:**
```
🔐 کد ورود شما: 31524

⏰ اعتبار: 5 دقیقه
```

---

## مرحله 3: چگونه سیستم پارامترها را خودکار جایگزین می‌کند؟

### 3.1 پارامترهای موجود در Context

وقتی سیستم OTP ارسال می‌کند، این پارامترها را به قالب می‌فرستد:

```python
context = {
    "code": otp_code,        # کد OTP (مثلاً "31524")
    "expiry_minutes": 5,     # مدت اعتبار به دقیقه
}
```

### 3.2 نحوه استفاده در قالب

در قالب‌های Jinja2، از `{{ نام_پارامتر }}` استفاده کنید:

```
کد ورود شما: {{ code }}
```

وقتی سیستم این قالب را رندر می‌کند:
- `{{ code }}` → `31524`
- `{{ expiry_minutes }}` → `5`

### 3.3 مثال‌های بیشتر

**مثال 1: استفاده از چند پارامتر**
```
کد ورود شما: {{ code }}
این کد تا {{ expiry_minutes }} دقیقه معتبر است.
```

**مثال 2: با فرمت بهتر**
```
🔐 کد ورود: {{ code }}

⏰ اعتبار: {{ expiry_minutes }} دقیقه

💡 نکته: این کد فقط یک بار قابل استفاده است.
```

---

## مرحله 4: کد Backend (تغییرات انجام شده)

کد Backend قبلاً تغییر کرده و از `NotificationService` استفاده می‌کند:

```python
# در OtpLoginService.send_login_otp()

context = {
    "code": otp_code,
    "expiry_minutes": 5,
}

self.notification_service.send(
    user_id=user.id,
    event_key="auth.otp_login",
    context=context,
    preferred_channels=[channel],
    locale="fa"
)
```

سیستم به صورت خودکار:
1. قالب مناسب را پیدا می‌کند (بر اساس `event_key` و `channel`)
2. پارامترها را در قالب جایگزین می‌کند
3. ناتیفیکیشن را ارسال می‌کند

---

## مرحله 5: افزودن پارامترهای بیشتر (اختیاری)

### 5.1 اگر می‌خواهید پارامترهای بیشتری اضافه کنید:

1. **در Backend** (مثلاً در `otp_login_service.py`):

```python
context = {
    "code": otp_code,
    "expiry_minutes": 5,
    "user_name": user.first_name + " " + user.last_name,  # پارامتر جدید
    "ip_address": ip_address,  # پارامتر جدید
}
```

2. **در قالب** می‌توانید استفاده کنید:

```
سلام {{ user_name }}،

کد ورود شما: {{ code }}

این درخواست از IP: {{ ip_address }} انجام شده است.
```

3. **تست با پیش‌نمایش:**

```json
{
  "code": "31524",
  "expiry_minutes": 5,
  "user_name": "علی احمدی",
  "ip_address": "192.168.1.1"
}
```

---

## نکات مهم

### ✅ نکات:
- نام پارامترها در قالب باید دقیقاً با نام پارامترها در `context` یکسان باشد
- از `{{ }}` برای جایگزینی پارامترها استفاده کنید
- می‌توانید قالب‌های مختلف برای زبان‌های مختلف ایجاد کنید (locale)

### ⚠️ نکات امنیتی:
- هرگز اطلاعات حساس (مثل OTP) را در لاگ‌ها ذخیره نکنید
- از `SandboxedEnvironment` در Jinja2 استفاده می‌شود برای امنیت

### 🔧 Fallback:
اگر قالب پیدا نشود یا خطا رخ دهد، سیستم به صورت خودکار از پیام پیش‌فرض استفاده می‌کند:
```
کد ورود شما: {otp_code}
این کد تا 5 دقیقه اعتبار دارد.
```

---

## مرجع سریع: پارامترهای پیش‌فرض OTP

| پارامتر | نوع | توضیحات | مثال |
|---------|-----|---------|------|
| `code` | string | کد OTP 6 رقمی | `"31524"` |
| `expiry_minutes` | number | مدت اعتبار به دقیقه | `5` |

---

## پشتیبانی

اگر مشکلی داشتید یا سوالی دارید، لطفاً با تیم توسعه تماس بگیرید.