# مشخصات درس‌نامه: ارسال ایمیل‌های تراکنشی و نوتیفیکیشن با پروتکل SMTP و ایمیل‌سرور لیارا
- **شناسه در سیلابس:** `L10.5`
- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
- **پیش‌نیازهای مستقیم:** `L10.4` (اتصال وب‌سرویس پیامک بومی)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** تفاوت ایمیل‌های تراکنشی سیستمی (Transactional Emails نظیر رسید، تایید رزرو مشاوره و ارسال فایل رزومه) را با ایمیل‌های انبوه تبلیغاتی (Marketing Emails) شرح دهد.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** پروتکل استاندارد SMTP را با وب‌سرویس‌های HTTP ارسال ایمیل مقایسه کرده و نقش رکوردهای امنیتی دامنه (SPF و DKIM) را در جلوگیری از اسپم شدن ایمیل‌ها ارزیابی کند.
- [ ] **به‌کار ببندد (Apply):** یک سرویس ایمیل‌سرور ابری بر بستر پلتفرم لیارا (Liara Mail Server) راه‌اندازی کرده و با کتابخانه `nodemailer` در Next.js به آن متصل شود.
- [ ] **ایجاد کند (Create):** یک قالب ایمیل راست‌چین (RTL) مدرن، واکنش‌گرا و سازگار با اینباکس‌های مختلف برای تایید ثبت درخواست کارفرما طراحی و ارسال کند.

---

## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)

### آنچه باید پوشش داده شود (In-Scope):
1. **ایمیل تراکنشی چیست و چرا پیامک به تنهایی کافی نیست؟**
   * پیامک کوتاه و فوری است؛ اما ایمیل رسمی، حاوی پیوست‌های PDF، فاکتور، متن‌های طولانی و لینک‌های قابل کلیک است.
2. **اصول پروتکل ارسال ایمیل (SMTP - Simple Mail Transfer Protocol):**
   * هاست سرور (`Host`)، درگاه امن (`Port` معمولاً ۵۸۷ یا ۴۶۵)، نام کاربری و رمز عبور اختصاصی.
3. **راه‌اندازی سرویس ایمیل‌سرور بومی در پلتفرم لیارا (Liara.ir):**
   * ساخت اکانت ایمیل‌سرور در پنل لیارا، دریافت مشخصات SMTP و معرفی آدرس فرستنده مجاز.
4. **پیاده‌سازی ماژول ارسال ایمیل در Next.js با Nodemailer:**
   * نصب پکیج `nodemailer` و تعریف کلاینت `transporter` در `services/email.ts`.
   * طراحی تابع ارسال ایمیل با قابلیت پذیرش موضوع، گیرنده و متن HTML.
5. **طراحی قالب ایمیل زیبا و راست‌چین (RTL Email Template):**
   * چالش‌های نرم‌افزارهای نمایش ایمیل (Gmail, Outlook) و چرایی استفاده از استایل‌های درون‌خطی (Inline Styles).
   * ساخت یک قالب شکیل با فونت فارسی و پالت پورتفولیو برای ارسال پیام تایید و پیوست رزومه PDF.
6. **پشتیبانی از شبیه‌ساز محلی (Dev Fallback):**
   * استفاده از حساب تستی Nodemailer (Ethereal Email) یا چاپ متن در کنسول در صورت نبود دسترسی به ایمیل‌سرور.
7. **دستورات چندسکویی برای نصب پکیج‌ها و تنظیمات محیطی:**
   * نصب `nodemailer` و تایپ‌های آن در منوهای کشویی ویندوز، مک و لینوکس.
8. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): مفهوم رکوردهای SPF و DKIM در DNS دامنه و اثر آن‌ها بر عبور از فیلتر اسپم گوگل و مایکروسافت.
   * کال‌اوت سبز (`<details class="green">`): پکیج رایگان آغازین ایمیل لیارا برای تست‌های دانشجویی بدون هزینه.
   * کال‌اوت قرمز (`<details class="red">`): ممنوعیت مطلق ارسال ایمیل‌های تبلیغاتی انبوه از طریق پورت‌های تراکنشی و خطر مسدود شدن سرور.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- طراحی کمپین‌های خبرنامه و ایمیل مارکتینگ انبوه (Mailchimp).
- جزییات پیکربندی پیشرفته سرورهای اختصاصی لینوکس Postfix/Exim.

---

## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Transactional Email | ایمیل تراکنشی | ایمیل اختصاصی که بلافاصله در پاسخ به اقدام خاص کاربر در سیستم (ثبت‌نام، رزرو، خرید) ارسال می‌شود |
| SMTP | پروتکل انتقال ساده نامه‌نگاری | پروتکل استاندارد اینترنت برای هدایت و ارسال بسته‌های نامه‌های الکترونیک میان سرورها |
| Nodemailer | کتابخانه نودمیلر | ماژول محبوب و استاندارد محیط Node.js برای اتصال به سرورهای ایمیل و ارسال پیام‌های غنی |
| SPF (Sender Policy Framework) | چارچوب سیاست فرستنده | رکورد DNS که مشخص می‌کند کدام سرورها مجاز به ارسال ایمیل از سمت دامنه شما هستند |
| DKIM | کلیدهای شناسایی دامنه | امضای دیجیتال رمزنگاری‌شده در هدر ایمیل برای تضمین عدم دستکاری متن در مسیر ارسال |
| Inline Styling | استایل‌دهی درون‌خطی | نوشتن کدهای CSS در ویژگی `style` المان‌ها به دلیل محدودیت نرم‌افزارهای کلاینت ایمیل |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** نامه الکترونیکی با مهر طلایی تایید که از سرور ابری ایمیل خارج شده و در اینباکس یک کارفرما فرود می‌آید.
2. **جریان ارسال ایمیل از پورتفولیو تا اینباکس کاربر:** `images/smtp-email-delivery-flow.png`
   * **موضوع:** دیاگرام معماری: کاربر فرم رزرو را پر می‌کند $\rightarrow$ سرور پورتفولیو $\rightarrow$ اتصال به SMTP سرور لیارا $\rightarrow$ انتقال از طریق اینترنت به جیمیل کارفرما.
