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 زیر را وارد کنید:

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

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

SMS:

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

Email:

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

Telegram:

🔐 کد ورود شما: 31524

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

---

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

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

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

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 استفاده می‌کند:

# در 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):

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. تست با پیش‌نمایش:

{
  "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

---

پشتیبانی

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