# مشخصات درس‌نامه: سرویس 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. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): مفهوم وب‌هوک (Webhook)؛ وقتی سرویس خارجی به سرور شما اطلاع‌رسانی معکوس می‌کند.
   * کال‌اوت سبز (`<details class="green">`): محیط‌های رایگان و اعتبارهای هدیه آغازین سرویس‌های بومی و بین‌المللی برای تست.
   * کال‌اوت قرمز (`<details class="red">`): وابستگی انحصاری (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 (`<details class="violet">`):** وب‌هوک‌ها چگونه کار می‌کنند؟ تفاوت این که ما مدام استعلام بگیریم (Polling) یا اینکه سرویس خودش زنگ بزند (Webhook).
8. **اصل ایمنی حیاتی: کلیدهای محرمانه هرگز به مرورگر کاربر نمی‌روند!**
   * توضیح ساده نحوه میانجی‌گری Next.js Server Actions برای محافظت از سرمایه و اعتبار شما.
9. **باکس هشدار Quera (`<details class="red">`):** خطر قفل شدن به یک شرکت خاص (Vendor Lock-in) و توصیه به تمیز نوشتن کد با توابع واسط.
10. **باکس انرژی‌بخش Quera (`<details class="green">`):** خوشبختانه تقریباً تمام سرویس‌های مدرن دارای پنل‌های آزمایشی و سهمیه تست رایگان هستند.
11. **جمع‌بندی درس‌نامه:** تسلط مفهومی بر سرویس‌های شخص ثالث و ورود به دنیای خواندن مستندات فنی API و مدیریت امن متغیرها در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] استعاره قطعات لگو و دوراهی Build vs Buy به صورت شفاف و قانع‌کننده تحلیل شود.
- [ ] پنج دسته اصلی سرویس‌های ابری با مثال‌های متناسب با نیاز ایران معرفی گردند.
- [ ] چرخه درخواست امن سمت سرور برای حفظ کلیدهای اختصاصی به صورت گرافیکی و متنی تبیین شود.
- [ ] مفهوم وب‌هوک (Webhook) به زبان ساده آموزش داده شود.