feat: add chapter 07-database-and-backend specs
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# مشخصات درس‌نامه: اهداف فصل هفتم (Chapter Goals)
|
||||
- **شناسه در سیلابس:** `L7.1`
|
||||
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۵ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L6.7` (تعامل با Agentها برای بهبود و توسعه تدریجی کد)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** جایگاه بنیادین پایگاه داده و بک‌اند به عنوان قلب تپنده و حافظه دائمی هر نرم‌افزار تجاری واقعی را درک کند.
|
||||
- [ ] **درک کند (Understand):** نقشه راه ۸ درس‌نامه مفهومی و کاربردی این فصل (از مفاهیم جدول و رکوردهای دیتابیس تا معماری REST API، راه‌اندازی Supabase، ساخت اسکیما، اتصال پروژه، احراز هویت ادمین و امنیت RLS) چگونه چیده شده است.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چگونگی گذار از داده‌های شبیه‌سازی‌شده (Mock Data فصل ۶) به پایگاه داده ابری زنده و ماندگار PostgreSQL را درک کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** ذهنیت خود را برای اتصال کامل پروژه محوری (پورتفولیوی پویا) به دیتابیس و آماده‌سازی برای تحویل نخستین نقطه عطف بزرگ دوره (پروژه ۱ در فصل ۸) تنظیم نماید.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **ورود به قلمرو حافظه ماندگار نرم‌افزار:**
|
||||
* در فصل ۶ ظاهر و فرانت‌اند ساخته شد؛ اما هر بار که صفحه رفرش می‌شود تغییرات پاک می‌شوند چون حافظه دائمی وجود ندارد؛ در این فصل به برنامه حافظه و هوشمندی بک‌اند می‌بخشیم.
|
||||
2. **مرور سرفصل‌های فصل ۷:**
|
||||
* درس ۷.۲: داده و دیتابیس چیست؛ ردیف‌ها، ستون‌ها، کلیدهای اصلی (Primary Key) و استعاره فایل اکسل ابرقدرت.
|
||||
* درس ۷.۳: مفهوم API و مکالمه کلاینت با سرور؛ متدهای چهارگانه GET, POST, PUT, DELETE.
|
||||
* درس ۷.۴: آشنایی با پلتفرم Supabase (آلترناتیو متن‌باز فایربیس بر پایه قدرتمندترین دیتابیس جهان، PostgreSQL).
|
||||
* درس ۷.۵: طراحی و ساخت جداول پروژه (`projects` برای نمونه‌کارها و `site_settings` برای متادیتای سئو).
|
||||
* درس ۷.۶: اتصال واقعی فرانت‌اند به دیتابیس و خداحافظی با Mock Data.
|
||||
* درس ۷.۷: احراز هویت (Auth)؛ لاگین ایمن ادمین با ایمیل/پسورد و محافظت از روت `/admin`.
|
||||
* درس ۷.۸: امنیت پایگاه داده با Row Level Security (RLS)؛ تعیین اینکه چه کسی حق خواندن و چه کسی حق ویرایش دارد.
|
||||
3. **آماده‌سازی برای فینال فاز اول (پروژه ۱):**
|
||||
* تکمیل این فصل به معنای اتمام کامل فونداسیون، فرانت‌اند و بک‌اند پورتفولیوی پویاست که مستقیماً در فصل ۸ ارزیابی خواهد شد.
|
||||
4. **کال‌اوت نکته کوئرا (`<details class="green">`):** اهمیت حفظ خونسردی در برابر اصطلاحات بک‌اند؛ تمام مفاهیم با استعاره‌های ساده و ملموس تدریس خواهند شد.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- طراحی دیتابیس‌های توزیع‌شده با میلیون‌ها تراکنش بانکی (فصول پیشرفته).
|
||||
- پیاده‌سازی وب‌سوکت‌ها یا پردازش‌های پس‌زمینه (فصل ۱۳).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Persistent Storage | ذخیره‌سازی ماندگار | نگهداری دائمی داده‌ها روی هارد سرور به گونه‌ای که با خاموش شدن سیستم یا رفرش صفحه پاک نشوند |
|
||||
| Backend-as-a-Service (BaaS) | بک‌اند به عنوان سرویس | پلتفرم ابری آماده (مانند Supabase) که بدون نیاز به سرورنویسی، دیتابیس و احراز هویت تحویل می‌دهد |
|
||||
| Database Schema | اسکیمای پایگاه داده | ساختار مهندسی و نقشه تعریف جداول، نام ستون‌ها و نوع فیلدهای ذخیره‌سازی داده |
|
||||
| Milestone Project 1 | نقطه عطف پروژه اول | پروژه عملی ارزیابی شایستگی در پایان فصل ۸ که پورتفولیوی متصل به دیتابیس را می‌سنجد |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** کاور مدرن با تم تیره و استوانه نورانی دیتابیس سبز نئونی (لوگوی سوپابیس) که پالس‌های داده را به سمت مرورگر فرانت‌اند ارسال می‌کند.
|
||||
2. **نقشه راه یادگیری فصل ۷:** `images/chapter-7-roadmap.png`
|
||||
* **موضوع:** اینفوگرافیک گام‌به‌گام از مبانی دیتابیس $\rightarrow$ مفهوم API $\rightarrow$ سوپابیس $\rightarrow$ طراحی جداول $\rightarrow$ اتصال فرانت‌اند $\rightarrow$ لاگین ادمین $\rightarrow$ امنیت RLS $\rightarrow$ ورود به پروژه ۱.
|
||||
3. **معماری پورتفولیوی پویا در فصل ۷:** `images/fullstack-portfolio-architecture.png`
|
||||
* **موضوع:** دیاگرام ارتباطی: فرانت‌اند Next.js $\rightarrow$ کلاینت Supabase $\rightarrow$ دیتابیس ابری PostgreSQL با جداول پروژه‌ها و تنظیمات سئو.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# اهداف فصل هفتم: داده و بک‌اند؛ دمیدن روح جاودانگی به نرم‌افزار`
|
||||
2. **مقدمه کوتاه:** چرا زیباترین فرانت‌اند دنیا بدون پایگاه داده، مثل ویترین مغازه‌ای است که اجناس پشت آن ماکت پلاستیکی هستند؟
|
||||
3. **جدول کاور درس**
|
||||
4. **سرفصل‌های کلیدی فصل در یک نگاه:** مرور ۸ گام اتصال به دنیای داده‌ها و امنیت.
|
||||
5. **جدول نقشه راه یادگیری فصل**
|
||||
6. **معرفی سکوی پرتاب: پلتفرم ابری Supabase:** دیتابیس حرفه‌ای بدون نیاز به تنظیمات دشوار سرور.
|
||||
7. **پل اتصال به پروژه ۱ (نقطه عطف فصل ۸):** هدف‌گذاری برای اتمام کامل نخستین محصول واقعی.
|
||||
8. **کال‌اوت آرامش‌بخش Quera (`<details class="green">`):** ثبت دکمه «خواندم» و آغاز سفر به دنیای شگفت‌انگیز داده‌ها.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] اهداف فصل و ضرورت یادگیری بک‌اند برای تبدیل پروتوتایپ به محصول واقعی تبیین شده باشد.
|
||||
- [ ] نقشه راه ۸ درس‌نامه بعدی به همراه معرفی Supabase و امنیت RLS پوشش داده شود.
|
||||
- [ ] پیوند این فصل با پروژه عملی اول در فصل ۸ به وضوح تشریح گردد.
|
||||
@@ -0,0 +1,99 @@
|
||||
# مشخصات درس‌نامه: داده و دیتابیس چیست (Database Fundamentals)
|
||||
- **شناسه در سیلابس:** `L7.2`
|
||||
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L7.1` (اهداف فصل هفتم)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** پایگاه داده (Database) چیست و استعاره «اکسل ابرقدرت و بدون کرش» چگونه ماهیت جداول، سطرها و ستون‌ها را تبیین می‌کند.
|
||||
- [ ] **درک کند (Understand):** مفاهیم ساختاری جدول: **ستون (Column)، سطر یا رکورد (Row/Record)، کلید اصلی (Primary Key)، و انواع داده (Data Types: متن، عدد، تاریخ، بولین)** را توضیح دهد.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** تفاوت پایگاه‌های داده رابطه‌ای (SQL نظیر PostgreSQL) را با پایگاه‌های داده سندرومحور (NoSQL) مقایسه کرده و چرایی برتری PostgreSQL را درک کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** ساختار دو جدول اصلی پروژه محوری (جدول `projects` و جدول `site_settings`) را روی کاغذ یا بوم معماری داده رسم و فیلدهای آن‌ها را مشخص کند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **استعاره فایل اکسل ابرقدرت (Superpowered Excel):**
|
||||
* پایگاه داده در ساده‌ترین تعریف، مانند یک دفترچه اکسل بسیار سریع، امن و آنلاین است که میلیون‌ها کاربر می‌توانند هم‌زمان و بدون کرش کردن، اطلاعات را در آن بخوانند یا ذخیره کنند.
|
||||
2. **کالبدشکافی ارکان پایگاه داده:**
|
||||
* **جدول (Table):** یک برگه اختصاصی برای یک موجودیت مشخص (مثل جدول پروژه‌ها یا جدول کاربران).
|
||||
* **ستون یا فیلد (Column / Field):** یک ویژگی مشخص از موجودیت (مثل ستون عنوان، ستون عکس، ستون تاریخ ایجاد).
|
||||
* **سطر یا رکورد (Row / Record):** یک نمونه واقعی ثبت‌شده در جدول (مثلاً سطر مربوط به پروژه «دستیار عادات هوشمند»).
|
||||
* **کلید اصلی (Primary Key):** کد ملی یا شناسه یکتای هر سطر که هیچ دو سطری نمی‌توانند شناسه مشابه داشته باشند (معرفی شناسه جهانی UUID).
|
||||
3. **انواع داده‌های پرکاربرد در دیتابیس:**
|
||||
* `text` / `varchar`: برای رشته‌های متنی (عنوان، توضیحات).
|
||||
* `boolean`: برای فیلدهای دوحالته درست/غلط (مثل فیلد `featured` برای پروژه‌های ویژه).
|
||||
* `timestamp`: برای تاریخ و ساعت ایجاد (`created_at`).
|
||||
* `text[]` (آرایه متنی): برای ذخیره تگ‌های تکنولوژی (`['React', 'Next.js']`).
|
||||
4. **تفاوت SQL در برابر NoSQL:**
|
||||
* دیتابیس‌های رابطه‌ای (SQL): ساختار منظم، جدول‌بندی مهندسی، داده‌های یکدست و امن (چرا PostgreSQL پادشاه دیتابیس‌های جهان است؟).
|
||||
* دیتابیس‌های NoSQL: ذخیره آزاد اسناد به شکل JSON.
|
||||
5. **نقشه داده‌های پروژه محوری (پورتفولیوی پویا):**
|
||||
* **جدول ۱ (`projects`):** فیلدهای `id` (UUID), `title`, `description`, `image_url`, `tags`, `live_url`, `github_url`, `created_at`.
|
||||
* **جدول ۲ (`site_settings`):** فیلدهای `id`, `site_title`, `meta_description`, `og_image_url`, `author_name`, `bio`.
|
||||
6. **کال‌اوت‌های Quera:**
|
||||
* `<details class="violet">`: چرا شناسه‌های تصادفی و طولانی (UUID) در وب مدرن بر شناسه‌های عددی ساده (`1, 2, 3`) ارجحیت دارند؟
|
||||
* `<details class="red">`: تله انتخاب نوع داده اشتباه؛ ذخیره کردن تاریخ یا اعداد در قالب متن خام (`text`) و مصیبت‌های بعدی در جستجو و مرتب‌سازی.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- نوشتن کوئری‌های پیچیده SQL با دستورات `JOIN`های چندگانه تو در تو.
|
||||
- ثبت‌نام و ساخت عملی پروژه در داشبورد Supabase (درس‌های ۷.۴ و ۷.۵).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Relational Database (RDBMS) | پایگاه داده رابطه‌ای | سیستمی برای ذخیره و سازماندهی داده‌ها در قالب جداول دارای سطر و ستون منظم |
|
||||
| Primary Key (PK) | کلید اصلی | فیلد منحصربه‌فردی که هویت یکتا و تمایز قطعی هر سطر در جدول را تضمین می‌کند |
|
||||
| UUID (Universally Unique ID) | شناسه جهانی یکتا | رشته متنی تصادفی و ۳۶ کاراکتری که احتمال تکرار آن در کل جهان نزدیک به صفر است |
|
||||
| Data Types | انواع داده | فرمت‌های معین برای مقادیر مجاز هر ستون (نظیر متن، عدد، تاریخ و منطقی) |
|
||||
| PostgreSQL | پستگرس‌کیو‌ال | پیشرفته‌ترین، پایدارترین و محبوب‌ترین موتور پایگاه داده متن‌باز رابطه‌ای در جهان |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** کاور مدرن با تم تیره و یک استوانه بلورین دیتابیس با طبقه‌های نوری منظم سطرها و ستون‌های داده که در فضا شناور است.
|
||||
2. **استعاره اکسل در برابر پایگاه داده:** `images/excel-vs-database-analogy.png`
|
||||
* **موضوع:** تصویر مقایسه‌ای: شیت ساده اکسل در برابر پایگاه داده رابطه‌ای با هزاران رکورد سریع و ایمن.
|
||||
3. **آناتومی یک جدول پایگاه داده:** `images/database-table-anatomy.png`
|
||||
* **موضوع:** اینفوگرافیک برچسب‌گذاری‌شده جدول: ستون‌ها، ردیف‌ها، کلید اصلی UUID و نوع داده هر ستون.
|
||||
4. **مقایسه ساختار SQL و NoSQL:** `images/sql-vs-nosql-comparison.png`
|
||||
* **موضوع:** دیاگرام مقایسه جداول ساخت‌یافته رابطه‌ای PostgreSQL در برابر اسناد انعطاف‌پذیر JSON.
|
||||
5. **نقشه جداول پورتفولیوی پویا:** `images/portfolio-tables-schema.png`
|
||||
* **موضوع:** تصویر شماتیک دو جدول `projects` و `site_settings` با نام ستون‌ها و انواع داده مجاز.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# داده و دیتابیس چیست: راز ماندگاری اطلاعات در دنیای دیجیتال`
|
||||
2. **مقدمه:** چرا بدون پایگاه داده، بهترین وب‌سایت‌ها با بستن تب مرورگر همه چیز را فراموش می‌کنند؟
|
||||
3. **جدول کاور درس**
|
||||
4. **استعاره فایل اکسل ابرقدرت:** کالبدشکافی مفهوم پایگاه داده به زبان ساده.
|
||||
5. **چهار رکن اساسی هر دیتابیس:**
|
||||
* جدول (Table)، ستون (Column)، سطر (Row) و کلید اصلی (Primary Key).
|
||||
6. **باکس نکته Quera (`<details class="violet">`):** چرا در پروژه‌های نوین از شناسه UUID استفاده می‌کنیم؟
|
||||
7. **انواع داده‌های پرکاربرد: متن، عدد، تاریخ و بولین:** جلوگیری از خطاهای رایج.
|
||||
8. **پایگاه‌های داده رابطه‌ای (SQL) در برابر NoSQL:** چرا PostgreSQL انتخاب استاندارد است؟
|
||||
9. **طراحی نقشه داده‌های پورتفولیوی پویا:** کالبدشکافی جداول پروژه‌ها و تنظیمات سئو.
|
||||
10. **باکس هشدار Quera (`<details class="red">`):** عواقب انتخاب اشتباه نوع داده ستون‌ها.
|
||||
11. **جمع‌بندی درس‌نامه:** تسلط بر مفاهیم بنیادین داده و ورود به شاهراه ارتباطی فرانت‌اند با بک‌اند (APIها).
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] مفاهیم جدول، سطر، ستون و کلید اصلی با زبان ملموس و روان شرح داده شده باشند.
|
||||
- [ ] انواع داده‌های اصلی به همراه دلیل نیاز به نوع‌های معین تدریس شوند.
|
||||
- [ ] ساختار جداول پروژه پورتفولیو (`projects` و `site_settings`) در متن مشخص گردند.
|
||||
- [ ] تفاوت SQL و NoSQL با تاکید بر جایگاه PostgreSQL تبیین شده باشد.
|
||||
@@ -0,0 +1,101 @@
|
||||
# مشخصات درس‌نامه: مفهوم API و ارتباط سرور با فرانت‌اند (APIs & HTTP Methods)
|
||||
- **شناسه در سیلابس:** `L7.3`
|
||||
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L7.2` (داده و دیتابیس چیست)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** رابط برنامه‌نویسی نرم‌افزار (API) چیست و استعاره مشهور «گارسون رستوران» چگونه چرخه ارتباط میان مشتری (فرانت‌اند) و آشپزخانه (پایگاه داده) را توضیح می‌دهد.
|
||||
- [ ] **درک کند (Understand):** چرخه درخواست و پاسخ (Request-Response Cycle) و ساختار داده‌های مبادلاتی در قالب زبان جهانی **JSON** چگونه کار می‌کنند.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چهار متد اساسی پروتکل HTTP و تطبیق آن‌ها با عملیات چهارگانه CRUD شامل: **GET (خواندن)، POST (ایجاد)، PUT/PATCH (ویرایش)، و DELETE (حذف)** را درک کند.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** کدهای وضعیت استاندارد HTTP (کدهای ۲۰۰ موفق، ۴۰۱ عدم دسترسی، ۴۰۴ پیدا نشدن، و ۵۰۰ خطای سرور) را برای خطایابی ارتباطات نرم‌افزار تفسیر کند.
|
||||
- [ ] **درک کند (Understand):** پلتفرم‌های نوین BaaS (مانند Supabase) چگونه بدون نیاز به نوشتن دستی صدها خط کد سرور، به صورت خودکار برای هر جدول یک REST API امن تولید می‌کنند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **استعاره گارسون رستوران (The Restaurant Waiter Analogy):**
|
||||
* شما (کاربر/فرانت‌اند) پشت میز نشسته‌اید و منو را می‌بینید، اما اجازه ندارید خودتان وارد آشپزخانه (دیتابیس) شوید و قابلمه‌ها را دستکاری کنید!
|
||||
* گارسون (API): سفارش شما را به آشپزخانه می‌برد، سرآشپز غذا را آماده می‌کند، و گارسون بشقاب آماده (پاسخ داده‌ها) را به میز شما بازمی‌گرداند.
|
||||
2. **کالبدشکافی چرخه درخواست و پاسخ (Request & Response):**
|
||||
* **درخواست (Request):** شامل آدرس اینترنتی (Endpoint)، روش عمل (HTTP Method)، سربرگ‌ها (Headers شامل توکن ورود)، و بدنه داده‌ها (Body).
|
||||
* **پاسخ (Response):** شامل کد وضعیت (Status Code) و بسته اطلاعات نهایی در قالب استاندارد **JSON**.
|
||||
3. **متدهای چهارگانه HTTP در پروژه محوری (عملیات CRUD):**
|
||||
* `GET /api/projects`: دریافت لیست تمام کارت‌های پروژه‌ها برای نمایش در ویترین عمومی (خواندن - Read).
|
||||
* `POST /api/projects`: ارسال اطلاعات یک پروژه جدید توسط ادمین برای ذخیره در دیتابیس (ایجاد - Create).
|
||||
* `PATCH /api/projects/123`: ویرایش عنوان یا عکس یک پروژه مشخص (بروزرسانی - Update).
|
||||
* `DELETE /api/projects/123`: حذف دائمی یک پروژه از پایگاه داده (حذف - Delete).
|
||||
4. **الفبای کدهای وضعیت (Status Codes): چراغ راهنمایی وب:**
|
||||
* خانواده ۲۰۰ (سبز - موفقیت): `200 OK` (عملیات موفق)، `201 Created` (پروژه با موفقیت ساخته شد).
|
||||
* خانواده ۴۰۰ (زرد - خطای کلاینت): `400 Bad Request` (ورودی نامعتبر)، `401 Unauthorized` (لاگین نکرده‌اید)، `404 Not Found` (یافت نشد).
|
||||
* خانواده ۵۰۰ (قرمز - خطای سرور): `500 Internal Server Error` (کرش دیتابیس یا خطای باگ بک‌اند).
|
||||
5. **فرمت جهانی JSON:** نمایش ساختار کلید-مقدار ساده در زبان تبادل داده‌ها.
|
||||
6. **کال‌اوت‌های Quera:**
|
||||
* `<details class="violet">`: استعاره گارسون رستوران؛ امن‌ترین روش حفظ پایگاه داده از دسترسی مستقیم مرورگرها.
|
||||
* `<details class="red">`: کدهای وضعیت HTTP؛ نیمی از مهارت حل باگ در وایب کدینگ، نگاه کردن به کد عددی پاسخ سرور در تب Network مرورگر است.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- نوشتن سرور دستی با پایتون FastAPI یا Node.js Express (سوپابیس این کار را خودکار می‌کند).
|
||||
- پروتکل‌های GraphQL یا gRPC (پیچیدگی غیرضروری برای این دوره).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| API (Application Programming Interface) | رابط برنامه‌نویسی کاربردی | پل و زبان مشترک ارتباطی که اجازه می‌دهد دو نرم‌افزار با یکدیگر تبادل داده کنند |
|
||||
| REST API | رِست ای‌پی‌آی | معماری استاندارد و وب‌محور برای تبادل داده‌ها با استفاده از متدهای پروتکل HTTP |
|
||||
| HTTP Methods / Verbs | متدهای پروتکل وب | دستورات استاندارد مشخص‌کننده نوع عملیات روی داده‌ها (GET, POST, PUT, DELETE) |
|
||||
| HTTP Status Code | کد وضعیت پاسخ وب | عدد سه‌رقمی استاندارد که موفقیت یا نوع خطای پاسخ سرور را نشان می‌دهد |
|
||||
| JSON | نمادگذاری اشیاء جاوااسکریپت | سبک‌ترین و پرکاربردترین فرمت متنی تبادل اطلاعات مبتنی بر جفت‌های کلید و مقدار |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** کاور مدرن با تم تیره که دو جزیره دیجیتال فرانت‌اند و دیتابیس را متصل به یک پل نوری درخشان با نشانهای متدهای GET, POST, DELETE نشان می‌دهد.
|
||||
2. **استعاره گارسون رستوران در عملکرد API:** `images/api-restaurant-waiter-analogy.png`
|
||||
* **موضوع:** تصویر شماتیک: مشتری روی صندلی (فرانت‌اند) $\rightarrow$ گارسون مودب (API) $\rightarrow$ آشپزخانه محافظت‌شده (دیتابیس).
|
||||
3. **چرخه رفت‌وبرگشت درخواست و پاسخ:** `images/request-response-cycle.png`
|
||||
* **موضوع:** اینفوگرافیک دوسطره: سطر بالا ارسال Request با متد و بادی $\rightarrow$ سطر پایین دریافت Response با کد وضعیت ۲۰۰ و دیتای JSON.
|
||||
4. **ماتریس تطبیق متدها با عملیات CRUD:** `images/crud-to-http-verbs.png`
|
||||
* **موضوع:** جدول شماتیک ۴ ردیفه: ایجاد (Create = POST)، خواندن (Read = GET)، ویرایش (Update = PATCH)، حذف (Delete = DELETE).
|
||||
5. **چراغ راهنمایی کدهای وضعیت HTTP:** `images/http-status-codes-traffic-light.png`
|
||||
* **موضوع:** تصویر جذاب ۳ چراغ: سبز (۲۰۰ و ۲۰۱)، زرد (۴۰۱ و ۴۰۴)، قرمز (۵۰۰) با توضیحات کوتاه کاربردی.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# مفهوم API و ارتباط سرور با فرانت‌اند: شاهراه مکالمه در وب`
|
||||
2. **مقدمه:** چرا فرانت‌اند هرگز نباید به طور مستقیم به پایگاه داده وصل شود؟
|
||||
3. **جدول کاور درس**
|
||||
4. **استعاره گارسون رستوران: API دقیقاً چه کار می‌کند؟:** منطق امنیت و واسطه‌گری.
|
||||
5. **کالبدشکافی درخواست و پاسخ (Request & Response):** اجزای یک مکالمه در اینترنت.
|
||||
6. **چهار متد اصلی HTTP در دنیای واقعی:**
|
||||
* متد GET برای خواندن پروژه‌ها.
|
||||
* متد POST برای ایجاد پروژه جدید.
|
||||
* متد PATCH برای ویرایش متادیتا و سئو.
|
||||
* متد DELETE برای حذف.
|
||||
7. **زبان مادری وب: فرمت داده‌های JSON:** ساختار ساده و کاربردی کلید-مقدار.
|
||||
8. **باکس نکته Quera (`<details class="violet">`):** چرا Supabase نیاز به نوشتن دستی کدهای API را برای همیشه حذف کرد؟
|
||||
9. **رمزگشایی از کدهای وضعیت HTTP (چراغ راهنمای خطاها):** تفاوت خطای ۴۰۱ با ۴۰۴ و ۵۰۰.
|
||||
10. **باکس هشدار Quera (`<details class="red">`):** تب Network در ابزار DevTools مرورگر؛ کلید کشف مشکلات ارتباطی فرانت‌اند با سرور.
|
||||
11. **جمع‌بندی درس‌نامه:** تسلط بر مفاهیم ارتباطی و ورود به درس راه‌اندازی عملی پروژه در پلتفرم ابری Supabase.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] استعاره گارسون برای تفهیم نقش واسطه‌ای و امنیتی API به زبان ساده بیان شده باشد.
|
||||
- [ ] متدهای چهارگانه HTTP و تطبیق آن‌ها با عملیات CRUD در سناریوی پروژه پورتفولیو توضیح داده شود.
|
||||
- [ ] کدهای وضعیت اصلی به همراه تحلیل علت رخداد هرکدام آموزش داده شوند.
|
||||
- [ ] فرمت JSON و ساختار تبادل پیام با کدهای نمونه مستند گردد.
|
||||
@@ -0,0 +1,108 @@
|
||||
# مشخصات درس‌نامه: آشنایی با Supabase و راه‌اندازی پروژه (Introduction to Supabase)
|
||||
- **شناسه در سیلابس:** `L7.4`
|
||||
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L7.3` (مفهوم API و ارتباط سرور با فرانت‌اند)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** پلتفرم Supabase چیست و چرا به عنوان آلترناتیو متن‌باز فایربیس بر پایه دیتابیس صنعتی PostgreSQL، بهترین انتخاب برای توسعه‌دهندگان وایب کدینگ است.
|
||||
- [ ] **به‌کار ببندد (Apply):** یک حساب کاربری رایگان در Supabase ایجاد کرده و نخستین پروژه ابری خود را با رمز عبور قوی و انتخاب نزدیک‌ترین ریجن جغرافیایی بسازد.
|
||||
- [ ] **درک کند (Understand):** بخش‌های اصلی پیشخوان (Supabase Studio) شامل: **ویرایشگر بصری جداول (Table Editor)، ویرایشگر کوئری‌ها (SQL Editor)، بخش احراز هویت (Auth)، و تنظیمات کلیدهای API** را بازشناسی کند.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** تفاوت حیاتی میان کلید عمومی کلاینت (`anon key` تحت حفاظت RLS) و کلید محرمانه ادمین (`service_role key`) را تحلیل کرده و اصول امنیتی نگهداری آن را رعایت کند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **پلتفرم Supabase چیست و چرا عاشق آن می‌شوید؟**
|
||||
* ارائه یک سرور بک‌اند کامل ابری بدون نیاز به سرورنویسی و خرید هاست‌های سنتی.
|
||||
* قابلیت‌های یکپارچه: پایگاه داده رابطه‌ای PostgreSQL، سیستم ورود و ثبت‌نام کاربران، ذخیره‌سازی فایل‌ها و تصاویر، و تولید آنی REST API.
|
||||
2. **ساخت گام‌به‌گام پروژه در Supabase:**
|
||||
* ثبت‌نام در وب‌سایت با حساب GitHub (که در فصل ۳ ساخته شد).
|
||||
* زدن دکمه New Project، انتخاب نام برای پروژه (`vibe-portfolio`).
|
||||
* تعیین یک رمز عبور پایگاه داده قوی (Database Password).
|
||||
* انتخاب منطقه جغرافیایی (Region): انتخاب سرورهای فرانکفورت (Central Europe) برای حداقل تاخیر اینترنت و پینگ سریع به کاربران ایرانی.
|
||||
3. **تور تصویری پیشخوان Supabase Studio:**
|
||||
* **Table Editor:** محیط شبیه به اکسل برای دیدن، افزودن و ویرایش دستی داده‌های جداول.
|
||||
* **SQL Editor:** تب اجرای اسکریپت‌ها یا پرامپت‌های هوش مصنوعی برای تولید ساختار جداول.
|
||||
* **Authentication:** پنل لیست کاربران ثبت‌نام‌شده و مدیریت تایید ایمیل.
|
||||
* **Storage:** فضایی شبیه به Google Drive برای آپلود عکس‌های نمونه‌کارها.
|
||||
4. **استخراج کلیدهای اتصال به پروژه (API Credentials):**
|
||||
* رفتن به مسیر Project Settings $\rightarrow$ API.
|
||||
* کپی کردن دو متغیر حیاتی:
|
||||
* `Project URL`: آدرس اختصاصی دیتابیس ابری شما.
|
||||
* `anon / public key`: کلید عمومی برای اتصال امن از فرانت‌اند Next.js.
|
||||
5. **مرزهای امنیتی کلیدها (Security Boundaries):**
|
||||
* چرا استفاده از `anon key` در کدهای فرانت‌اند مجاز است؟ (چون توسط قوانین RLS کنترل می‌شود).
|
||||
* چرا کلید `service_role key` هرگز نباید در کدهای کلاینت یا مخزن گیت‌هاب قرار گیرد؟ (این کلید دسترسی نامحدود به تمام جداول دارد).
|
||||
6. **کال‌اوت‌های Quera:**
|
||||
* `<details class="violet">`: مزیت آزادی و عدم قفل‌شدگی؛ پایگاه داده Supabase یک PostgreSQL خالص است که در هر زمان می‌توانید کل اطلاعات آن را خروجی گرفته و به سرور شخصی خود منتقل کنید.
|
||||
* `<details class="red">`: هشدار امنیتی افشای Service Role Key؛ کلید اصلی ریشه پروژه را هرگز به اشتراک نگذارید!
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- نوشتن اسکریپت‌های ایجاد جداول (درس بعدی ۷.۵).
|
||||
- نصب پکیج و کدهای اتصالی در ری‌اکت (درس ۷.۶).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Supabase | سوپابیس | پلتفرم ابری ارائه‌دهنده دیتابیس PostgreSQL، احراز هویت و APIهای خودکار |
|
||||
| Supabase Studio | پیشخوان استودیو | رابط کاربری گرافیکی تحت وب برای مدیریت آسان جداول، کاربران و دیتابیس |
|
||||
| Project URL | نشانی اختصاصی پروژه | آدرس یکتای اینترنتی سرورهای دیتابیس شما در بستر ابری Supabase |
|
||||
| Anon Public Key | کلید عمومی امن کلاینت | رمزارز اعتباری برای اتصال فرانت‌اند که اختیارات آن توسط قوانین امنیتی RLS محدود شده است |
|
||||
| Service Role Key | کلید اصلی سطح سرور | کلید فوق‌محرمانه با دسترسی نامحدود ادمین به تمام جداول بدون رعایت محدودیت‌های امنیتی |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** کاور مدرن با تم تیره و لوگوی سبز درخشان Supabase که جعبه‌ابزار ابری دیتابیس، احراز هویت و فضای ذخیره‌سازی را در فضا نمایش می‌دهد.
|
||||
2. **ارکان چهارگانه اکوسیستم Supabase:** `images/supabase-core-features.png`
|
||||
* **موضوع:** اینفوگرافیک ۴ ستونه: ۱. دیتابیس Postgres $\rightarrow$ ۲. سیستم Auth $\rightarrow$ ۳. فضای Storage $\rightarrow$ ۴. ای‌پی‌آی خودکار (Auto APIs).
|
||||
3. **پنجره ساخت پروژه جدید در Supabase:** `images/supabase-new-project-dialog.png`
|
||||
* **موضوع:** اسکرین‌شات تمیز از فرم ساخت پروژه با نام، رمز عبور دیتابیس و ریجن فرانکفورت.
|
||||
4. **تور پیشخوان استودیو سوپابیس:** `images/supabase-studio-interface-tour.png`
|
||||
* **موضوع:** اسکرین‌شات برچسب‌گذاری‌شده از داشبورد شامل سایدبار ابزارها: Table Editor، SQL Editor، Authentication و Storage.
|
||||
5. **صفحه کلیدهای API و هشدار امنیتی:** `images/supabase-api-keys-page.png`
|
||||
* **موضوع:** اسکرین‌شات از منوی API Settings با نشان دادن کادر سبز Anon Key و کادر هشدار قرمز Service Role Key.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# آشنایی با Supabase و راه‌اندازی پروژه: پایگاه داده مدرن در دستان شما`
|
||||
2. **مقدمه:** چرا Supabase محبوب‌ترین ابزار بک‌اند در میان استارتاپ‌های نوین هوش مصنوعی است؟
|
||||
3. **جدول کاور درس**
|
||||
4. **چرا Supabase برنده بلامنازع است؟:**
|
||||
* مقایسه با روش‌های سنتی خرید هاست و سرورهای سنگین.
|
||||
* قدرت واقعی هسته PostgreSQL.
|
||||
5. **ساخت اولین پروژه ابری به صورت گام‌به‌گام:**
|
||||
* ثبت‌نام با GitHub.
|
||||
* انتخاب نام و رمز عبور قوی.
|
||||
* انتخاب ریجن فرانکفورت برای پینگ عالی به ایران.
|
||||
6. **تور دیداری در استودیو Supabase:** معرفی ابزارهای روزمره (ادیتور جدول، ادیتور اس‌کیو‌ال، احراز هویت).
|
||||
7. **باکس نکته Quera (`<details class="violet">`):** فرار از انحصار؛ داده‌های شما همیشه در قالب دیتابیس استاندارد متعلق به خودتان است.
|
||||
8. **دریافت کلیدهای اتصال پروژه (Project URL & Anon Key):** نحوه کپی کردن مقادیر برای کدهای فرانت‌اند.
|
||||
9. **مرزهای امنیتی: فرق کلید عمومی و کلید اختصاصی ادمین:**
|
||||
* چرا کلید anon امن است؟
|
||||
* خطرات نابودکننده افشای service role key.
|
||||
10. **باکس هشدار Quera (`<details class="red">`):** هرگز کلید service role را در کدهای فرانت‌اند یا گیت‌هاب قرار ندهید!
|
||||
11. **جمع‌بندی درس‌نامه:** آماده شدن زیرساخت ابری و ورود به درس طراحی و ساخت جداول دیتابیس.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] ویژگی‌های پلتفرم Supabase و تفاوت آن با سرویس‌های بسته به روشنی بیان شده باشد.
|
||||
- [ ] مراحل ساخت پروژه با انتخاب ریجن بهینه در متن آموزش داده شود.
|
||||
- [ ] بخش‌های مختلف داشبورد Supabase Studio با اسکرین‌شات‌های برچسب‌دار شرح داده شوند.
|
||||
- [ ] تمایز حیاتی Anon Key و Service Role Key از منظر امنیت به صراحت تاکید گردد.
|
||||
@@ -0,0 +1,106 @@
|
||||
# مشخصات درس‌نامه: ساخت جداول و کار با داده‌ها در Supabase (Database Schema Design & Tables)
|
||||
- **شناسه در سیلابس:** `L7.5`
|
||||
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L7.4` (آشنایی با Supabase و راه‌اندازی پروژه)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** دو روش ساخت جداول در Supabase (روش بصری Table Editor و روش حرفه‌ای اسکریپت SQL) چگونه کار می‌کنند و چرا روش اسکریپت SQL برای وایب کدینگ دقیق‌تر و سریع‌تر است.
|
||||
- [ ] **به‌کار ببندد (Apply):** اسکیمای کامل دو جدول اختصاصی پروژه محوری شامل جدول پروژه‌ها (`projects`) و جدول تنظیمات و سئو (`site_settings`) را با انواع داده دقیق طراحی کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** اسکریپت استاندارد SQL را در تب SQL Editor سوپابیس اجرا کرده و جداول را در چند ثانیه بسازد.
|
||||
- [ ] **به‌کار ببندد (Apply):** داده‌های نمونه فصل ۶ (Mock Data) را در قالب کوئری درج (`INSERT`) وارد پایگاه داده ابری کند تا جداول از وضعیت خالی خارج شوند.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** الگوی معماری «جدول تک‌سطری (Single-Row Table Pattern)» را برای مدیریت تنظیمات و متادیتای سئو تحلیل و پیاده‌سازی نماید.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **دو مسیر ساخت جدول در Supabase:**
|
||||
* **مسیر بصری (Table Editor):** کلیک روی New Table و افزودن ستون‌ها با ماوس (خوب برای بررسی اولیه).
|
||||
* **مسیر مهندسی (SQL Editor):** کپی کردن اسکریپت تمیز SQL و زدن دکمه Run (روش ایده‌آل برای همکاری با ایجنت‌های هوش مصنوعی بدون خطر خطای دستی).
|
||||
2. **طراحی اسکیمای جدول پروژه‌ها (`projects`):**
|
||||
* `id`: نوع `uuid` با مقدار پیش‌فرض `gen_random_uuid()` به عنوان کلید اصلی.
|
||||
* `created_at`: نوع `timestamptz` با مقدار پیش‌فرض `now()`.
|
||||
* `title`: نوع `text` اجباری (NOT NULL).
|
||||
* `description`: نوع `text` برای توضیحات کوتاه کارت.
|
||||
* `long_description`: نوع `text` برای متن کامل در مودال جزئیات.
|
||||
* `image_url`: نوع `text` آدرس عکس کاور.
|
||||
* `tags`: نوع `text[]` (آرایه متنی) با مقدار پیش‌فرض `'{}'`.
|
||||
* `live_url`: نوع `text` آدرس دموی اینترنتی.
|
||||
* `github_url`: نوع `text` آدرس گیت‌هاب.
|
||||
* `featured`: نوع `boolean` با مقدار پیش‌فرض `false`.
|
||||
3. **طراحی اسکیمای جدول تنظیمات سئو و مشخصات سایت (`site_settings`):**
|
||||
* الگوی جدول تک‌سطری: فقط یک رکورد با `id = 1` وجود دارد که اطلاعات کل پورتفولیو را نگهداری می‌کند.
|
||||
* ستون‌های `site_title`, `meta_description`, `og_image_url`, `author_name`, `bio`, `contact_email`.
|
||||
4. **اسکریپت آماده و کامل SQL (Copy-Paste Migration Script):**
|
||||
* ارائه قطعه کد کامل ساخت جداول به همراه مقادیر اولیه (Seed Data) از پروژه‌های تستی فصل ۶.
|
||||
5. **مشاهده زنده رکوردهای ثبت‌شده در Table Editor:**
|
||||
* باز کردن ادیتور بصری و دیدن ۶ ردیف پروژه همراه با تصاویر و تگ‌ها در بستر ابری سوپابیس.
|
||||
* تست ویرایش درون‌خطی (Inline Edit) یک عنوان به عنوان تمرین عملی.
|
||||
6. **کال‌اوت‌های Quera:**
|
||||
* `<details class="violet">`: الگوی جدول تک‌سطری (Single-Row Pattern)؛ ساده‌ترین و مطمئن‌ترین ترفند برای نگهداری متادیتای سئو و اطلاعات عمومی سایت.
|
||||
* `<details class="red">`: تله مقادیر پیش‌فرض فراموش‌شده؛ چرا ستون‌های تاریخ و آرایه همیشه باید مقدار دیفالت داشته باشند تا با خطای `null` مواجه نشویم.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- پیکربندی روابط پیچیده چندبه‌چند (Many-to-Many) یا جوین‌های سنگین دیتابیس.
|
||||
- اتصال مستقیم کد فرانت‌اند به این جداول (درس بعدی ۷.۶).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| SQL Editor | ویرایشگر فرامین اس‌کیو‌ال | محیط اجرای مستقیم دستورات متنی پایگاه داده برای ساخت و مدیریت ساختار جداول |
|
||||
| Single-Row Pattern | الگوی جدول تک‌سطری | ساختار جدولی که فقط یک رکورد ثابت دارد و برای ذخیره تنظیمات سراسری سیستم استفاده می‌شود |
|
||||
| Default Value | مقدار پیش‌فرض | مقداری که در صورت عدم ارسال دیتا توسط کاربر، به صورت خودکار در ستون ثبت می‌شود |
|
||||
| Seed Data | داده‌های اولیه / بذری | اطلاعات نمونه و آماده‌ای که در بدو راه‌اندازی برای تست اولیه به دیتابیس تزریق می‌شوند |
|
||||
| Text Array (text[]) | آرایه متنی در پستگرس | قابلیت ذخیره چندین برچسب یا کلمه در قالب یک لیست درون یک ستون واحد دیتابیس |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** کاور مدرن با تم تیره که جداول شفاف و نورانی دیتابیس را با ستون‌های مرتب و کدهای SQL اجرا شده در پس‌زمینه نمایش می‌دهد.
|
||||
2. **نقشه دیاگرام دو جدول پورتفولیو:** `images/portfolio-database-schema-diagram.png`
|
||||
* **موضوع:** اینفوگرافیک مقایسه‌ای دو جدول: جدول چندسطری `projects` (برای نمونه‌کارها) در کنار جدول تک‌سطری `site_settings` (برای متادیتای سئو).
|
||||
3. **اجرای اسکریپت در SQL Editor سوپابیس:** `images/supabase-sql-editor-run.png`
|
||||
* **موضوع:** اسکرین‌شات تمیز از محیط کدنویسی SQL در Supabase با دکمه سبز Run و پیام موفقیت‌آمیز `Success. No rows returned`.
|
||||
4. **نمای رکوردهای ماک در Table Editor:** `images/supabase-table-editor-projects.png`
|
||||
* **موضوع:** اسکرین‌شات از جدول واقعی `projects` در سوپابیس که ردیف‌های شیک پروژه‌ها با تگ‌ها و تصاویر را نشان می‌دهد.
|
||||
5. **الگوی جدول تک‌سطری سئو در عمل:** `images/single-row-settings-demo.png`
|
||||
* **موضوع:** نمایش تصویری جدول `site_settings` با ردیف واحد و فیلدهای تایتل، دیسکریپشن و آدرس عکس اوپن‌گراف.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# ساخت جداول و کار با داده‌ها در Supabase: پیاده‌سازی اسکلت اطلاعات`
|
||||
2. **مقدمه:** چرا نوشتن اسکریپت SQL با هوش مصنوعی بسیار مطمئن‌تر از کلیک‌های دستی در منوهاست؟
|
||||
3. **جدول کاور درس**
|
||||
4. **انتخاب استراتژی: ویرایشگر بصری یا اسکریپت سریع SQL؟:** مقایسه دو رویکرد.
|
||||
5. **کالبدشکافی اسکیمای جدول پروژه‌ها (`projects`):** فیلدهای شناسه، عنوان، تگ‌ها و لینک‌ها.
|
||||
6. **معماری جدول تنظیمات سئو (`site_settings`):**
|
||||
* چرا الگوی جدول تک‌سطری بهترین راهکار مدیریت متادیتا است؟
|
||||
7. **باکس نکته Quera (`<details class="violet">`):** راز سادگی و پایداری الگوی Single-Row در مدیریت تنظیمات سایت.
|
||||
8. **اجرای اسکریپت کامل ساخت جداول و تزریق داده‌های اولیه (Seed Data):**
|
||||
* کد کامل و آماده برای کپی در SQL Editor.
|
||||
* اجرای کوئری با یک کلیک.
|
||||
9. **بازرسی رکوردهای زنده در Table Editor:** مشاهده داده‌ها و تست ویرایش یک ستون.
|
||||
10. **باکس هشدار Quera (`<details class="red">`):** اهمیت تعریف مقادیر پیش‌فرض برای پیشگیری از باگ‌های Null در آینده.
|
||||
11. **جمع‌بندی درس‌نامه:** تولد جداول واقعی در پایگاه داده ابری و آماده شدن برای متصل کردن فرانت‌اند Next.js به این داده‌ها در درس بعد.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] ساختار جداول `projects` و `site_settings` به همراه انواع داده و قیود به دقت مستند شده باشد.
|
||||
- [ ] اسکریپت کامل و قابل اجرای SQL در متن درس‌نامه قرار گیرد.
|
||||
- [ ] الگوی جدول تک‌سطری برای تنظیمات سئو با استدلال فنی تشریح شود.
|
||||
- [ ] تزریق داده‌های نمونه اولیه (Seed Data) در ادامه اسکریپت گنجانده شده باشد.
|
||||
@@ -0,0 +1,128 @@
|
||||
# مشخصات درس‌نامه: اتصال پروژه به دیتابیس (Connecting the App to Supabase)
|
||||
- **شناسه در سیلابس:** `L7.6`
|
||||
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L7.5` (ساخت جداول و کار با داده‌ها در Supabase)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **به‌کار ببندد (Apply):** کتابخانه رسمی کلاینت سوپابیس (`@supabase/supabase-js`) را با استفاده از دستورات چندسکویی در پروژه Next.js خود نصب کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** متغیرهای محیطی محرمانه (`NEXT_PUBLIC_SUPABASE_URL` و `NEXT_PUBLIC_SUPABASE_ANON_KEY`) را در فایل `.env.local` تنظیم و ذخیره کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** ماژول یکتا و متمرکز اتصال به پایگاه داده (`src/lib/supabase.ts`) را برای تعامل امن با جداول بسازد.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** کدهای دریافت داده در کامپوننت‌های سرور Next.js را با داده‌های ماک قبلی جایگزین کند؛ داده‌های زنده را با دستور `.from('projects').select('*')` فراخوانی کرده و خطایابی کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** نخستین عملیات ایجاد پروژه جدید (Insert) را از طریق فرم ارسال کرده و افزوده شدن آنی آن به جدول دیتابیس ابری را راستی‌آزمایی کند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **لحظه تاریخی خداحافظی با داده‌های ماک:**
|
||||
* از این درس به بعد، پروتوتایپ ما به یک محصول تمام‌عیار متصل به دیتابیس ابری تبدیل می‌شود که هر تغییری در آن برای همیشه روی سرورهای جهانی ذخیره خواهد ماند.
|
||||
2. **نصب کتابخانه رسمی Supabase با منوهای کشویی سیستم‌عامل‌ها:**
|
||||
* دستور نصب پکیج:
|
||||
```bash
|
||||
npm install @supabase/supabase-js
|
||||
```
|
||||
* منوی کشویی ویندوز (Windows).
|
||||
* منوی کشویی مک‌اواس (macOS).
|
||||
* منوی کشویی لینوکس (Linux).
|
||||
3. **پیکربندی متغیرهای محیطی در `.env.local`:**
|
||||
* ساخت فایل محرمانه `.env.local` در ریشه پروژه.
|
||||
* درج کلیدها:
|
||||
```env
|
||||
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
* فلسفه پیشوند `NEXT_PUBLIC_`: چرا Next.js برای کلیدهایی که مرورگر کاربر باید بتواند آن‌ها را بخواند این پیشوند را الزامی کرده است؟
|
||||
* اطمینان از وجود این فایل در `.gitignore`.
|
||||
4. **ساخت کلاینت ارتباطی متمرکز (`src/lib/supabase.ts`):**
|
||||
* ساخت فایل و فراخوانی تابع `createClient`:
|
||||
```typescript
|
||||
import { createClient } from '@supabase/supabase-js';
|
||||
|
||||
const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
|
||||
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;
|
||||
|
||||
export const supabase = createClient(supabaseUrl, supabaseAnonKey);
|
||||
```
|
||||
5. **خواندن داده‌های زنده در صفحه اصلی (Reading Projects):**
|
||||
* در فایل `src/app/page.tsx` (به صورت Server Component فوق‌العاده سریع):
|
||||
```typescript
|
||||
const { data: projects, error } = await supabase
|
||||
.from('projects')
|
||||
.select('*')
|
||||
.order('created_at', { ascending: false });
|
||||
```
|
||||
* پاس دادن داده‌های زنده به کامپوننت `ProjectsGrid` و رندر شدن فوری.
|
||||
6. **ارسال اولین دیتای جدید (Creating a Project):**
|
||||
* پیاده‌سازی متد `insert` در فرم ادمین و تایید ایجاد رکورد.
|
||||
7. **کال‌اوت‌های Quera:**
|
||||
* `<details class="violet">`: چرا خواندن داده در Server Component بدون نیاز به `useEffect` یا لودینگ‌های خسته‌کننده کلاینتی، اوج قدرت Next.js است؟
|
||||
* `<details class="red">`: خطای نخواندن متغیرهای جدید؛ الزام ریستارت کردن سرور (`Ctrl+C` و اجرای مجدد `npm run dev`) بعد از ساخت فایل `.env.local`.
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- احراز هویت کاربری و محدودیت دسترسی به پنل ادمین (درس بعدی ۷.۷).
|
||||
- تعریف قوانین امنیتی سطح ردیف RLS (درس ۷.۸).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Supabase Client | کلاینت سوپابیس | ابزار نرم‌افزاری که دستورات جاوااسکریپت شما را به کوئری‌های امن دیتابیس ترجمه می‌کند |
|
||||
| .env.local | فایل متغیرهای محیطی محلی | فایل ویژه Next.js برای نگهداری آدرس‌ها و کلیدهای محرمانه دور از کدهای سورس |
|
||||
| NEXT_PUBLIC_ Prefix | پیشوند پابلیک نکست | نشانهای که به Next.js اعلام می‌کند مقدار این متغیر می‌تواند به کدهای کلاینت مرورگر فرستاده شود |
|
||||
| Async Data Fetching | دریافت ناهمگام داده | خواندن مستقیم اطلاعات از پایگاه داده در سمت سرور پیش از تولید HTML نهایی صفحه |
|
||||
| Database Mutation | تغییر / جهش داده‌ها | هرگونه عملیات تغییردهنده وضعیت دیتابیس نظیر اضافه کردن، ویرایش یا حذف رکورد |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** کاور مدرن با تم تیره که کابل‌های نوری سبز رنگ کلاینت سوپابیس را در حال اتصال فایل‌های فرانت‌اند Next.js به دیتابیس ابری نمایش می‌دهد.
|
||||
2. **دیاگرام معماری اتصال فرانت‌اند به دیتابیس ابری:** `images/frontend-to-supabase-pipeline.png`
|
||||
* **موضوع:** اینفوگرافیک اتصال: کلیدهای `.env.local` $\rightarrow$ ماژول `lib/supabase.ts` $\rightarrow$ کامپوننت سرور `page.tsx` $\rightarrow$ کوئری به دیتابیس ابری.
|
||||
3. **نمونه فایل `.env.local` تنظیم‌شده در ادیتور:** `images/env-local-editor-demo.png`
|
||||
* **موضوع:** اسکرین‌شات تمیز از فایل تنظیمات محیطی با نشانی پروژه و کلید عمومی anon.
|
||||
4. **رندر شدن داده‌های واقعی دیتابیس در مرورگر:** `images/live-database-rendered.png`
|
||||
* **موضوع:** اسکرین‌شات از صفحه اصلی پورتفولیو روی `localhost:3000` که داده‌های زنده خوانده‌شده از Supabase را بدون ماک‌دیتا نمایش می‌دهد.
|
||||
5. **همگام‌سازی لحظه‌ای؛ ثبت در فرم و نمایش در جدول دیتابیس:** `images/live-sync-verification.png`
|
||||
* **موضوع:** تصویر دونیمه‌ای: سمت چپ زدن دکمه ذخیره در فرم فرانت‌اند و سمت راست ظاهر شدن بلافاصله رکورد در Table Editor سوپابیس.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# اتصال پروژه به دیتابیس: پایان دوران داده‌های مصنوعی و آغاز حیات واقعی`
|
||||
2. **مقدمه:** لحظه هیجان‌انگیز اتصال سیم‌های داده به قلب تپنده پورتفولیو.
|
||||
3. **جدول کاور درس**
|
||||
4. **نصب کتابخانه رسمی `@supabase/supabase-js`:**
|
||||
* دستورات منوی کشویی ویندوز (Windows).
|
||||
* دستورات منوی کشویی مک‌اواس (macOS).
|
||||
* دستورات منوی کشویی لینوکس (Linux).
|
||||
5. **پیکربندی کلیدهای اتصال در فایل محرمانه `.env.local`:**
|
||||
* ثبت آدرس پروژه و کلید عمومی `anon`.
|
||||
* چرا پیشوند `NEXT_PUBLIC_` اهمیت دارد؟
|
||||
6. **ساخت ماژول مرکزی کلاینت (`src/lib/supabase.ts`):** یک خط کد برای تمام تعاملات پروژه.
|
||||
7. **خواندن مستقیم داده‌ها در Server Component:**
|
||||
* جایگزینی Mock Data با کوئری `.from('projects').select('*')`.
|
||||
* مرتب‌سازی بر اساس جدیدترین زمان ایجاد (`order by created_at`).
|
||||
8. **باکس نکته Quera (`<details class="violet">`):** سرعت خیره‌کننده خواندن داده‌ها در کامپوننت‌های سرور Next.js.
|
||||
9. **تست عملی ارسال داده جدید به دیتابیس ابری:** ثبت اولین پروژه از طریق فرم فرانت‌اند.
|
||||
10. **باکس هشدار Quera (`<details class="red">`):** الزام ریستارت سرور توسعه پس از ویرایش فایل‌های `.env`.
|
||||
11. **جمع‌بندی درس‌نامه:** زنده شدن پورتفولیو با داده‌های ابری و ورود به درس حیاتی احراز هویت ادمین.
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] فرایند نصب پکیج و تنظیم `.env.local` با رعایت منوهای کشویی سیستم‌عامل‌ها آموزش داده شود.
|
||||
- [ ] ماژول کلاینت `src/lib/supabase.ts` به همراه کدهای استاندارد در متن قرار گیرد.
|
||||
- [ ] کوئری دریافت داده در کامپوننت‌های سرور به طور شفاف مستند گردد.
|
||||
- [ ] نحوه تست و راستی‌آزمایی افزوده شدن اطلاعات به دیتابیس زنده نشان داده شود.
|
||||
@@ -0,0 +1,116 @@
|
||||
# مشخصات درس‌نامه: احراز هویت (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` با مکانیزم ریدایرکت امن تشریح شود.
|
||||
@@ -0,0 +1,119 @@
|
||||
# مشخصات درس‌نامه: امنیت پایگاه داده با Row Level Security (RLS)
|
||||
- **شناسه در سیلابس:** `L7.8`
|
||||
- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
|
||||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
|
||||
- **پیش‌نیازهای مستقیم:** `L7.7` (احراز هویت)
|
||||
|
||||
---
|
||||
|
||||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||
- [ ] **درک کند (Understand):** سازوکار امنیت در سطح ردیف (Row Level Security - RLS) در پایگاه داده PostgreSQL چیست و چرا به عنوان دیوار آتشین و غیرقابل نفوذ دیتابیس عمل می‌کند.
|
||||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطر هولناک غیرفعال بودن RLS را تحلیل کند و بداند چرا بدون RLS، هر فرد متفرقه‌ای با داشتن کلید عمومی `anon key` می‌تواند کل داده‌های پروژه را با یک درخواست ساده پاک کند.
|
||||
- [ ] **به‌کار ببندد (Apply):** قابلیت RLS را روی جداول پروژه محوری (`projects` و `site_settings`) در پیشخوان Supabase یا با دستورات SQL فعال سازد.
|
||||
- [ ] **به‌کار ببندد (Apply):** دو سیاست امنیتی استاندارد را پیاده‌سازی کند: **سیاست خواندن عمومی برای همه کاربران (Public Read via SELECT)** و **سیاست نگارش، ویرایش و حذف منحصراً برای ادمین لاگین‌شده (`auth.role() = 'authenticated'`)**.
|
||||
- [ ] **به‌کار ببندد (Apply):** عملکرد قوانین امنیتی را با باز کردن سایت در تب ناشناس (Incognito) و تلاش برای ویرایش غیرمجاز تست و راستی‌آزمایی کند.
|
||||
|
||||
---
|
||||
|
||||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||
|
||||
### آنچه باید پوشش داده شود (In-Scope):
|
||||
1. **کابوس بزرگ وب بدون RLS:**
|
||||
* از آنجا که کلید عمومی `anon key` در کدهای فرانت‌اند مرورگر قرار دارد، اگر RLS فعال نباشد، هر هکر یا کاربری می‌تواند با ابزارهایی مثل Postman یا دستور `curl`، یک درخواست `DELETE` به سرور بفرستد و در یک ثانیه تمام کارهای پورتفولیو را پاک کند!
|
||||
* دیوار آتشین RLS کاری می‌کند که خود موتور دیتابیس PostgreSQL پیش از اجرای هر عملیاتی بپرسد: «آیا این کاربر اجازه این کار را دارد؟»
|
||||
2. **سازوکار امنیت در سطح ردیف (Row Level Security چیست؟):**
|
||||
* قوانینی که مستقیماً در لایه عمیق پایگاه داده (نه در فرانت‌اند) تعریف و اعمال می‌شوند.
|
||||
* حتی اگر کسی کدهای فرانت‌اند شما را دور بزند، دیتابیس بدون مجوز اجازه عبور نخواهد داد.
|
||||
3. **تعریف سیاست‌های امنیتی (Security Policies) برای پروژه پورتفولیو:**
|
||||
* **سیاست‌های جدول پروژه‌ها (`projects`):**
|
||||
* **قانون ۱ (خواندن برای عموم آزاد):** همه افراد در جهان باید بتوانند نمونه‌کارها را ببینند:
|
||||
```sql
|
||||
CREATE POLICY "Public projects are viewable by everyone"
|
||||
ON projects FOR SELECT
|
||||
USING (true);
|
||||
```
|
||||
* **قانون ۲ (فقط ادمین لاگین‌شده حق ویرایش دارد):** فقط کاربری که با موفقیت در Supabase Auth لاگین کرده اجازه ثبت، ویرایش و حذف دارد:
|
||||
```sql
|
||||
CREATE POLICY "Only authenticated admin can insert, update, delete"
|
||||
ON projects FOR ALL
|
||||
TO authenticated
|
||||
USING (true);
|
||||
```
|
||||
* **سیاست‌های جدول تنظیمات سئو (`site_settings`):**
|
||||
* خواندن تنظیمات برای عموم آزاد (`FOR SELECT USING (true)`).
|
||||
* ویرایش تنظیمات فقط توسط ادمین تاییدشده (`FOR UPDATE TO authenticated`).
|
||||
4. **اسکریپت کامل فعال‌سازی RLS با SQL:**
|
||||
* دستورات صریح فعال‌سازی:
|
||||
```sql
|
||||
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
|
||||
ALTER TABLE site_settings ENABLE ROW LEVEL SECURITY;
|
||||
```
|
||||
5. **تست و سنجش امنیت در عمل:**
|
||||
* باز کردن صفحه اصلی در تب ناشناس مرورگر: همه پروژه‌ها به درستی نمایش داده می‌شوند (تست موفق قانون SELECT).
|
||||
* تلاش برای ارسال درخواست ایجاد یا حذف بدون ورود: دریافت خطای قاطع `403 Forbidden / Row Level Security Violation`.
|
||||
6. **کال‌اوت‌های Quera:**
|
||||
* `<details class="violet">`: چرا امنیت در سطح پایگاه داده (Database-Level Security) هزاران بار نفوذناپذیرتر از چک‌های ظاهری در کدهای جاوااسکریپت است؟
|
||||
* `<details class="red">`: پرچم قرمز مرگبار؛ هرگز پروژه‌ای را در وضعیت «RLS Disabled» روی اینترنت رها نکنید؛ این کار معادل رها کردن گاوصندوق باز در خیابان است!
|
||||
|
||||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||
- تعریف رول‌های پیچیده چندسطحی سازمانی (RBAC با چندین سطح دسترسی نظیر سوپرادمین، نویسنده، ویرایشگر).
|
||||
- تنظیمات فایروال شبکه یا DDoS Protection سرور (فصل ۱۱ امنیت و انتشار).
|
||||
|
||||
---
|
||||
|
||||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||
|
||||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||
| :--- | :--- | :--- |
|
||||
| Row Level Security (RLS) | امنیت در سطح ردیف | مکانیزم امنیتی در دیتابیس که دسترسی به تک‌تک سطرهای جدول را بر اساس هویت کاربر فیلتر می‌کند |
|
||||
| Security Policy | خط‌مشی / سیاست امنیتی | قانون صریحی در دیتابیس که تعیین می‌کند چه کسی حق اجرای SELECT، INSERT، UPDATE یا DELETE را دارد |
|
||||
| Authenticated Role | نقش کاربری احراز هویت‌شده | برچسب امنیتی در دیتابیس برای کاربرانی که لاگین موفق با نشست فعال داشته‌اند |
|
||||
| Database Firewall | دیوار آتشین پایگاه داده | سپر دفاعی مستقر در هسته دیتابیس برای رد خودکار درخواست‌های غیرمجاز |
|
||||
| 403 Forbidden | خطای دسترسی غیرمجاز | کد وضعیت وب برای پاسخ به کاربرانی که بدون داشتن مجوز لازم قصد دستکاری منابع را دارند |
|
||||
|
||||
---
|
||||
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
|
||||
|
||||
1. **تصویر کاور درس:** `images/cover.png`
|
||||
* **موضوع:** کاور مدرن با تم تیره و یک سپر دیجیتال نئونی که دور استوانه دیتابیس PostgreSQL تنیده شده و امواج غیرمجاز را دفع می‌کند.
|
||||
2. **استعاره نگهبان امنیتی RLS جلوی در دیتابیس:** `images/rls-bouncer-analogy.png`
|
||||
* **موضوع:** تصویر استعاری: نگهبان امنیتی جلوی جدول (درخواست‌های بدون لاگین را به سمت در خروج هدایت می‌کند و به ادمین احراز هویت‌شده اجازه ورود می‌دهد).
|
||||
3. **مقایسه دیتابیس با و بدون RLS:** `images/unprotected-vs-rls-protected.png`
|
||||
* **موضوع:** اینفوگرافیک مقایسه‌ای: سمت چپ دیتابیس بدون RLS (خطر پاک شدن کل اطلاعات توسط هر فرد) در برابر سمت راست دیتابیس قفل‌شده با RLS.
|
||||
4. **نشانگر سبز RLS در پنل Table Editor سوپابیس:** `images/supabase-rls-green-badge.png`
|
||||
* **موضوع:** اسکرین‌شات تمیز از هدر جدول در Supabase با نشان دادن برچسب سبز `RLS Enabled` و لیست سیاست‌های فعال.
|
||||
5. **اسکریپت SQL سیاست‌های امنیتی پورتفولیو:** `images/sql-policies-code-block.png`
|
||||
* **موضوع:** تصویر کادر کدهای SQL سیاست‌های خواندن عمومی و نگارش اختصاصی ادمین با هایلایت سینتکس تمیز.
|
||||
|
||||
---
|
||||
|
||||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||
|
||||
1. **تیتر اصلی:** `# امنیت پایگاه داده با Row Level Security: ساخت دژ تسخیرناپذیر`
|
||||
2. **مقدمه:** چرا بدون RLS، انتشار یک اپلیکیشن متصل به دیتابیس معادل خودکشی سایبری است؟
|
||||
3. **جدول کاور درس**
|
||||
4. **کابوس بزرگ: افشای کلید عمومی بدون سپر امنیتی:** ریشه نیاز مبرم به RLS.
|
||||
5. **سازوکار Row Level Security (RLS) در PostgreSQL:** امنیت در عمق دیتابیس، نه در جاوااسکریپت کلاینت.
|
||||
6. **سیاست‌های امنیتی پروژه پورتفولیوی پویا:**
|
||||
* قانون خواندن عمومی کارهای پورتفولیو برای همه (SELECT Policy).
|
||||
* قانون انحصار ویرایش و حذف فقط برای ادمین تاییدشده (Authenticated Policy).
|
||||
* سیاست‌های جدول تک‌سطری سئو.
|
||||
7. **باکس نکته پیشرفته Quera (`<details class="violet">`):** چرا چک‌های امنیتی فرانت‌اند هرگز کافی نیستند؟
|
||||
8. **اجرای اسکریپت فعال‌سازی و قفل‌گذاری RLS در SQL Editor:** کپی و اجرای کوئری در چند ثانیه.
|
||||
9. **آزمون نفوذپذیری و تست زنده امنیت:**
|
||||
* راستی‌آزمایی در تب ناشناس مرورگر.
|
||||
* اثبات مسدود شدن درخواست‌های غیرمجاز با خطای ۴۰۳.
|
||||
10. **باکس هشدار قرمز Quera (`<details class="red">`):** هرگز پروژه‌ای را با RLS خاموش به پروداکشن نبرید!
|
||||
11. **جشن پایان فصل هفتم:** اعلام آماده‌سازی ۱۰۰٪ فرانت‌اند، دیتابیس، احراز هویت و امنیت برای ورود به پروژه عملی اول (فصل ۸).
|
||||
|
||||
---
|
||||
|
||||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||
- [ ] مفهوم RLS و خطرات غیرفعال بودن آن به زبانی رسا و هشداردهنده تبیین شده باشد.
|
||||
- [ ] سیاست‌های امنیتی برای دو جدول `projects` و `site_settings` با کدهای کامل SQL ارائه گردند.
|
||||
- [ ] تمایز دسترسی عمومی خواندن با دسترسی اختصاصی نگارش ادمین شفاف شده باشد.
|
||||
- [ ] آزمون عملی تست سیاست‌ها با تب ناشناس مرورگر در متن گنجانده شود.
|
||||
Reference in New Issue
Block a user