feat: add chapter 10-external-services specs

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://<project-id>.supabase.co/auth/v1/callback`).
+   * فعال‌سازی تاگل ارائه‌دهنده در داشبورد Authentication سوپابیس.
+4. **کدنویسی فرانت‌اند Next.js برای دکمه‌های ورود:**
+   * فراخوانی ساده `supabase.auth.signInWithOAuth({ provider: 'github' })`.
+   * هدایت خودکار کاربر پس از ورود موفق به پنل مدیریت (`/admin`).
+5. **معماری الگوی ورود بومی ایرانی: لاگین پیامکی (SMS OTP Login):**
+   * بررسی چرخه ورود در اپ‌های محبوب مانند اسنپ و دیجی‌کالا:
+     - ۱. کاربر شماره موبایل خود را وارد می‌کند.
+     - ۲. سرور یک کد تصادفی ۵ رقمی تولید کرده و با زمان انقضای ۲ دقیقه (TTL) در جدول یا سشن ذخیره می‌کند.
+     - ۳. فراخوانی الگوی اعتبارسنجی وب‌سرویس کاوه‌نگار/SMS.ir برای تحویل در ۲ ثانیه.
+     - ۴. کاربر کد را وارد می‌کند؛ سرور مطابقت داده و سشن لاگین ایجاد می‌کند.
+6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
+   * کال‌اوت بنفش (`<details class="violet">`): تفاوت OAuth (احراز هویت و اجازه دسترسی) با OIDC (شناسایی هویت پروفایل کاربر).
+   * کال‌اوت سبز (`<details class="green">`): مدیریت خودکار کوکی‌ها و رفرش توکن‌ها توسط کتابخانه `@supabase/ssr`.
+   * کال‌اوت قرمز (`<details class="red">`): تله خطای رایج `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 (`<details class="violet">`):** اهمیت هماهنگی دقیق Redirect URL در محیط Localhost و پس از دیپلوی روی دامنه نهایی.
+12. **باکس هشدار Quera (`<details class="red">`):** تله فاش کردن `Client Secret` گوگل در کدهای فرانت‌اند؛ این کلید فقط و فقط باید در پنل پشتیبانی سوپابیس ثبت شود.
+13. **باکس انرژی‌بخش Quera (`<details class="green">`):** آزمایش لاگین با گیت‌هاب شخصی خودتان و دیدن عکس پروفایل و ایمیلتان در داشبورد ادمین پورتفولیو.
+14. **جمع‌بندی درس‌نامه:** تکمیل مکانیزم‌های ورود؛ ورود به جذاب‌ترین بخش تجاری: اتصال درگاه پرداخت زرین‌پال در درس بعدی.
+
+---
+
+## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
+- [ ] اصول کارکرد پروتکل OAuth 2.0 به زبان قابل فهم برای افراد غیربرنامه‌نویس تبیین شود.
+- [ ] مراحل دریافت کلیدهای GitHub و Google و تنظیم آن‌ها در Supabase به شکل عملی بیان گردد.
+- [ ] معماری ورود بومی پیامکی (SMS OTP) به همراه گام‌های پیاده‌سازی تشریح شود.
+- [ ] نمونه کدهای اتصال فرانت‌اند و کال‌اوت‌های هشداری امنیتی لحاظ گردند.