# مشخصات درس‌نامه: اهداف فصل دهم (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های مقیاس‌پذیر به صورت روشن بیان گردد.