3. **پیش‌نمایش قالب ایمیل راست‌چین طراحی‌شده:** `images/rtl-email-template-preview.png`
   * **موضوع:** اسکرین‌شات از قالب ایمیل تایید رزرو در اپلیکیشن Gmail با دکمه بنفش، متن خوانای فارسی، و لوگوی صاحب پورتفولیو.
4. **تفاوت ارسال مستقیم با ارسال تأییدشده توسط SPF/DKIM:** `images/email-deliverability-passports.png`
   * **موضوع:** اینفوگرافیک مقایسه‌ای: ایمیل بدون رکورد به پوشه هرزنامه (Spam) می‌رود؛ ایمیل با رکوردهای معتبر مستقیماً در صندوق ورودی (Inbox) قرار می‌گیرد.

---

## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)

1. **تیتر اصلی:** `# ارسال ایمیل‌های تراکنشی و نوتیفیکیشن با پروتکل SMTP و ایمیل‌سرور لیارا`
2. **مقدمه:** چگونه پس از ثبت پیام یا درخواست مشاوره، یک ایمیل فوق‌العاده شیک با برند شخصی به اینباکس کارفرما بفرستیم؟
3. **جدول کاور درس**
4. **استعاره نامه رسمی سربرگ‌دار در برابر پیامک دوخطی:**
   * چرا ایمیل‌های تراکنشی هویت و پرستیژ حرفه‌ای محصول شما را بالا می‌برند.
5. **معرفی و راه‌اندازی ایمیل‌سرور ابری لیارا (Liara Mail Server):**
   * ساخت اکانت، ساخت ایمیل‌سرور و دریافت اطلاعات اتصال: Host, Port, User, Password.
6. **نصب و پیکربندی Nodemailer در پروژه Next.js:**
   * دستورات نصب پکیج‌ها در سه سیستم‌عامل.
   * کد تمیز ماژول `services/email.ts` با مدیریت ارور و مکانیزم شبیه‌ساز لوکال.
7. **هنر طراحی قالب‌های ایمیل HTML با چیدمان راست‌چین (RTL):**
   * چرا کدهای مدرن مثل Grid یا CSS خارجی در ایمیل کار نمی‌کنند؟ استفاده از Table Layout و Inline CSS.
8. **جعبه پرامپت طلایی: ساخت قالب ایمیل داینامیک و اتصال به فرم با ایجنت:**
   * پرامپت دقیق:
     > «من یک فایل `services/email.ts` با Nodemailer دارم. لطفاً یک قالب ایمیل HTML بسیار زیبا و راست‌چین برای تایید درخواست مشاوره در پورتفولیو بساز که شامل نام کارفرما، موضوع درخواست و زمان ثبت باشد. استایل‌ها باید به صورت Inline نوشته شوند و رنگ دکمه با تم بنفش سایت همخوانی داشته باشد.»
9. **دستورات چندسکویی برای نصب Nodemailer و متغیرهای محیطی:**
   * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
     - Windows (PowerShell):
       ```powershell
       npm install nodemailer
       npm install -D @types/nodemailer
       Add-Content .env.local "`nSMTP_HOST=smtp.c1.liara.email`nSMTP_PORT=587`nSMTP_USER=your_user`nSMTP_PASS=your_pass"
       ```
     - macOS (Terminal):
       ```bash
       npm install nodemailer
       npm install -D @types/nodemailer
       echo -e "\nSMTP_HOST=smtp.c1.liara.email\nSMTP_PORT=587\nSMTP_USER=your_user\nSMTP_PASS=your_pass" >> .env.local
       ```
     - Linux (Bash):
       ```bash
       npm install nodemailer
       npm install -D @types/nodemailer
       echo -e "\nSMTP_HOST=smtp.c1.liara.email\nSMTP_PORT=587\nSMTP_USER=your_user\nSMTP_PASS=your_pass" >> .env.local
       ```
10. **باکس نکته Quera (`<details class="violet">`):** نقش گذرنامه‌های سه‌گانه ایمیل (SPF، DKIM و DMARC) در رسیدن صددرصدی ایمیل به اینباکس اصلی جیمیل و جلوگیری از پوشه Spam.
11. **باکس هشدار Quera (`<details class="red">`):** هرگز از هاست ایمیل اشتراکی برای ارسال ایمیل به هزاران نفر همزمان استفاده نکنید؛ سرور شما در لیست سیاه جهانی مسدود خواهد شد.
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** تست ارسال ایمیل و دیدن نوتیفیکیشن دریافت ایمیل روی کامپیوتر یا گوشی در کمتر از ۳ ثانیه.
13. **جمع‌بندی درس‌نامه:** تکمیل کانال ایمیل؛ ورود به دنیای هیجان‌انگیز ارائه‌دهندگان احراز هویت خارجی (Google, GitHub و لاگین پیامکی) در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] تفاوت ایمیل‌های تراکنشی با ایمیل‌های تبلیغاتی تبیین گردد.
- [ ] راه‌اندازی و استفاده از سرور SMTP لیارا به همراه کتابخانه Nodemailer آموزش داده شود.
- [ ] اصول ساخت قالب‌های HTML ایمیل راست‌چین (RTL) با کدهای استاندارد توضیح داده شود.
- [ ] تنظیمات متغیرهای محیطی و نصب پکیج‌ها در تب‌های چندسکویی ارائه شود.