feat: add chapter 10-external-services specs

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. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
+   * کال‌اوت بنفش (`<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) به زبان ساده آموزش داده شود.