diff --git a/chapters/10-external-services/00-lesson-chapter-goals/spec.md b/chapters/10-external-services/00-lesson-chapter-goals/spec.md new file mode 100644 index 0000000..6bd3549 --- /dev/null +++ b/chapters/10-external-services/00-lesson-chapter-goals/spec.md @@ -0,0 +1,85 @@ +# مشخصات درس‌نامه: اهداف فصل دهم (Chapter Goals) +- **شناسه در سیلابس:** `L10.1` +- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۵ دقیقه +- **پیش‌نیازهای مستقیم:** `L9.6` (دیباگ تعاملی با ایجنت و حل خطاهای متداول) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** چرا هیچ محصول مدرنی از صفر تمام چرخ‌ها را اختراع نمی‌کند و چگونه سرویس‌های بیرونی (Third-party Services) اپلیکیشن شما را به دنیای واقعی متصل می‌کنند. +- [ ] **درک کند (Understand):** نقشه راه ۸ درس‌نامه این فصل شامل: آشنایی با اکوسیستم سرویس‌ها، خواندن مستندات فنی و مدیریت Secretها، ارسال پیامک بومی (کاوه‌نگار و SMS.ir)، ارسال ایمیل‌های تراکنشی با SMTP لیارا، ارائه‌دهندگان احراز هویت (Google/GitHub و ورود پیامکی)، درگاه پرداخت آنلاین (زرین‌پال در حالت سندباکس)، و اتصال مدل‌های هوش مصنوعی (OpenRouter / AvalAI). +- [ ] **تحلیل/ارزیابی کند (Evaluate):** ارزش اقتصادی و سرعت توسعه ناشی از اتصال APIهای آماده در مقایسه با ساخت پرهزینه زیرساخت‌های پیامک، ایمیل و مالی را ارزیابی نماید. +- [ ] **به‌کار ببندد (Apply):** پورتفولیوی شخصی را از یک ویترین ایزوله به یک سیستم زنده مجهز به چت‌بات هوش مصنوعی، دریافت نوتیفیکیشن تماس پیامکی و دریافت هزینه مشاوره تبدیل کند. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **خروج از جزیره محلی و اتصال به شاهراه‌های اینترنت:** + * نرم‌افزار بدون ارتباط با سرویس‌های مالی، ارتباطی و هویتی، جزیره‌ای دورافتاده است. +2. **مرور ۸ ایستگاه تخصصی فصل دهم:** + * درس ۱۰.۲: سرویس شخص ثالث چیست؟ (مزایا، معماری درخواست به سرورهای ثالث و صرفه‌جویی در هزینه‌ها). + * درس ۱۰.۳: رمزگشایی از مستندات APIها و اصول نگهداری کلیدهای محرمانه و اعتبارسنجی (API Keys & Credentials). + * درس ۱۰.۴: یکپارچه‌سازی وب‌سرویس پیامک بومی (ارسال خودکار پیامک اطلاع‌رسانی با کاوه‌نگار و پترن‌های خدماتی SMS.ir). + * درس ۱۰.۵: ارسال ایمیل‌های تراکنشی و نوتیفیکیشن با ایمیل‌سرور و پروتکل SMTP (استفاده از سرویس ابری لیارا). + * درس ۱۰.۶: اتصال ارائه‌دهندگان احراز هویت خارجی (ورود با یک کلیک از طریق Google و GitHub در Supabase + معماری ورود با پیامک OTP). + * درس ۱۰.۷: اتصال درگاه پرداخت آنلاین ایرانی (پیاده‌سازی درگاه پرداخت زرین‌پال در محیط سندباکس تستی برای فروش مشاوره یا فایل رزومه). + * درس ۱۰.۸: تزریق مغز متفکر هوش مصنوعی (اتصال API مدل‌های LLM از طریق OpenRouter یا سرویس‌های در دسترس به چت‌بات رزومه). +3. **هم‌راستایی کامل با نیازها و زیرساخت‌های بومی ایران:** + * تأکید بر سرویس‌های پایدار و در دسترس داخلی در کنار استانداردهای بین‌المللی API. +4. **دستورات چندسکویی و پیکربندی متغیرهای محیطی:** + * منوهای کشویی ویندوز، مک و لینوکس برای تنظیم متغیرها در فایل‌های محیطی. +5. **کال‌اوت‌های کوئرا:** + * کال‌اوت سبز (`
`): انگیزه و هیجان از اینکه پروژه با اولین تراکنش مالی یا اولین پیامک، جان می‌گیرد. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- جزییات پیشرفته امنیت، Rate Limiting و جلوگیری از حملات DDOS به اندپوینت‌ها (فصل ۱۱). +- استقرار واقعی روی سرورهای ابری و ست کردن دامنه اینترنتی (فصل ۱۲). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Third-party Service | سرویس شخص ثالث | پلتفرم‌ها و شرکت‌های مستقلی که خدمات تخصصی (پیامک، پرداخت، ایمیل) را از طریق API ارائه می‌دهند | +| API Key | کلید رابط برنامه‌نویسی | رشته کدی اختصاصی و محرمانه که هویت پروژه شما را نزد ارائه‌دهنده سرویس تأیید می‌کند | +| Sandbox Environment | محیط شبیه‌ساز / سندباکس | فضای امن و تستی ارائه‌دهندگان خدمات برای آزمایش بدون نیاز به تبادل پول واقعی یا ارسال پیامک واقعی | +| Transactional Email | ایمیل تراکنشی | ایمیل‌های سیستمی و فوری نظیر تایید خرید، فاکتور و رزرو که به یک رفتار کاربر پاسخ می‌دهند | +| Payment Gateway | درگاه پرداخت الکترونیک | پلی امن میان فروشگاه اینترنتی، شاپرک و شبکه بانکی برای انتقال وجوه | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** نمایش دیجیتال یک برنامه مرکزی که مانند یک نیروگاه، با کابل‌های نئونی به آیکون‌های پیامک، ایمیل، کارت بانکی، احراز هویت و هوش مصنوعی متصل شده است. +2. **نقشه راه جامع فصل ۱۰:** `images/chapter-10-roadmap.png` + * **موضوع:** اینفوگرافیک ۸ مرحله‌ای فصل ۱۰ با نمادهای کاوه‌نگار، لیارا، زرین‌پال، سوپابیس و OpenRouter. +3. **اکوسیستم اتصال محصول به دنیای واقعی:** `images/product-ecosystem-connectivity.png` + * **موضوع:** دیاگرام معماری جریان داده: کاربر روی پورتفولیو دکمه رزرو را می‌زند $\rightarrow$ زرین‌پال پول می‌گیرد $\rightarrow$ کاوه‌نگار پیامک می‌فرستد $\rightarrow$ لیارا ایمیل می‌زند $\rightarrow$ چت‌بات پاسخ می‌دهد. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# اهداف فصل دهم: اتصال سرویس‌های بیرونی؛ بخشیدن جان و ارتباط به محصول` +2. **مقدمه کوتاه:** چرا نرم‌افزاری که به سرویس‌های واقعی متصل نباشد، شبیه یک خودروی بدون بنزین در پارکینگ است؟ +3. **جدول کاور درس** +4. **سرفصل‌های طلایی فصل در یک نگاه:** مرور ۸ ایستگاه تخصصی فصل. +5. **جدول نقشه راه یادگیری فصل** +6. **معرفی قهرمانان بومی و جهانی این فصل:** کاوه‌نگار، SMS.ir، ایمیل سرور لیارا، زرین‌پال، سوپابیس و OpenRouter. +7. **پورتفولیوی شخصی در نقش محصول تجاری:** چگونه این قابلیت‌ها باعث می‌شوند کارفرمایان پروژه شما را بسیار فراتر از یک سایت ساده ببینند. +8. **کال‌اوت روحیه‌بخش Quera (`
`):** لمس جادوی اتصال به درگاه پرداخت و دریافت پیامک واقعی روی موبایل شخصی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] دورنمای فصل ۱۰ و مزایای استفاده از سرویس‌های شخص ثالث تبیین شود. +- [ ] سرفصل‌های ۸ درس‌نامه بعدی با ذکر نام سرویس‌های بومی مصوب (کاوه‌نگار، لیارا، زرین‌پال) معرفی شوند. +- [ ] ارزش تجاری و فنی یادگیری این فصل در ساخت MVPهای مقیاس‌پذیر به صورت روشن بیان گردد. diff --git a/chapters/10-external-services/01-lesson-what-are-third-party-services/spec.md b/chapters/10-external-services/01-lesson-what-are-third-party-services/spec.md new file mode 100644 index 0000000..08fd25b --- /dev/null +++ b/chapters/10-external-services/01-lesson-what-are-third-party-services/spec.md @@ -0,0 +1,96 @@ +# مشخصات درس‌نامه: سرویس Third-Party چیست و چرا نباید چرخ را از نو بسازیم؟ +- **شناسه در سیلابس:** `L10.2` +- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۲ دقیقه +- **پیش‌نیازهای مستقیم:** `L10.1` (اهداف فصل دهم) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** مفهوم سرویس‌های شخص ثالث (Third-Party Services) و فلسفه استفاده از قطعات آماده نرم‌افزاری (Lego-Bricks Architecture) را در توسعه پرسرعت محصول شرح دهد. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** دوراهی ساختن در برابر خریدن/استفاده از سرویس آماده (Build vs Buy) را از منظر هزینه مالی، زمان عرضه به بازار (Time to Market) و الزامات قانونی مقایسه کند. +- [ ] **درک کند (Understand):** چرا درخواست به سرویس‌های حساس شخص ثالث (پیامک، پرداخت، مدل‌های زبانی) حتماً باید از طریق سرور (Next.js Server Actions / Route Handlers) انجام شود تا کلیدهای محرمانه فاش نشوند. +- [ ] **به‌کار ببندد (Apply):** معماری کلی ارتباط پروژه پورتفولیو با سرویس‌های ارتباطی، مالی و هوش مصنوعی را روی نمودار جریان سیستم رسم و پیاده نماید. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **استعاره کارخانه لگو در برابر ساخت پلاستیک از نفت خام:** + * توسعه‌دهنده مدرن کارخانه‌دار نیست؛ یک معمار زبردست است که قطعات باکیفیت و تخصصی را کنار هم می‌چیند. +2. **کالبدشکافی دوراهی استراتژیک ساخت یا خرید (Build vs Buy):** + * برای ارسال پیامک: بستن قرارداد با اپراتورها، راه‌اندازی دکل، مجوزهای مخابراتی (چند ماه و صدها میلیون تومان) در برابر ثبت‌نام ۲ دقیقه‌ای در کاوه‌نگار یا SMS.ir. + * برای پرداخت: راه‌اندازی سرور اختصاصی، دریافت نماد اعتماد و پروتکل‌های شاپرک در برابر اتصال سندباکس زرین‌پال در چند خط کد. +3. **دسته‌بندی اصلی سرویس‌های ابری در دنیای وب مدرن:** + * سرویس‌های ارتباطی و نوتیفیکیشن (Communication: SMS & Email). + * سرویس‌های مالی و درگاه‌های پرداخت (Fintech: Payment Gateways). + * سرویس‌های هویتی و دسترسی (Identity & OAuth: Google, GitHub). + * سرویس‌های ابری داده و فایل (BaaS: Supabase Database & Storage). + * سرویس‌های هوش مصنوعی زاینده (AI Model APIs: OpenAI, OpenRouter, AvalAI). +4. **جریان فنی تبادل داده با سرویس‌های بیرونی:** + * مرورگر کاربر دکمه را می‌زند $\rightarrow$ درخواست امن به سرور پروژه شما می‌رسد $\rightarrow$ سرور شما کلید اختصاصی را الصاق کرده و به سرور سرویس ثالث می‌فرستد $\rightarrow$ پاسخ JSON دریافت و وضعیت کاربر آپدیت می‌شود. +5. **معماری امنیت: سرور امن در برابر مرورگر ناامن:** + * چرا نباید کلیدهای پرداخت یا پیامک مستقیماً در کدهای کلاینت جاوااسکریپت قرار گیرند. +6. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم وب‌هوک (Webhook)؛ وقتی سرویس خارجی به سرور شما اطلاع‌رسانی معکوس می‌کند. + * کال‌اوت سبز (`
`): محیط‌های رایگان و اعتبارهای هدیه آغازین سرویس‌های بومی و بین‌المللی برای تست. + * کال‌اوت قرمز (`
`): وابستگی انحصاری (Vendor Lock-in) و اهمیت جداسازی کد از سرویس با لایه واسط (Adapter Pattern). + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- نوشتن کدهای تفصیلی ارسال پیامک یا پرداخت (درس‌های ۱۰.۴ و ۱۰.۷). +- معماری مایکروسرویس‌های توزیع‌شده سازمانی (فصل ۱۶). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Third-Party Integration | یکپارچه‌سازی با سرویس ثالث | اتصال و هماهنگ‌سازی نرم‌افزار با یک پلتفرم خارجی از طریق پروتکل‌های استاندارد وب | +| Build vs Buy | دوراهی ساخت یا خرید | تصمیم استراتژیک مهندسی درباره توسعه داخلی یک ماژول یا استفاده از سرویس‌های آماده موجود | +| Webhook | وب‌هوک / قلاب وب | سازوکار اعلان خودکار از طرف سرویس خارجی به آدرس سرور شما هنگام رخ دادن یک رویداد | +| Adapter Pattern | الگوی آداپتور یا لایه واسط | شیوه طراحی کد به نحوی که تعویض یک سرویس‌دهنده (مثلاً کاوه‌نگار با SMS.ir) به کمترین تغییر در کل پروژه منجر شود | +| Server-Side Proxy | پروکسی سمت سرور | ارسال درخواست‌ها از طریق سرور خودی به منظور مخفی‌سازی کلیدهای اختصاصی از دید کاربران | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** تقابل ساخت دستی یک قطعه مکانیکی پیچیده و پرزحمت با استفاده از قطعات لگوی دیجیتال مدرن و براق. +2. **دیاگرام معماری پورتفولیو و قطعات متصل:** `images/portfolio-integrations-architecture.png` + * **موضوع:** معماری سیستم پورتفولیو در مرکز با فلش‌های متصل به کاوه‌نگار (پیامک)، لیارا (ایمیل)، زرین‌پال (پرداخت)، سوپابیس (دیتابیس/Auth) و OpenRouter (هوش مصنوعی). +3. **تفاوت درخواست امن سروری با درخواست ناامن کلاینتی:** `images/secure-server-vs-client-flow.png` + * **موضوع:** اینفوگرافیک مقایسه‌ای: مسیر قرمز (مرورگر کلید را مستقیماً می‌فرستد و هک می‌شود) در برابر مسیر سبز (مرورگر به Next.js Server Action پیام می‌دهد و سرور کلید را محرمانه ارسال می‌کند). + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# سرویس Third-Party چیست و چرا نباید چرخ را از نو بسازیم؟` +2. **مقدمه:** اگر برای سفر با هواپیما مجبور بودید خودتان کارخانه هواپیماسازی راه بیندازید، هیچ‌کس هرگز مسافرت نمی‌رفت! +3. **جدول کاور درس** +4. **استعاره جعبه ابزار و قطعات پیش‌ساخته در مهندسی:** + * چرا ارزش شما در اتصال هوشمندانه قطعات برای حل مسئله کاربر است، نه در بازنویسی پروتکل‌های مخابراتی و بانکی. +5. **جدول مقایسه‌ای Build vs Buy در ۵ بُعد کلیدی:** + * مقایسه هزینه، زمان تا راه‌اندازی، امنیت، نگهداری و مقیاس‌پذیری. +6. **نقشه اکوسیستم سرویس‌های شخص ثالث در پورتفولیوی شخصی:** + * نقش پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی در ساخت یک تجربه کاربری فوق‌العاده. +7. **باکس نکته Quera (`
`):** وب‌هوک‌ها چگونه کار می‌کنند؟ تفاوت این که ما مدام استعلام بگیریم (Polling) یا اینکه سرویس خودش زنگ بزند (Webhook). +8. **اصل ایمنی حیاتی: کلیدهای محرمانه هرگز به مرورگر کاربر نمی‌روند!** + * توضیح ساده نحوه میانجی‌گری Next.js Server Actions برای محافظت از سرمایه و اعتبار شما. +9. **باکس هشدار Quera (`
`):** خطر قفل شدن به یک شرکت خاص (Vendor Lock-in) و توصیه به تمیز نوشتن کد با توابع واسط. +10. **باکس انرژی‌بخش Quera (`
`):** خوشبختانه تقریباً تمام سرویس‌های مدرن دارای پنل‌های آزمایشی و سهمیه تست رایگان هستند. +11. **جمع‌بندی درس‌نامه:** تسلط مفهومی بر سرویس‌های شخص ثالث و ورود به دنیای خواندن مستندات فنی API و مدیریت امن متغیرها در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] استعاره قطعات لگو و دوراهی Build vs Buy به صورت شفاف و قانع‌کننده تحلیل شود. +- [ ] پنج دسته اصلی سرویس‌های ابری با مثال‌های متناسب با نیاز ایران معرفی گردند. +- [ ] چرخه درخواست امن سمت سرور برای حفظ کلیدهای اختصاصی به صورت گرافیکی و متنی تبیین شود. +- [ ] مفهوم وب‌هوک (Webhook) به زبان ساده آموزش داده شود. diff --git a/chapters/10-external-services/02-lesson-reading-docs-and-managing-keys/spec.md b/chapters/10-external-services/02-lesson-reading-docs-and-managing-keys/spec.md new file mode 100644 index 0000000..234bd51 --- /dev/null +++ b/chapters/10-external-services/02-lesson-reading-docs-and-managing-keys/spec.md @@ -0,0 +1,119 @@ +# مشخصات درس‌نامه: رمزگشایی از مستندات API و مدیریت امن کلیدها (Credentials & .env) +- **شناسه در سیلابس:** `L10.3` +- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۵ دقیقه +- **پیش‌نیازهای مستقیم:** `L10.2` (سرویس Third-Party چیست) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** ساختار استاندارد مستندات فنی API (شامل Base URL، هدرهای احراز هویت، اندپوینت‌ها، متدهای HTTP و نمونه‌های cURL/JSON) را به راحتی بخواند و درک کند. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** تفاوت متغیرهای محیطی امن سمت سرور با متغیرهای عمومی کلاینتی با پیشوند `NEXT_PUBLIC_` را تشخیص داده و خطرات نشت اطلاعات حساس را ارزیابی کند. +- [ ] **به‌کار ببندد (Apply):** فایل‌های `.env.local` و `.env.example` را به شکل استاندارد در پروژه پورتفولیو ایجاد و مقادیر آزمایشی کلیدها را در آن ذخیره نماید. +- [ ] **ایجاد کند (Create):** یک پرامپت طلایی برای ایجنت بنویسد که با دریافت نمونه کد cURL یا مستندات وب‌سرویس، یک ماژول ارتباطی تمیز با تایپ‌های کامل TypeScript تولید کند. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **شکستن ترس از مستندات انگلیسی و جداول پارامترها:** + * مستندات API شبیه دفترچه راهنمای یک تلویزیون جدید است؛ لازم نیست همه صفحات را بخوانید، فقط باید بدانید دکمه روشن و پورت ورودی کجاست! +2. **کالبدشکافی ۵ بخش اصلی هر سند API:** + * ۱. آدرس پایه (Base URL): سرور مرکزی کجاست؟ (مثلاً `https://api.kavenegar.com/v1/`). + * ۲. شیوه ارسال احراز هویت (Authentication): کلید در هدر `Authorization: Bearer ` است یا داخل پارامترهای آدرس؟ + * ۳. مسیرها و متدها (Endpoints & Methods): آیا داده می‌فرستیم (`POST`) یا داده می‌خوانیم (`GET`)؟ + * ۴. بدنه درخواست (Request Body / Payload): چه فیلدهایی اجباری (Required) و چه فیلدهایی اختیاری (Optional) هستند؟ + * ۵. پاسخ سرور و کدهای وضعیت (Response & Status Codes): پاسخ موفق ۲۰۰۰، خطای ۴۰۱ احراز هویت، خطای ۴۲۹ محدودیت درخواست و خطای ۵۰۰ سرور. +3. **تکنیک میانبر وایب کدینگ: خوراندن مستندات به ایجنت هوش مصنوعی:** + * نحوه کپی کردن دستور cURL از مستندات و تبدیل آن به کدهای تایپ‌اسکریپت تمیز توسط ایجنت با دستور `@docs`. +4. **قوانین طلایی مدیریت کلیدها و گاوصندوق `.env.local`:** + * قانون شماره ۱: هرگز کلید را هاردکد نکنید (`const apiKey = "123"` ممنوع!). + * قانون شماره ۲: فایل `.env.local` باید در `.gitignore` ثبت شده باشد تا هیچ‌وقت روی گیت‌هاب آپلود نشود. + * قانون شماره ۳: ساخت فایل نمونه `.env.example` بدون مقادیر واقعی برای سایر اعضای تیم یا ریپازیتوری عمومی. + * قانون شماره ۴: تفاوت حیاتی متغیرهای معمولی (مخفی در سرور) با متغیرهای دارای پیشوند `NEXT_PUBLIC_` (آشکار در مرورگر کاربر). +5. **دستورات چندسکویی برای کپی و مدیریت فایل‌های محیطی:** + * ساخت `.env.local` از روی `.env.example` با دستورات ترمینال برای ویندوز، مک و لینوکس. +6. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): نحوه کار ربات‌های اسکنر گیت‌هاب که کلیدهای لو رفته را در عرض چند ثانیه سرقت می‌کنند. + * کال‌اوت سبز (`
`): ابزارهای تستی سریع مانند Thunder Client یا استفاده از دستور ساده `curl` برای راستی‌آزمایی کارکرد کلید در ۳۰ ثانیه. + * کال‌اوت قرمز (`
`): هرگز کلیدهای واقعی و اعتباری خود را داخل چت‌بات‌های عمومی یا تیکت‌های پشتیبانی نگذارید. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- مباحث پیشرفته هشینگ و امضای دیجیتال توکن‌های JWT (فصل ۱۱). +- اتصال اختصاصی وب‌سرویس‌های خاص (در درس‌های بعدی فصل ۱۰ به تفکیک بررسی می‌شوند). + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| API Documentation | مستندات رابط برنامه‌نویسی | راهنمای رسمی ارائه‌دهنده سرویس که نحوه ارسال درخواست و قالب پاسخ را شرح می‌دهد | +| Base URL | آدرس پایه سرور | ریشه اصلی آدرس وب‌سرویس که تمام مسیرها و درخواست‌ها به انتهای آن متصل می‌شوند | +| Bearer Token | توکن حامل | فرمت استاندارد ارسال کلید امنیتی در هدر درخواست HTTP برای اثبات هویت مجاز | +| Environment Variable | متغیر محیطی | مقادیر تنظیمی خارج از کد برنامه که در فایل‌های محلی تنظیم و متناسب با محیط تغییر می‌کنند | +| GitLeaks / Secret Leak | نشت اطلاعات محرمانه | حادثه امنیتی خطرناک انتشار ناخواسته رمزها و کلیدهای خصوصی در تاریخچه گیت | +| cURL | ابزار خط فرمان cURL | دستور ترمینالی استاندارد برای شبیه‌سازی و ارسال درخواست‌های شبکه به سرورها | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** گاوصندوق دیجیتال مستحکم نئونی که کلیدهای API را محافظت می‌کند در کنار یک دفترچه راهنمای مدرن که مسیرهای نوری از آن خارج می‌شوند. +2. **کالبدشکافی ساختار سند API مدرن:** `images/api-docs-anatomy.png` + * **موضوع:** اسکرین‌شات از صفحه مستندات یک وب‌سرویس مدرن با فلش‌های توضیحی روی Base URL، Header، Request Body و Response JSON. +3. **تفکیک دو دنیای متغیرهای محیطی در Next.js:** `images/env-variables-boundary.png` + * **موضوع:** اینفوگرافیک مقایسه‌ای: سمت سرور (دیوار محرمانه، متغیرهای بدون پیشوند) در برابر سمت کلاینت (پیشوند NEXT_PUBLIC_، دید همگانی در سورس صفحه مرورگر). +4. **تبدیل نمونه cURL به کد تایپ‌اسکریپت با ایجنت:** `images/curl-to-typescript-prompt.png` + * **موضوع:** پنجره چت ادیتور که دستور cURL مستندات به ایجنت داده شده و ایجنت یک فانکشن تمیز تایپ‌شده تحویل داده است. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# رمزگشایی از مستندات API و مدیریت امن کلیدها (Credentials & .env)` +2. **مقدمه:** چگونه مستندات وب‌سرویس‌ها را در ۵ دقیقه رمزگشایی کنیم و کلیدهای محرمانه را مثل طلا در گاوصندوق نگه داریم؟ +3. **جدول کاور درس** +4. **استعاره منوی رستوران و گارسون:** + * مستندات API دقیقاً مثل منوی رستوران است: غذاها چیست (Endpoints)، هزینه چیست (Payload)، و غذا چطور سرو می‌شود (Response). +5. **کالبدشکافی ۵ رکن اساسی هر سند API با مثال واقعی:** + * آدرس پایه، هدرهای Authorization، متدهای GET/POST، بدنه جیسون و کدهای پاسخ موفق و خطا. +6. **سریع‌ترین تست با دستور cURL در ترمینال:** + * تست یک‌خطی ساده برای راستی‌آزمایی پاسخ سرور قبل از شروع کدنویسی. +7. **روش تبدیل مستندات به ماژول آماده تایپ‌اسکریپت با ایجنت هوش مصنوعی:** + * جعبه پرامپت طلایی: + > «من این نمونه درخواست cURL را از مستندات وب‌سرویس دارم: [نمونه cURL]. لطفاً یک تابع Server Action تایپ‌اسکریپت تمیز در Next.js با تایپ‌های مشخص برای ورودی‌ها و خروجی‌ها بساز که کلید API را از `process.env` بخواند و خطاهای شبکه را با پیام خطای خوانا به زبان فارسی مدیریت کند.» +8. **مدیریت گاوصندوق `.env.local` و جلوگیری از فاجعه نشت کلید:** + * چرا کلیدها هرگز داخل کدهای گیت وارد نمی‌شوند؟ + * تفاوت حساسیت‌برانگیز بین متغیرهای معمولی سروری و متغیرهای `NEXT_PUBLIC_`. +9. **دستورات چندسکویی ساخت فایل تنظیمات محیطی:** + * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس: + - Windows (PowerShell): + ```powershell + Copy-Item .env.example .env.local + ``` + - macOS (Terminal): + ```bash + cp .env.example .env.local + ``` + - Linux (Bash): + ```bash + cp .env.example .env.local + ``` +10. **باکس نکته Quera (`
`):** ماجرای وحشتناک ربات‌های اسکنر گیت‌هاب؛ نشت یک کلید API در یک مخزن عمومی و مصرف میلیون‌ها تومان اعتبار در کمتر از چند دقیقه! +11. **باکس راهنمای Quera (`
`):** افزونه‌های ساده مثل Thunder Client در ادیتور برای تست اندپوینت‌ها با یک کلیک. +12. **باکس هشدار Quera (`
`):** چک‌لیست نهایی فایل `.gitignore`؛ مطمئن شوید عبارت `.env*.local` در خطوط گیت‌ایگنور وجود دارد. +13. **جمع‌بندی درس‌نامه:** تسلط کامل بر زبان مستندات API و گاوصندوق متغیرهای محیطی؛ ورود به اولین اتصال واقعی: ارسال پیامک با وب‌سرویس‌های کاوه‌نگار و SMS.ir در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] پنج بخش اصلی مستندات API با مثال‌های بصری و ملموس تشریح شوند. +- [ ] مرز امنیتی متغیرهای سروری و متغیرهای دارای پیشوند `NEXT_PUBLIC_` تبیین گردد. +- [ ] پرامپت طلایی تبدیل مستندات و نمونه cURL به کدهای تمیز TypeScript ارائه شود. +- [ ] دستورات ترمینالی کپی فایل محیطی برای سیستم‌عامل‌های مختلف در تب‌های کشویی گنجانده شود. diff --git a/chapters/10-external-services/03-lesson-sms-integration-kavenegar-smsir/spec.md b/chapters/10-external-services/03-lesson-sms-integration-kavenegar-smsir/spec.md new file mode 100644 index 0000000..404e942 --- /dev/null +++ b/chapters/10-external-services/03-lesson-sms-integration-kavenegar-smsir/spec.md @@ -0,0 +1,116 @@ +# مشخصات درس‌نامه: اتصال وب‌سرویس پیامک بومی (کاوه‌نگار و SMS.ir) و ارسال الگوهای خدماتی +- **شناسه در سیلابس:** `L10.4` +- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۸ دقیقه +- **پیش‌نیازهای مستقیم:** `L10.3` (رمزگشایی از مستندات API و مدیریت کلیدها) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** تفاوت خطوط عادی تبلیغاتی با خطوط خدماتی بر پایه الگو (Verify Lookup / Pattern-based SMS) را در اپراتورهای مخابراتی ایران بشناسد و علت عبور از بلک‌لیست را درک کند. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** معماری وب‌سرویس دو ارائه‌دهنده بومی برجسته (کاوه‌نگار و SMS.ir) را مقایسه کرده و مدل ارسال پیامک نوتیفیکیشن در وب را ارزیابی نماید. +- [ ] **به‌کار ببندد (Apply):** یک Next.js Server Action برای فرم تماس پورتفولیو بسازد که به محض ثبت پیام توسط کارفرما، یک پیامک هشدار فوری به شماره موبایل صاحب پورتفولیو و یک پیامک تأیید به کارفرما ارسال کند. +- [ ] **ایجاد کند (Create):** یک حالت شبیه‌ساز لوکال (Mock Mode) برای مواقعی که دانشجو اعتبار مالی یا کلید وب‌سرویس ندارد پیاده کند تا بدون هزینه بتواند رفتار ارسال پیامک را در ترمینال تست نماید. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **داستان واقعی پیامک در ایران: چالش بلک‌لیست مخابرات (لیست سیاه تبلیغات):** + * چرا پیامک‌های عادی روی گوشی بیش از ۶۰٪ کاربران به دلیل مسدودسازی تبلیغات نمی‌رسد؟ + * راهکار نجات: ارسال بر اساس الگو (Pattern/Template) از طریق خطوط خدماتی اشتراکی ارائه‌دهندگان معتبر. +2. **بررسی وب‌سرویس‌های کاوه‌نگار (Kavenegar) و SMS.ir:** + * ثبت نام در پنل، دریافت API Key و تعریف الگوی پیامکی با متغیرها (مثلاً: `نام %token% پیام شما دریافت شد`). + * ساختار اندپوینت ارسال اعتبارسنجی (Verify Lookup). +3. **پیاده‌سازی ماژول ارسال پیامک در پورتفولیوی شخصی:** + * سناریوی کاربردی: کارفرما در فرم «تماس با من» نام و شماره خود را وارد می‌کند. + * سرور اکشن Next.js داده را می‌گیرد $\rightarrow$ در Supabase ذخیره می‌کند $\rightarrow$ تابع ارسال پیامک کاوه‌نگار را فراخوانی می‌کند $\rightarrow$ صاحب سایت در جیب خود لرزش گوشی و صدای نوتیفیکیشن پیامک را احساس می‌کند! +4. **طراحی حالت شبیه‌ساز تستی (Dev Mock Logger):** + * اگر کلید پیامک تعریف نشده باشد، متن پیامک به صورت یک کادر زیبا در ترمینال چاپ شود تا توسعه و تست متوقف نشود. +5. **جعبه پرامپت طلایی برای ایجنت:** + * پرامپت ساخت ماژول پیامک با تایپ‌های مشخص و مدیریت ارورهای قطعی اینترنت. +6. **دستورات چندسکویی برای نصب پکیج‌ها یا استفاده از Fetch استاندارد:** + * استفاده از `fetch` داخلی Node.js یا پکیج‌های رسمی در ویندوز، مک و لینوکس. +7. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): قانون سازمان تنظیم مقررات درباره محتوای پیامک‌های خدماتی و ممنوعیت ارسال متون تبلیغاتی با خطوط خدماتی. + * کال‌اوت سبز (`
`): شارژ هدیه رایگان ثبت نام در کاوه‌نگار برای تست‌های اولیه دانشجویان. + * کال‌اوت قرمز (`
`): خطر حملات پیامکی (SMS Flooding) و لزوم قرار دادن اعتبارسنجی اولیه روی فرم‌ها. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- احراز هویت پیامکی کامل و مدیریت سشن‌های OTP (در درس ۱۰.۶ بررسی می‌شود). +- تنظیمات پیچیده وب‌هوک وضعیت دلیوری (Delivery Report) پیامک. + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Pattern-based SMS | پیامک بر اساس الگو | ارسال پیام با متن پیش‌تأییدشده از طریق خط خدماتی که حتی به شماره‌های مسدود تبلیغات تحویل داده می‌شود | +| Blacklist / DND | لیست سیاه تبلیغات | فهرست مشترکان تلفن همراه که دریافت هرگونه پیامک تجاری و تبلیغاتی را لغو کرده‌اند | +| Service Line | خط خدماتی | سرشماره‌های پیامکی مورد تایید مراجع قانونی برای ارسال اطلاع‌رسانی‌ها و کدهای فوری اعتبارسنجی | +| Verify Lookup | سرویس اعتبارسنجی سریع | وب‌سرویس بهینه‌شده شرکت‌های پیامکی که پیامک‌ها را با اولویت بالا و در کمتر از ۵ ثانیه ارسال می‌کند | +| Mock Mode | حالت شبیه‌ساز تستی | اجرای آزمایشی فرآیند بدون ارسال درخواست واقعی به سرور برای صرفه‌جویی در هزینه و تسهیل تست | +| SMS Flooding | بمباران پیامکی | ارسال حجم بالایی از پیامک‌های ناخواسته توسط ربات‌ها که موجب هدررفت اعتبار حساب می‌شود | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** گوشی موبایل در حال دریافت یک پیامک تایید شیک با لوگوی نوتیفیکیشن در کنار دکمه ارسال فرم پورتفولیو. +2. **تفاوت خط تبلیغاتی و خط خدماتی الگومحور:** `images/service-vs-advertising-sms.png` + * **موضوع:** اینفوگرافیک مقایسه‌ای: خط تبلیغاتی به دیوار سد بلک‌لیست برخورد می‌کند؛ خط خدماتی الگومحور از گیت عبور کرده و به مقصد می‌رسد. +3. **معماری ارسال پیامک فرم تماس در پورتفولیو:** `images/contact-form-sms-flow.png` + * **موضوع:** فلوچارت جریان: فرم تماس $\rightarrow$ Server Action $\rightarrow$ API کاوه‌نگار $\rightarrow$ پیامک به صاحب سایت و کارفرما. +4. **خروجی حالت شبیه‌ساز در ترمینال:** `images/sms-terminal-mock-output.png` + * **موضوع:** نمایش کادر شبیه‌سازی شده متن پیامک در ترمینال مشکی ادیتور با متغیرهای نام، شماره و متن درخواست. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# اتصال وب‌سرویس پیامک بومی (کاوه‌نگار و SMS.ir) و ارسال الگوهای خدماتی` +2. **مقدمه:** چرا وقتی کارفرما روی دکمه «ارسال درخواست» در پورتفولیو کلیک می‌کند، صدای پیامک روی گوشی شما باید به صدا درآید؟ +3. **جدول کاور درس** +4. **چالش بزرگ بلک‌لیست مخابرات در ایران و نسخه شفابخش «ارسال با پترن»:** + * تفاوت خطوط تبلیغاتی با خطوط خدماتی اشتراکی؛ چرا نباید از ارسال متنی ساده استفاده کنیم؟ +5. **گام اول: ساخت حساب در کاوه‌نگار / SMS.ir و دریافت کلید API:** + * ثبت رایگان، دریافت کلید تست، و ثبت یک الگوی ساده اعتبارسنجی در پنل. +6. **معماری ارسال ایمن سمت سرور با Next.js Server Actions:** + * ساخت فایل `services/sms.ts` برای تفکیک منطق ارسال پیامک از صفحات کاربری. +7. **کد ماژول ارسال پیامک با قابلیت خودکار شبیه‌ساز (Mock Fallback):** + * اگر کلید `KAVENEGAR_API_KEY` وجود نداشت، پیام را در کنسول چاپ کن؛ اگر بود، درخواست `fetch` واقعی بفرست. +8. **جعبه پرامپت طلایی: ساخت فرم تماس مجهز به نوتیفیکیشن پیامکی با ایجنت:** + * پرامپت دقیق: + > «من یک فایل `services/sms.ts` برای ارسال پیامک پترن با وب‌سرویس کاوه‌نگار دارم. لطفاً فرم تماس در صفحه اصلی پورتفولیو را به یک Server Action متصل کن که پس از ثبت پیام در دیتابیس، با متغیرهای نام کارفرما و متن کوتاه، تابع ارسال پیامک را فراخوانی کند و وضعیت ارسال موفق را با انیمیشن سبز به کاربر نشان دهد.» +9. **دستورات چندسکویی برای تعریف متغیرهای محیطی پیامک:** + * افزودن `KAVENEGAR_API_KEY` در منوی کشویی سه‌گانه ویندوز، مک و لینوکس: + - Windows (PowerShell): + ```powershell + Add-Content .env.local "`nKAVENEGAR_API_KEY=your_api_key_here" + ``` + - macOS (Terminal): + ```bash + echo "KAVENEGAR_API_KEY=your_api_key_here" >> .env.local + ``` + - Linux (Bash): + ```bash + echo "KAVENEGAR_API_KEY=your_api_key_here" >> .env.local + ``` +10. **باکس نکته Quera (`
`):** قوانین متغیرها در پترن‌های کاوه‌نگار (توکن‌های عددی و حروفی بدون فاصله) و اهمیت تایید سریع الگو در پنل. +11. **باکس هشدار Quera (`
`):** هرگز اندپوینت پیامک را بدون اعتبارسنجی شماره (بررسی فرمت ۰۹xxxxxxxx) رها نکنید؛ خطر سوءاستفاده ربات‌ها. +12. **باکس انرژی‌بخش Quera (`
`):** احساس فوق‌العاده دیدن اولین پیامک واقعی ارسالی از سایتی که خودتان ساخته‌اید روی گوشی موبایلتان. +13. **جمع‌بندی درس‌نامه:** تکمیل زنجیره پیامک بومی؛ ورود به دنیای ایمیل‌های تراکنشی و ارسال ایمیل با ایمیل‌سرور لیارا در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] پدیده بلک‌لیست مخابرات ایران و لزوم ارسال پیامک‌های پترن‌محور تشریح شده باشد. +- [ ] ادغام وب‌سرویس‌های بومی (کاوه‌نگار / SMS.ir) با کدهای تمیز سمت سرور پیاده شود. +- [ ] مکانیزم شبیه‌ساز محلی (Mock Mode) برای تست بدون نیاز به شارژ حساب ارائه گردد. +- [ ] دستورات ترمینالی چندسکویی برای پیکربندی کلیدها در تب‌های اختصاصی گنجانده شود. diff --git a/chapters/10-external-services/04-lesson-transactional-email-with-smtp/spec.md b/chapters/10-external-services/04-lesson-transactional-email-with-smtp/spec.md new file mode 100644 index 0000000..00f0dea --- /dev/null +++ b/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. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم رکوردهای SPF و DKIM در DNS دامنه و اثر آن‌ها بر عبور از فیلتر اسپم گوگل و مایکروسافت. + * کال‌اوت سبز (`
`): پکیج رایگان آغازین ایمیل لیارا برای تست‌های دانشجویی بدون هزینه. + * کال‌اوت قرمز (`
`): ممنوعیت مطلق ارسال ایمیل‌های تبلیغاتی انبوه از طریق پورت‌های تراکنشی و خطر مسدود شدن سرور. + +### آنچه نباید وارد آن شویم (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 (`
`):** نقش گذرنامه‌های سه‌گانه ایمیل (SPF، DKIM و DMARC) در رسیدن صددرصدی ایمیل به اینباکس اصلی جیمیل و جلوگیری از پوشه Spam. +11. **باکس هشدار Quera (`
`):** هرگز از هاست ایمیل اشتراکی برای ارسال ایمیل به هزاران نفر همزمان استفاده نکنید؛ سرور شما در لیست سیاه جهانی مسدود خواهد شد. +12. **باکس رضایت‌بخش Quera (`
`):** تست ارسال ایمیل و دیدن نوتیفیکیشن دریافت ایمیل روی کامپیوتر یا گوشی در کمتر از ۳ ثانیه. +13. **جمع‌بندی درس‌نامه:** تکمیل کانال ایمیل؛ ورود به دنیای هیجان‌انگیز ارائه‌دهندگان احراز هویت خارجی (Google, GitHub و لاگین پیامکی) در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] تفاوت ایمیل‌های تراکنشی با ایمیل‌های تبلیغاتی تبیین گردد. +- [ ] راه‌اندازی و استفاده از سرور SMTP لیارا به همراه کتابخانه Nodemailer آموزش داده شود. +- [ ] اصول ساخت قالب‌های HTML ایمیل راست‌چین (RTL) با کدهای استاندارد توضیح داده شود. +- [ ] تنظیمات متغیرهای محیطی و نصب پکیج‌ها در تب‌های چندسکویی ارائه شود. diff --git a/chapters/10-external-services/05-lesson-oauth-and-sms-auth-providers/spec.md b/chapters/10-external-services/05-lesson-oauth-and-sms-auth-providers/spec.md new file mode 100644 index 0000000..14c6ce4 --- /dev/null +++ b/chapters/10-external-services/05-lesson-oauth-and-sms-auth-providers/spec.md @@ -0,0 +1,110 @@ +# مشخصات درس‌نامه: ارائه‌دهندگان احراز هویت خارجی (Google، GitHub و الگوی ورود پیامکی) +- **شناسه در سیلابس:** `L10.6` +- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۱۸ دقیقه +- **پیش‌نیازهای مستقیم:** `L10.5` (ارسال ایمیل‌های تراکنشی با SMTP) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** سازوکار پروتکل استانداردهای احراز هویت اجتماعی (OAuth 2.0) را شرح دهد و بداند چرا ورود با یک کلیک، نرخ تبدیل و رضایت کاربران را به شدت افزایش می‌دهد. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** مزایا و معایب ورود با حساب‌های بین‌المللی (Google و GitHub) را در مقایسه با الگوی غالب بومی ایران یعنی ورود با رمز یک‌بارمصرف پیامکی (SMS OTP) ارزیابی کند. +- [ ] **به‌کار ببندد (Apply):** ارائه‌دهندگان GitHub و Google را در کنسول Supabase پیکربندی کرده و دکمه‌های ورود با یک کلیک را در پنل ادمین پورتفولیو فعال نماید. +- [ ] **ایجاد کند (Create):** معماری و جریان گام‌به‌گام پیاده‌سازی ورود با شماره موبایل و کد یک‌بارمصرف پیامکی (OTP) با وب‌سرویس کاوه‌نگار/SMS.ir را طراحی و مستند کند. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **پایان دوران فرم‌های ثبت‌نام طولانی با رمزهای عبور فراموش‌شدنی:** + * چرا هیچ کاربری حوصله انتخاب رمز ۱۲ رقمی با حروف بزرگ و کوچک و نماد را ندارد؟ +2. **پروتکل OAuth 2.0 به زبان بسیار ساده:** + * استعاره کلید هتل و کارت اتاق: گوگل یا گیت‌هاب هویت کاربر را تایید می‌کنند و به پورتفولیوی شما یک کارت تردد موقت (Access Token) می‌دهند. +3. **مراحل فعال‌سازی ورود با GitHub و Google در Supabase:** + * ساخت OAuth App در تنظیمات توسعه‌دهندگان GitHub (Developer Settings). + * ساخت پروژه و دریافت Client ID و Client Secret در Google Cloud Console. + * تنظیم Callback URL سوپابیس (`https://.supabase.co/auth/v1/callback`). + * فعال‌سازی تاگل ارائه‌دهنده در داشبورد Authentication سوپابیس. +4. **کدنویسی فرانت‌اند Next.js برای دکمه‌های ورود:** + * فراخوانی ساده `supabase.auth.signInWithOAuth({ provider: 'github' })`. + * هدایت خودکار کاربر پس از ورود موفق به پنل مدیریت (`/admin`). +5. **معماری الگوی ورود بومی ایرانی: لاگین پیامکی (SMS OTP Login):** + * بررسی چرخه ورود در اپ‌های محبوب مانند اسنپ و دیجی‌کالا: + - ۱. کاربر شماره موبایل خود را وارد می‌کند. + - ۲. سرور یک کد تصادفی ۵ رقمی تولید کرده و با زمان انقضای ۲ دقیقه (TTL) در جدول یا سشن ذخیره می‌کند. + - ۳. فراخوانی الگوی اعتبارسنجی وب‌سرویس کاوه‌نگار/SMS.ir برای تحویل در ۲ ثانیه. + - ۴. کاربر کد را وارد می‌کند؛ سرور مطابقت داده و سشن لاگین ایجاد می‌کند. +6. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): تفاوت OAuth (احراز هویت و اجازه دسترسی) با OIDC (شناسایی هویت پروفایل کاربر). + * کال‌اوت سبز (`
`): مدیریت خودکار کوکی‌ها و رفرش توکن‌ها توسط کتابخانه `@supabase/ssr`. + * کال‌اوت قرمز (`
`): تله خطای رایج `redirect_uri_mismatch`؛ تطابق نداشتن آدرس لوکال‌هاست با دامنه ثبت شده در کنسول گوگل. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- احراز هویت دو مرحله‌ای سخت‌افزاری (Hardware YubiKey). +- اتصال سیستم‌های سازمانی Active Directory و SAML SSO. + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| OAuth 2.0 | پروتکل تفویض دسترسی آزاد | استاندارد امنیتی که به کاربران اجازه می‌دهد بدون اشتراک رمز عبور، با اکانت گوگل/گیت‌هاب وارد شوند | +| Social Login | ورود با شبکه‌های اجتماعی | قابلیت احراز هویت سریع با فشردن دکمه ورود از طریق حساب‌های کاربری موجود | +| Callback URL / Redirect URI | آدرس بازگشت مجاز | نشانی مشخصی از سایت شما که ارائه‌دهنده پس از تایید هویت، کاربر را به آن برمی‌گرداند | +| Client ID & Client Secret | شناسه و رمز کلاینت | شناسه عمومی و رمز فوق‌محرمانه برنامه شما نزد گوگل یا گیت‌هاب | +| OTP (One-Time Password) | رمز یک‌بارمصرف | کد موقت و معمولاً چندرقمی که تنها برای یک‌بار ورود و در بازه زمانی کوتاه معتبر است | +| TTL (Time To Live) | طول عمر اعتبار | مدت زمانی که یک کد موقت یا سشن پیش از باطل شدن خودکار معتبر باقی می‌ماند | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** صفحه ورود شیک با دکمه‌های ورود با یک کلیک گوگل و گیت‌هاب و فیلد دریافت کد تایید پیامکی موبایل. +2. **چرخه ۴ مرحله‌ای تبادل هویت با OAuth 2.0:** `images/oauth2-flow-diagram.png` + * **موضوع:** فلوچارت: کاربر روی «ورود با گیت‌هاب» می‌زند $\rightarrow$ انتقال به گیت‌هاب $\rightarrow$ تایید کاربر $\rightarrow$ بازگشت توکن به سوپابیس $\rightarrow$ باز شدن پنل ادمین. +3. **تنظیمات کلیدهای گوگل و گیت‌هاب در داشبورد Supabase:** `images/supabase-auth-providers-setup.png` + * **موضوع:** اسکرین‌شات از پنل Supabase Authentication Providers با فیلدهای Client ID و Secret پر شده. +4. **فلوچارت ورود پیامکی بومی (SMS OTP):** `images/sms-otp-architecture.png` + * **موضوع:** اینفوگرافیک معماری: دریافت شماره $\rightarrow$ تولید کد ۵ رقمی $\rightarrow$ ارسال با وب‌سرویس پترن کاوه‌نگار $\rightarrow$ اعتبارسنجی ورودی کاربر $\rightarrow$ تولید سشن ورود. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# ارائه‌دهندگان احراز هویت خارجی (Google، GitHub و الگوی ورود پیامکی)` +2. **مقدمه:** چرا ورود با یک کلیک (Social Login) و ورود پیامکی، کاربران را از کابوس به خاطر سپردن ده‌ها رمز عبور نجات می‌دهد؟ +3. **جدول کاور درس** +4. **استعاره کارت شناسایی بین‌المللی و پاسپورت معتبر:** + * وقتی گوگل هویت کاربر را تایید می‌کند، چرا شما دوباره از کاربر سوال بپرسید؟ +5. **پروتکل OAuth 2.0 چگونه کار می‌کند؟** + * کالبدشکافی جریان ریدایرکت، رضایت کاربر، و تحویل توکن سشن. +6. **راه‌اندازی گام‌به‌گام ورود با GitHub در Supabase:** + * آموزش تصویری ساخت OAuth App در گیت‌هاب و وارد کردن کلیدها در کنسول سوپابیس. +7. **راه‌اندازی ورود با Google Cloud:** + * فعال‌سازی OAuth Consent Screen و ساخت Credentials در پنل گوگل. +8. **پیاده‌سازی دکمه‌های ورود در صفحه `/admin/login` پورتفولیو:** + * کد کامپوننت React با آیکون‌های رسمی Google و GitHub و انیمیشن لودینگ. +9. **الگوی ورود بومی ایران: احراز هویت پیامکی (SMS OTP):** + * چرا در کسب‌وکارهای ایرانی، شماره موبایل هویت اصلی کاربر است؟ + * بررسی معماری ۴ گامی ساخت سیستم ورود پیامکی با کاوه‌نگار/SMS.ir. +10. **جعبه پرامپت طلایی: اتصال دکمه‌های ورود اجتماعی به ایجنت:** + * پرامپت دقیق: + > «من ارائه‌دهنده‌های Google و GitHub را در Supabase فعال کرده‌ام. لطفاً کامپوننت لاگین را به‌روزرسانی کن تا دکمه‌های شکیل ورود با گیت‌هاب و گوگل به آن اضافه شوند. هنگام کلیک، تابع `signInWithOAuth` فراخوانی شود و در صورت موفقیت کاربر مستقیماً به داشبورد `/admin` هدایت گردد.» +11. **باکس نکته Quera (`
`):** اهمیت هماهنگی دقیق Redirect URL در محیط Localhost و پس از دیپلوی روی دامنه نهایی. +12. **باکس هشدار Quera (`
`):** تله فاش کردن `Client Secret` گوگل در کدهای فرانت‌اند؛ این کلید فقط و فقط باید در پنل پشتیبانی سوپابیس ثبت شود. +13. **باکس انرژی‌بخش Quera (`
`):** آزمایش لاگین با گیت‌هاب شخصی خودتان و دیدن عکس پروفایل و ایمیلتان در داشبورد ادمین پورتفولیو. +14. **جمع‌بندی درس‌نامه:** تکمیل مکانیزم‌های ورود؛ ورود به جذاب‌ترین بخش تجاری: اتصال درگاه پرداخت زرین‌پال در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] اصول کارکرد پروتکل OAuth 2.0 به زبان قابل فهم برای افراد غیربرنامه‌نویس تبیین شود. +- [ ] مراحل دریافت کلیدهای GitHub و Google و تنظیم آن‌ها در Supabase به شکل عملی بیان گردد. +- [ ] معماری ورود بومی پیامکی (SMS OTP) به همراه گام‌های پیاده‌سازی تشریح شود. +- [ ] نمونه کدهای اتصال فرانت‌اند و کال‌اوت‌های هشداری امنیتی لحاظ گردند. diff --git a/chapters/10-external-services/06-lesson-payment-gateway-zarinpal-sandbox/spec.md b/chapters/10-external-services/06-lesson-payment-gateway-zarinpal-sandbox/spec.md new file mode 100644 index 0000000..fbd332b --- /dev/null +++ b/chapters/10-external-services/06-lesson-payment-gateway-zarinpal-sandbox/spec.md @@ -0,0 +1,118 @@ +# مشخصات درس‌نامه: اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (ZarinPal Sandbox) +- **شناسه در سیلابس:** `L10.7` +- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۲۰ دقیقه +- **پیش‌نیازهای مستقیم:** `L10.6` (ارائه‌دهندگان احراز هویت خارجی) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** چرخه استاندارد ۲ مرحله‌ای پرداخت آنلاین شاپرک (درخواست پرداخت $\rightarrow$ هدایت به درگاه $\rightarrow$ تایید نهایی تراکنش Verification) را به زبان ساده شرح دهد. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** ارزش فوق‌العاده محیط شبیه‌ساز (Sandbox) زرین‌پال را در تست تراکنش‌های مالی بدون نیاز به اینماد، کارت بانکی واقعی یا ریسک کسر وجه درک کند. +- [ ] **به‌کار ببندد (Apply):** قابلیت «رزرو جلسه مشاوره تخصصی ۱ ساعته» را در پورتفولیو با وب‌سرویس زرین‌پال پیاده‌سازی کرده و وضعیت پرداخت را در دیتابیس Supabase ذخیره نماید. +- [ ] **ایجاد کند (Create):** یک روت اعتبارسنجی (Verify Route Handler) امن بسازد که در برابر حمله پرداخت جعلی (Fake Query Attack) و پرداخت تکراری مقاوم باشد. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **لحظه بلوغ تجاری محصول: تبدیل بازدیدکننده به خریدار:** + * چرا توانایی دریافت وجه آنلاین، مهم‌ترین وجه تمایز یک پروژه جدی تجاری از یک تمرین دانشجویی است. +2. **کالبدشکافی چرخه ۲ مرحله‌ای پرداخت آنلاین در ایران (شاپرک):** + * مرحله ۱ (Payment Request): ارسال مبلغ، توضیحات، ایمیل، موبایل و آدرس بازگشت به زرین‌پال $\rightarrow$ دریافت کد رهگیری اختصاصی (`Authority`). + * مرحله ۲ (Redirect): هدایت مرورگر کاربر به صفحه امن درگاه پرداخت زرین‌پال با شناسه Authority. + * مرحله ۳ (Callback): بازگشت کاربر از بانک به آدرس سایت شما با پارامترهای `Authority` و `Status=OK/NOK`. + * مرحله ۴ (Payment Verification): ارسال مجدد Authority و مبلغ از سمت سرور به زرین‌پال برای استعلام قطعی و دریافت شماره پیگیری (`RefID`). +3. **محیط سندباکس (ZarinPal Sandbox)؛ آزمایشگاه امن توسعه‌دهندگان:** + * استفاده از مرچنت کد تستی بدون نیاز به احراز هویت بانکی، سفته، یا نماد اعتماد الکترونیکی (اینماد). + * امکان شبیه‌سازی هر دو حالت «تراکنش موفق» و «تراکنش ناموفق/انصراف کاربر». +4. **پیاده‌سازی ماژول پرداخت در پورتفولیوی شخصی:** + * فیچر: «رزرو وقت مشاوره آنلاین» در صفحه پورتفولیو. + * کاربر مشخصات و زمان را انتخاب می‌کند $\rightarrow$ دکمه «پرداخت و ثبت نهایی» را می‌زند $\rightarrow$ به درگاه منتقل می‌شود $\rightarrow$ پس از پرداخت موفق، رکورد رزرو در Supabase وضعیت `paid` می‌گیرد $\rightarrow$ پیامک و ایمیل تایید ارسال می‌شود. +5. **دستورات چندسکویی برای متغیرهای محیطی زرین‌پال:** + * تنظیم `ZARINPAL_MERCHANT_ID` و `NEXT_PUBLIC_APP_URL` در سه سیستم‌عامل. +6. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم تکرارناپذیری (Idempotency) و خطر کلاهبرداری بازگشت جعلی؛ هرگز بدون متد Verify به کاربر خدمات ندهید! + * کال‌اوت سبز (`
`): شبیه‌سازی کارت بانکی تستی در سندباکس بدون کسر حتی یک ریال از حساب شما. + * کال‌اوت قرمز (`
`): تله اشتباه گرفتن ریال و تومان؛ درگاه‌های شاپرک مبالغ را بر حسب ریال یا تومان با دقت بالا می‌خواهند. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- مراحل قانونی دریافت اینماد و کد مالیاتی (در فصل ۱۲ و چک‌لیست حقوقی بررسی می‌شود). +- پرداخت‌های بین‌المللی با ارز دیجیتال یا کارت‌های اعتباری ویزا/مستر. + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Payment Gateway (IPG) | درگاه پرداخت اینترنتی | واسط نرم‌افزاری امن بانکی که امکان کسر وجه از حساب خریدار و واریز به حساب فروشنده را فراهم می‌کند | +| Merchant ID | شناسه پذیرنده | کد شناسایی ۳۶ کاراکتری یکتای شما نزد شرکت پرداخت برای تفکیک تراکنش‌های کسب‌وکار | +| Authority | شناسه تراکنش شاپرک | رشته کد ۳۶ کاراکتری که برای هر درخواست پرداخت تولید شده و مبنای پیگیری تراکنش است | +| Payment Verification | تایید نهایی پرداخت | استعلام قطعی و رمزنگاری‌شده از درگاه برای اثبات واریز واقعی پول قبل از تحویل کالا یا خدمات | +| RefID | شماره پیگیری بانکی | شماره ارجاع یکتای رسمی شبکه بانکی که روی رسید تراکنش چاپ می‌شود | +| Double Spending | پرداخت تکراری یا جعلی | تلاش خرابکارانه برای تحویل چندباره خدمات با استفاده از یک شناسه تایید شده قدیمی | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** کارت بانکی نئونی با آیکون تایید سبز در حال لمس درگاه پرداخت دیجیتال زرین‌پال روی لپ‌تاپ پورتفولیو. +2. **چرخه ۴ مرحله‌ای پرداخت شاپرک با زرین‌پال:** `images/zarinpal-payment-flow.png` + * **موضوع:** دیاگرام معماری: ۱) درخواست پرداخت سروری $\rightarrow$ ۲) انتقال به درگاه سندباکس $\rightarrow$ ۳) بازگشت کاربر $\rightarrow$ ۴) تایید سروری (Verify) $\rightarrow$ صدور فاکتور نهایی. +3. **صفحه شبیه‌ساز پرداخت سندباکس زرین‌پال:** `images/zarinpal-sandbox-mock-screen.png` + * **موضوع:** اسکرین‌شات از محیط سندباکس زرین‌پال با دکمه‌های «پرداخت موفق» و «انصراف از پرداخت» برای تست. +4. **رسید تراکنش موفق در پورتفولیو:** `images/payment-success-receipt-card.png` + * **موضوع:** کارت رسید مدرن در سایت با کد پیگیری RefID، مبلغ، تاریخ، و دکمه دانلود جزئیات جلسه مشاوره. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (ZarinPal Sandbox)` +2. **مقدمه:** هیجان‌انگیزترین لحظه برای یک خالق محصول: وقتی اولین پیامک «حساب شما شارژ شد» از راه می‌رسد! +3. **جدول کاور درس** +4. **استعاره صندوقدار فروشگاه و دستگاه پوز:** + * شما فاکتور صادر می‌کنید، مشتری کارت می‌کشد، دستگاه بوق تایید می‌زند، و سپس شما کالا را تحویل می‌دهید. +5. **معماری پرداخت در وب مدرن ایران (پروتکل دوگانه Request و Verify):** + * چرا نمی‌توان تنها به بازگشت کاربر به آدرس سایت اعتماد کرد؟ +6. **فعال‌سازی آزمایشگاه سندباکس زرین‌پال (بدون نیاز به اینماد):** + * استفاده از مرچنت تستی ۳۶ کاراکتری و آدرس اندپوینت سندباکس: + `https://sandbox.zarinpal.com/pg/v4/payment/request.json` +7. **کدنویسی ماژول پرداخت `services/payment.ts` در Next.js:** + * تابع ایجاد درخواست پرداخت (`createPaymentRequest`). + * تابع اعتبارسنجی نهایی پرداخت (`verifyPayment`). +8. **جعبه پرامپت طلایی: ساخت صفحه پرداخت و رزرو مشاوره با ایجنت:** + * پرامپت دقیق: + > «من ماژول پرداخت `services/payment.ts` را برای زرین‌پال دارم. لطفاً یک بخش جدید در صفحه پورتفولیو با عنوان "رزرو جلسه مشاوره تخصصی" اضافه کن. کاربر با انتخاب تاریخ و زدن دکمه پرداخت، به سرور اکشن متصل شود، به درگاه زرین‌پال سندباکس هدایت گردد، و پس از بازگشت به صفحه `/payment/callback`، در صورت تایید موفقیت، رسید پرداخت با شماره پیگیری RefID نمایش داده شده و وضعیت رزرو در دیتابیس به paid تغییر کند.» +9. **دستورات چندسکویی برای تنظیم متغیرهای محیطی پرداخت:** + * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس: + - Windows (PowerShell): + ```powershell + Add-Content .env.local "`nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000`nNEXT_PUBLIC_APP_URL=http://localhost:3000" + ``` + - macOS (Terminal): + ```bash + echo -e "\nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000\nNEXT_PUBLIC_APP_URL=http://localhost:3000" >> .env.local + ``` + - Linux (Bash): + ```bash + echo -e "\nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000\nNEXT_PUBLIC_APP_URL=http://localhost:3000" >> .env.local + ``` +10. **باکس نکته امنیتی Quera (`
`):** تله جعل پارامتر URL؛ اگر کسی آدرس را دستی به `Status=OK` تغییر دهد، تابع `verifyPayment` متوجه شده و تراکنش فاقد اعتبار تلقی می‌شود. +11. **باکس هشدار Quera (`
`):** واحد پول! مبالغ زرین‌پال به تومان است، اما همیشه مستندات رسمی را چک کنید تا مشتری ده برابر مبلغ واقعی پرداخت نکند! +12. **باکس رضایت‌بخش Quera (`
`):** کلیک روی دکمه پرداخت سندباکس و مشاهده صفحه تراکنش موفق بدون نیاز به کارت واقعی. +13. **جمع‌بندی درس‌نامه:** تسلط بر دریافت پول آنلاین؛ ورود به بخش هیجان‌انگیز و پایانی فصل: تزریق هوش مصنوعی به پورتفولیو با API در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] چرخه ۴ مرحله‌ای پرداخت اینترنتی شاپرک با نمودار و زبان شفاف تبیین گردد. +- [ ] نحوه اتصال به سندباکس زرین‌پال با مرچنت تستی به صورت کاربردی آموزش داده شود. +- [ ] روت تایید پرداخت (Payment Verification) با تدابیر امنیتی جلوگیری از تقلب پیاده شود. +- [ ] سناریوی رزرو مشاوره پورتفولیو به صورت یکپارچه با پیامک و دیتابیس ارائه گردد. diff --git a/chapters/10-external-services/07-lesson-integrating-ai-models-and-apis/spec.md b/chapters/10-external-services/07-lesson-integrating-ai-models-and-apis/spec.md new file mode 100644 index 0000000..00cc340 --- /dev/null +++ b/chapters/10-external-services/07-lesson-integrating-ai-models-and-apis/spec.md @@ -0,0 +1,132 @@ +# مشخصات درس‌نامه: تزریق مغز هوش مصنوعی به محصول؛ چت‌بات رزومه با OpenRouter و AvalAI +- **شناسه در سیلابس:** `L10.8` +- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10) +- **نوع محتوا:** 📘 درس‌نامه متنی +- **زمان تقریبی مطالعه:** ۲۰ دقیقه +- **پیش‌نیازهای مستقیم:** `L10.7` (اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال) + +--- + +## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy) +دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند: +- [ ] **درک کند (Understand):** جهش از «کدنویسی با هوش مصنوعی» به «تزریق قابلیت‌های هوش مصنوعی به عنوان فیچر محصول» (AI as a Feature) را درک کرده و ساختار استاندارد Chat Completions API را شرح دهد. +- [ ] **تحلیل/ارزیابی کند (Evaluate):** مزایای هاب‌های چندمدلی نظیر OpenRouter و سرویس‌های واسط بومی (نظیر AvalAI) را در کاهش هزینه‌ها و عدم نیاز به کارت‌های اعتباری بین‌المللی ارزیابی کند. +- [ ] **به‌کار ببندد (Apply):** یک ویجت چت‌بات هوشمند رزومه (AI Resume Assistant) در گوشه پورتفولیو پیاده کند که با استریم زنده (Streaming)، به سوالات کارفرمایان درباره مهارت‌ها و پروژه‌ها پاسخ دهد. +- [ ] **ایجاد کند (Create):** یک پرامپت سیستمی مستحکم (System Prompt با تکنیک Grounding) تنظیم کند تا از توهم اطلاعات غیرواقعی و حملات تزریق پرامپت (Prompt Injection) جلوگیری نماید. + +--- + +## ۲. محدوده و مرزهای محتوا (Scope & Boundaries) + +### آنچه باید پوشش داده شود (In-Scope): +1. **انقلاب در هویت محصول: پورتفولیویی که زنده است و حرف می‌زند!** + * بازدیدکننده پورتفولیو به جای خواندن صدها سطر رزومه، از هوش مصنوعی می‌پرسد: «آیا فلانی تجربه کار با Supabase را دارد؟» و پاسخ هوشمند دریافت می‌کند. +2. **کالبدشکافی ساختار پیام‌های API در مدل‌های زبانی (Chat Completion Schema):** + * پیام سیستمی (`system`): شخصیت، قوانین و دانش پایه دستیار. + * پیام کاربر (`user`): سوال یا ورودی جدید بازدیدکننده. + * پیام دستیار (`assistant`): تاریخچه پاسخ‌های مدل برای حفظ کانتکست گفتگو. +3. **دسترسی بی‌دردسر به مدل‌های روز جهان (OpenRouter و AvalAI):** + * چرا OpenRouter با یک کلید، دسترسی به Claude 3.5 Sonnet، GPT-4o، DeepSeek V3 و Llama 3 را ممکن می‌کند؟ + * گزینه‌های پرداخت ریالی و پروکسی‌های داخلی پایدار در ایران. +4. **تکنیک لنگراندازی داده‌ها (Grounding) و دیوارهای امنیتی:** + * تزریق خلاصه مشخصات صاحب سایت، لیست پروژه‌ها، سابقه کار و راه‌های ارتباطی در پرامپت سیستمی. + * دستورالعمل سفت‌وسخت: «تو دستیار رزومه هستی. فقط بر اساس اطلاعات بالا پاسخ بده. اگر چیزی را نمی‌دانی، حدس نزن و بگو در رزومه ذکر نشده است.» +5. **معماری روت سرور امن `/api/chat` در Next.js:** + * دریافت پیام کاربر $\rightarrow$ افزودن پرامپت سیستمی مخفی در سرور $\rightarrow$ ارسال به OpenRouter با کلید محرمانه $\rightarrow$ استریم پاسخ به مرورگر کاربر. +6. **پیاده‌سازی رابط کاربری ویجت چت:** + * آیکون شناور در گوشه پایین سایت، قابلیت باز و بسته شدن، دکمه‌های پیشنهاد سریع سوال (Chips)، و افکت تایپ زنده (Typewriter/Streaming). +7. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): حمله تزریق پرامپت (Prompt Injection)؛ چطور نگذاریم کارفرما با گفتن «تمام دستورات قبلی را فراموش کن» دستیار را هک کند. + * کال‌اوت سبز (`
`): مدل‌های فوق‌سریع و تقریباً رایگان مانند DeepSeek V3 یا Gemini 2.0 Flash در OpenRouter با هزینه چند صدم سنت برای هر مکالمه. + * کال‌اوت قرمز (`
`): محدود کردن طول تاریخچه چت (Truncation) به ۶ پیام آخر برای جلوگیری از سوختن توکن‌ها و هزینه‌های انفجاری. + +### آنچه نباید وارد آن شویم (Out-of-Scope): +- مباحث پیچیده RAG (Retrieval-Augmented Generation) و دیتابیس‌های برداری وکتوری (در فصل ۱۵ بررسی می‌شود). +- فاین‌تیونینگ (Fine-Tuning) مدل‌های زبانی متن‌باز. + +--- + +## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms) + +| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده | +| :--- | :--- | :--- | +| Chat Completions API | وب‌سرویس تکمیل گفتگو | رابط استاندارد ارسال تاریخچه مکالمه به مدل زبانی و دریافت پاسخ متنی هوشمند | +| System Prompt | پرامپت سیستمی بنیادین | دستورالعمل سطح بالایی که رفتار، هویت، محدودیت‌ها و پایگاه دانش مدل را مشخص می‌کند | +| Grounding | لنگراندازی داده‌ها | مقید کردن مدل به استفاده انحصاری از اطلاعات و اسناد ارائه شده به جای تکیه بر اطلاعات عمومی | +| Streaming Response | پاسخ جریانی پیوسته | دریافت توکن‌به‌توکن کلمات مدل از طریق اینترنت برای ایجاد جلوه تایپ زنده بدون معطلی | +| Prompt Injection | تزریق پرامپت مخرب | ترفند کاربر برای دور زدن قوانین سیستمی مدل از طریق ارسال دستورات فریبکارانه | +| OpenRouter | روتر باز مدل‌های زبانی | پلتفرم تجمیع‌کننده مدل‌های هوش مصنوعی مختلف با یک رابط یکپارچه و کلید مشترک | + +--- + +## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders) +> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند: + +1. **تصویر کاور درس:** `images/cover.png` + * **موضوع:** مغز دیجیتال نئونی درخشان که یک ویجت چت شناور بنفش را روی صفحه سایت پورتفولیو زنده و فعال می‌کند. +2. **جریان فنی فراخوانی امن چت‌بات در Next.js:** `images/ai-chat-architecture.png` + * **موضوع:** دیاگرام معماری: کاربر در ویجت تایپ می‌کند $\rightarrow$ روت سرور `/api/chat` کانتکست رزومه را الصاق می‌کند $\rightarrow$ درخواست امن به OpenRouter/AvalAI $\rightarrow$ استریم پاسخ به کلاینت. +3. **ویجت چت‌بات تعاملی در گوشه پورتفولیو:** `images/portfolio-chat-widget-ui.png` + * **موضوع:** اسکرین‌شات از ویجت شناور در پورتفولیو با دکمه‌های پیشنهاد سوال سریع ("پروژه‌های شاخص"، "تجربه React"، "تماس با من"). +4. **تکنیک جلوگیری از توهم و تزریق پرامپت:** `images/prompt-guardrails-diagram.png` + * **موضوع:** اینفوگرافیک محافظتی: تلاش کاربر برای خروج از نقش $\rightarrow$ فیلتر قوانین System Prompt $\rightarrow$ بازگرداندن مودبانه مکالمه به مباحث رزومه. + +--- + +## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`) + +1. **تیتر اصلی:** `# تزریق مغز هوش مصنوعی به محصول؛ چت‌بات رزومه با OpenRouter و AvalAI` +2. **مقدمه:** تا پیش از این، با هوش مصنوعی کد می‌نوشتید؛ اکنون وقت آن است که هوش مصنوعی را به عنوان یک کارمند شبانه‌روزی داخل پروژه خود استخدام کنید! +3. **جدول کاور درس** +4. **استعاره منشی هوشمند و سخنگوی ۲۴ ساعته شما:** + * کارفرما ساعت ۲ نیمه‌شب می‌خواهد بداند شما برای پروژه‌اش مناسب هستید یا خیر؛ دستیار رزومه بیدار است و با تسلط کامل پاسخ می‌دهد. +5. **ساختار Chat Completions در مدل‌های زبانی (Roles: System, User, Assistant):** + * چگونگی هدایت هوش با تفکیک پیام‌های سه لایه. +6. **دریافت کلید API از OpenRouter یا سرویس‌های در دسترس داخلی (AvalAI):** + * ثبت نام سریع، دریافت کلید، و انتخاب مدل‌های مقرون‌به‌صرفه و سریع. +7. **طراحی پرامپت سیستمی طلایی با تکنیک Grounding:** + * تزریق رزومه به ساختار پرامپت: + ```markdown + You are the AI Portfolio Assistant for [Your Name], a Full-Stack Developer. + Here is the verified knowledge base about the creator: + - Experience: 3 years building modern web apps with Next.js, TypeScript, Tailwind. + - Top Projects: 1) Personal Portfolio with Supabase, 2) E-Commerce MVP. + - Availability: Open for freelance and full-time remote roles. + Strict Rules: + 1. ONLY answer questions about [Your Name]'s skills, experience, and projects. + 2. If asked about cooking, politics, or unrelated topics, politely decline. + 3. Never invent facts not listed in the knowledge base. + ``` +8. **ساخت روت سرور امن `/api/chat/route.ts` با قابلیت Streaming:** + * کد تمیز فراخوانی API به صورت استریم برای ایجاد حس پاسخ‌گویی بلادرنگ. +9. **طراحی کامپوننت ویجت شناور رزومه در فرانت‌اند:** + * دکمه آیکون چت در گوشه راست پایین، قابلیت مینیمایز، و دکمه‌های سریع (Quick Chips). +10. **جعبه پرامپت طلایی: ساخت کامل دستیار رزومه با ایجنت:** + * پرامپت دقیق: + > «من یک کلید `OPENROUTER_API_KEY` در `.env.local` دارم. لطفاً یک روت سرور `/api/chat` بساز که با مدل `deepseek/deepseek-chat` یا `openai/gpt-4o-mini` ارتباط برقرار کند. پرامپت سیستمی باید اطلاعات رزومه من را به صورت محرمانه در بر بگیرد. سپس یک ویجت چت شناور در پایین صفحه پورتفولیو اضافه کن که تاریخچه پیام‌ها را نمایش دهد، حالت لودینگ داشته باشد و متن پاسخ را به صورت تایپ زنده بنویسد.» +11. **دستورات چندسکویی برای پیکربندی متغیر محیطی هوش مصنوعی:** + * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس: + - Windows (PowerShell): + ```powershell + Add-Content .env.local "`nOPENROUTER_API_KEY=sk-or-v1-your-key-here" + ``` + - macOS (Terminal): + ```bash + echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" >> .env.local + ``` + - Linux (Bash): + ```bash + echo "OPENROUTER_API_KEY=sk-or-v1-your-key-here" >> .env.local + ``` +12. **باکس نکته امنیتی Quera (`
`):** مقابله با Prompt Injection؛ چرا کلید API هرگز نباید در کلاینت بماند و چطور کدهای مخرب کاربر را خنثی کنیم. +13. **باکس راهنمای بهینه‌سازی هزینه Quera (`
`):** کوتاه کردن هیستوری به ۶ چت آخر برای جلوگیری از هزینه اضافی. +14. **باکس هشدار Quera (`
`):** خطرات توهم مدل؛ حتماً تست کنید که مدل برای شما تخصص‌هایی که ندارید اختراع نکند! +15. **جمع‌بندی فصل دهم و پیش‌نمایش فصل یازدهم:** جشن اتصال کامل پورتفولیو به پیامک، ایمیل، درگاه پرداخت و هوش مصنوعی؛ ورود به فصل سرنوشت‌ساز یازدهم: امنیت و استفاده مسئولانه. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] تفاوت استفاده از AI به عنوان ابزار با AI به عنوان قابلیت محصول تبیین شود. +- [ ] ساختار فنی Chat Completions API به همراه نقشه پیام‌های System, User, Assistant تشریح گردد. +- [ ] تکنیک Grounding برای جلوگیری از توهم در دستیار رزومه پیاده‌سازی شود. +- [ ] پرامپت ایجنت برای ساخت ویجت شناور چت با قابلیت Streaming در متن قرار گیرد.