feat: add chapter 10-external-services specs

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. **کال‌اوت‌های کوئرا:**
+   * کال‌اوت سبز (`<details class="green">`): انگیزه و هیجان از اینکه پروژه با اولین تراکنش مالی یا اولین پیامک، جان می‌گیرد.
+
+### آنچه نباید وارد آن شویم (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 (`<details class="green">`):** لمس جادوی اتصال به درگاه پرداخت و دریافت پیامک واقعی روی موبایل شخصی.
+
+---
+
+## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
+- [ ] دورنمای فصل ۱۰ و مزایای استفاده از سرویس‌های شخص ثالث تبیین شود.
+- [ ] سرفصل‌های ۸ درس‌نامه بعدی با ذکر نام سرویس‌های بومی مصوب (کاوه‌نگار، لیارا، زرین‌پال) معرفی شوند.
+- [ ] ارزش تجاری و فنی یادگیری این فصل در ساخت MVPهای مقیاس‌پذیر به صورت روشن بیان گردد.