# مشخصات درس‌نامه: احراز هویت (Authentication & Route Protection)
- **شناسه در سیلابس:** `L7.7`
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
- **پیش‌نیازهای مستقیم:** `L7.6` (اتصال پروژه به دیتابیس)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** تفاوت بنیادین میان احراز هویت (Authentication - شما چه کسی هستید؟) و سطح دسترسی (Authorization - شما اجازه ورود به کدام اتاق‌ها را دارید؟) چیست.
- [ ] **به‌کار ببندد (Apply):** حساب کاربری ادمین اصلی را در بخش کاربران داشبورد Supabase Auth ایجاد کرده و ثبت‌نام عمومی غریبه‌ها را غیرفعال سازد.
- [ ] **به‌کار ببندد (Apply):** صفحه ورود مدرن (`/login`) را با فیلدهای ایمیل، رمز عبور، مدیریت وضعیت‌های لودینگ و پیام خطای فارسی پیاده‌سازی کند.
- [ ] **به‌کار ببندد (Apply):** متد احراز هویت رسمی `supabase.auth.signInWithPassword` را فراخوانی کرده و کاربر را پس از تایید به داشبورد `/admin` هدایت کند.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** سازوکار محافظت از مسیرها (Route Guard) در Next.js را به کار گیرد؛ اطمینان حاصل کند که افراد بدون نشست فعال (Active Session) به طور خودکار به صفحه ورود ریدایرکت می‌شوند.

---

## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)

### آنچه باید پوشش داده شود (In-Scope):
1. **تفاوت مفهوم احراز هویت با تعیین سطح دسترسی:**
   * **Authentication (احراز هویت):** اثبات هویت با نام کاربری و رمز عبور (کارت ملی دیجیتال).
   * **Authorization (مجوز دسترسی):** بررسی اینکه آیا این کاربر تاییدشده، اجازه ویرایش کارهای پورتفولیو یا تغییر سئو را دارد یا فقط یک بیننده عادی است.
2. **پیکربندی اختصاصی احراز هویت در Supabase Auth:**
   * چرا در پورتفولیوی شخصی نیازی به فرم ثبت‌نام عمومی نیست؟
   * رفتن به Authentication $\rightarrow$ Users $\rightarrow$ Add User و ساخت حساب ادمین اختصاصی با ایمیل و پسورد امن.
   * خاموش کردن گزینه ثبت‌نام عمومی (Disable Public Signups) در تنظیمات Auth جهت حفظ انحصار مالک پورتفولیو.
3. **پیاده‌سازی صفحه ورود شیک (`src/app/login/page.tsx`):**
   * کارت تاریک و مینیمال با کامپوننت‌های شادسی‌ان (`Card`, `Input`, `Button`).
   * فرم دریافت ایمیل و رمز عبور.
   * دکمه ورود همراه با اسپینر لودینگ حین اعتبارسنجی.
   * نمایش خطای فارسی («ایمیل یا رمز عبور اشتباه است») در صورت اشتباه بودن رمز.
4. **منطق لاگین با کلاینت Supabase:**
   * اجرای متد `signInWithPassword`:
     ```typescript
     const { data, error } = await supabase.auth.signInWithPassword({
       email,
       password,
     });
     if (!error) {
       router.push('/admin');
     }
     ```
5. **محافظت از مسیرهای ادمین (Route Guard):**
   * پیاده‌سازی لایه نگهبان در `src/app/admin/layout.tsx`:
     * بررسی `supabase.auth.getSession()`.
     * اگر کاربری لاگین نبود $\rightarrow$ ریدایرکت فوری به `/login`.
     * اگر ادمین تایید شده بود $\rightarrow$ نمایش محتوای داشبورد و سایدبار.
6. **دکمه خروج ایمن (Sign Out):**
   * فراخوانی `supabase.auth.signOut()` و بازگشت به صفحه اصلی سایت.
7. **کال‌اوت‌های Quera:**
   * `<details class="violet">`: تفاوت بنیادین Authentication و Authorization؛ دو ستون تفکیک‌ناپذیر امنیت نرم‌افزار.
   * `<details class="red">`: غیرفعال کردن ثبت‌نام عمومی؛ پورتفولیوی شخصی متعلق به شماست، اجازه ندهید افراد متفرقه با ایمیل خود در دیتابیس شما کاربر بسازند!

### آنچه نباید وارد آن شویم (Out-of-Scope):
- لاگین‌های اجتماعی پیشرفته (Google OAuth یا GitHub OAuth) در این مرحله.
- تایید دو مرحله‌ای پیامکی (2FA) یا بازیابی رمز با سرویس‌های ایمیل شخص ثالث (فصل ۱۰).

---

## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Authentication (AuthN) | احراز هویت | فرایند تایید هویت کاربر با بررسی اعتبار اطلاعات ورودی (ایمیل و رمز عبور) |
| Authorization (AuthZ) | اعطای مجوز دسترسی | تعیین سطح دسترسی کاربر تاییدشده برای مشاهده یا دستکاری بخش‌های خاص نرم‌افزار |
| Active Session | نشست فعال کاربری | وضعیت برقراری ارتباط احراز هویت‌شده که در کوکی‌های امن مرورگر ذخیره می‌شود |
| Route Guard | نگهبان مسیر | سد امنیتی نرم‌افزاری که ورود به صفحات محافظت‌شده را مشروط به لاگین بودن کاربر می‌کند |
| Public Signup Disable | بستن ثبت‌نام عمومی | تنظیم امنیتی برای جلوگیری از ثبت‌نام افراد متفرقه در نرم‌افزارهای تک‌کاربره یا مدیریتی |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** کاور مدرن با تم تیره و یک قفل دیجیتال نئونی درخشان که درگاه ورود به پنل مدیریت را با کارت اعتباری امنیتی محافظت می‌کند.
2. **تفاوت احراز هویت با مجوز دسترسی:** `images/authn-vs-authz-diagram.png`
   * **موضوع:** تصویر مقایسه‌ای: کارت شناسایی عکس‌دار (احراز هویت: شما مریم هستید) در برابر کلید دسترسی اتاق سرور (مجوز دسترسی: آیا کلید این در را دارید؟).
3. **پنل مدیریت کاربران در استودیو Supabase:** `images/supabase-auth-users-admin.png`
   * **موضوع:** اسکرین‌شات از تب Authentication با نمایش کاربر ادمین ساخته‌شده و تیک سبز تایید هویت.
4. **صفحه لاگین طراحی‌شده در فرانت‌اند:** `images/login-page-interface.png`
   * **موضوع:** اسکرین‌شات از کارت ورود به پنل ادمین روی آدرس `localhost:3000/login` با استایل شیک شیشه‌ای.
5. **فلوچارت نگهبان مسیر (Route Guard Flow):** `images/route-guard-redirect-flow.png`
   * **موضوع:** نمودار تصمیم‌گیری: کاربر به `/admin` می‌رود $\rightarrow$ شرط بررسی نشست فعال $\rightarrow$ بله: نمایش داشبورد / خیر: ریدایرکت خودکار به `/login`.

---

## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)

1. **تیتر اصلی:** `# احراز هویت: نصب قفل امنیتی بر دروازه پنل مدیریت`
2. **مقدمه:** چرا یک نرم‌افزار تجاری بدون سیستم احراز هویت، شبیه به خانه‌ای بدون در و پیکر است؟
3. **جدول کاور درس**
4. **تفاوت بنیادین احراز هویت (AuthN) و مجوز دسترسی (AuthZ):** مفهوم هویت در برابر اجازه.
5. **تنظیم حساب ادمین در Supabase Auth:**
   * ساخت دستی ادمین در داشبورد ابری.
   * بستن ثبت‌نام عمومی برای حفظ مالکیت اختصاصی.
6. **باکس هشدار Quera (`<details class="red">`):** اهمیت قفل کردن ثبت‌نام در پورتفولیوی تک‌کاربره.
7. **طراحی و ساخت صفحه ورود شیک (`/login`):**
   * کامپوننت‌های فرم و وضعیت لودینگ.
   * مدیریت خطاهای رمز عبور نادرست.
8. **فراخوانی متد لاگین با کلاینت سوپابیس (`signInWithPassword`):** ورود به حریم امن.
9. **محافظت از مسیرها با Route Guard در Next.js:** ریدایرکت خودکار غریبه‌ها به صفحه ورود.
10. **باکس نکته Quera (`<details class="violet">`):** تمایز دو مفهوم AuthN و AuthZ در مهندسی وب مدرن.
11. **دکمه خروج ایمن (Sign Out):** پاک کردن نشست و بازگشت به صفحه اصلی.
12. **جمع‌بندی درس‌نامه:** امن شدن کامل پنل مدیریت و ورود به درس نهایی فصل: امنیت سطح ردیف (RLS) در دیتابیس.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] تفاوت احراز هویت و مجوز دسترسی با ادبیات دقیق و تمثیل ملموس تبیین شده باشد.
- [ ] مراحل ساخت کاربر ادمین در Supabase و لزوم غیرفعال‌سازی ثبت‌نام عمومی مستند گردد.
- [ ] کدهای صفحه لاگین و فراخوانی متد `signInWithPassword` به طور کامل در متن لحاظ شوند.
- [ ] منطق محافظت از مسیر `/admin` با مکانیزم ریدایرکت امن تشریح شود.