125 lines
13 KiB
Markdown
125 lines
13 KiB
Markdown
# مشخصات درس‌نامه: ارسال ایمیل‌های تراکنشی و نوتیفیکیشن با پروتکل 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) با کدهای استاندارد توضیح داده شود.
|
||
- [ ] تنظیمات متغیرهای محیطی و نصب پکیج‌ها در تب‌های چندسکویی ارائه شود.
|