vibe-coding-college-specs/chapters/10-external-services/04-lesson-transactional-email-with-smtp/spec.md

مشخصات درس‌نامه: ارسال ایمیل‌های تراکنشی و نوتیفیکیشن با پروتکل 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):

       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):

       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):

       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) با کدهای استاندارد توضیح داده شود.
• تنظیمات متغیرهای محیطی و نصب پکیج‌ها در تب‌های چندسکویی ارائه شود.