feat: add chapter 10-external-services specs

chapters/10-external-services/04-lesson-transactional-email-with-smtp/spec.md

@@ -0,0 +1,124 @@
+# مشخصات درس‌نامه: ارسال ایمیل‌های تراکنشی و نوتیفیکیشن با پروتکل 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) با کدهای استاندارد توضیح داده شود.
+- [ ] تنظیمات متغیرهای محیطی و نصب پکیج‌ها در تب‌های چندسکویی ارائه شود.