# مشخصات درس‌نامه: ارائه‌دهندگان احراز هویت خارجی (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) به همراه گام‌های پیاده‌سازی تشریح شود.
- [ ] نمونه کدهای اتصال فرانت‌اند و کال‌اوت‌های هشداری امنیتی لحاظ گردند.