diff --git a/chapters/07-database-and-backend/00-lesson-chapter-goals/spec.md b/chapters/07-database-and-backend/00-lesson-chapter-goals/spec.md new file mode 100644 index 0000000..665aaed --- /dev/null +++ b/chapters/07-database-and-backend/00-lesson-chapter-goals/spec.md @@ -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. **کال‌اوت نکته کوئرا (`
`):** اهمیت حفظ خونسردی در برابر اصطلاحات بک‌اند؛ تمام مفاهیم با استعاره‌های ساده و ملموس تدریس خواهند شد. + +### آنچه نباید وارد آن شویم (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 (`
`):** ثبت دکمه «خواندم» و آغاز سفر به دنیای شگفت‌انگیز داده‌ها. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] اهداف فصل و ضرورت یادگیری بک‌اند برای تبدیل پروتوتایپ به محصول واقعی تبیین شده باشد. +- [ ] نقشه راه ۸ درس‌نامه بعدی به همراه معرفی Supabase و امنیت RLS پوشش داده شود. +- [ ] پیوند این فصل با پروژه عملی اول در فصل ۸ به وضوح تشریح گردد. diff --git a/chapters/07-database-and-backend/01-lesson-database-fundamentals/spec.md b/chapters/07-database-and-backend/01-lesson-database-fundamentals/spec.md new file mode 100644 index 0000000..7488200 --- /dev/null +++ b/chapters/07-database-and-backend/01-lesson-database-fundamentals/spec.md @@ -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:** + * `
`: چرا شناسه‌های تصادفی و طولانی (UUID) در وب مدرن بر شناسه‌های عددی ساده (`1, 2, 3`) ارجحیت دارند؟ + * `
`: تله انتخاب نوع داده اشتباه؛ ذخیره کردن تاریخ یا اعداد در قالب متن خام (`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 (`
`):** چرا در پروژه‌های نوین از شناسه UUID استفاده می‌کنیم؟ +7. **انواع داده‌های پرکاربرد: متن، عدد، تاریخ و بولین:** جلوگیری از خطاهای رایج. +8. **پایگاه‌های داده رابطه‌ای (SQL) در برابر NoSQL:** چرا PostgreSQL انتخاب استاندارد است؟ +9. **طراحی نقشه داده‌های پورتفولیوی پویا:** کالبدشکافی جداول پروژه‌ها و تنظیمات سئو. +10. **باکس هشدار Quera (`
`):** عواقب انتخاب اشتباه نوع داده ستون‌ها. +11. **جمع‌بندی درس‌نامه:** تسلط بر مفاهیم بنیادین داده و ورود به شاهراه ارتباطی فرانت‌اند با بک‌اند (APIها). + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] مفاهیم جدول، سطر، ستون و کلید اصلی با زبان ملموس و روان شرح داده شده باشند. +- [ ] انواع داده‌های اصلی به همراه دلیل نیاز به نوع‌های معین تدریس شوند. +- [ ] ساختار جداول پروژه پورتفولیو (`projects` و `site_settings`) در متن مشخص گردند. +- [ ] تفاوت SQL و NoSQL با تاکید بر جایگاه PostgreSQL تبیین شده باشد. diff --git a/chapters/07-database-and-backend/02-lesson-api-and-http-methods/spec.md b/chapters/07-database-and-backend/02-lesson-api-and-http-methods/spec.md new file mode 100644 index 0000000..c1bbb64 --- /dev/null +++ b/chapters/07-database-and-backend/02-lesson-api-and-http-methods/spec.md @@ -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:** + * `
`: استعاره گارسون رستوران؛ امن‌ترین روش حفظ پایگاه داده از دسترسی مستقیم مرورگرها. + * `
`: کدهای وضعیت 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 (`
`):** چرا Supabase نیاز به نوشتن دستی کدهای API را برای همیشه حذف کرد؟ +9. **رمزگشایی از کدهای وضعیت HTTP (چراغ راهنمای خطاها):** تفاوت خطای ۴۰۱ با ۴۰۴ و ۵۰۰. +10. **باکس هشدار Quera (`
`):** تب Network در ابزار DevTools مرورگر؛ کلید کشف مشکلات ارتباطی فرانت‌اند با سرور. +11. **جمع‌بندی درس‌نامه:** تسلط بر مفاهیم ارتباطی و ورود به درس راه‌اندازی عملی پروژه در پلتفرم ابری Supabase. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] استعاره گارسون برای تفهیم نقش واسطه‌ای و امنیتی API به زبان ساده بیان شده باشد. +- [ ] متدهای چهارگانه HTTP و تطبیق آن‌ها با عملیات CRUD در سناریوی پروژه پورتفولیو توضیح داده شود. +- [ ] کدهای وضعیت اصلی به همراه تحلیل علت رخداد هرکدام آموزش داده شوند. +- [ ] فرمت JSON و ساختار تبادل پیام با کدهای نمونه مستند گردد. diff --git a/chapters/07-database-and-backend/03-lesson-intro-to-supabase/spec.md b/chapters/07-database-and-backend/03-lesson-intro-to-supabase/spec.md new file mode 100644 index 0000000..5dd97d6 --- /dev/null +++ b/chapters/07-database-and-backend/03-lesson-intro-to-supabase/spec.md @@ -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:** + * `
`: مزیت آزادی و عدم قفل‌شدگی؛ پایگاه داده Supabase یک PostgreSQL خالص است که در هر زمان می‌توانید کل اطلاعات آن را خروجی گرفته و به سرور شخصی خود منتقل کنید. + * `
`: هشدار امنیتی افشای 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 (`
`):** فرار از انحصار؛ داده‌های شما همیشه در قالب دیتابیس استاندارد متعلق به خودتان است. +8. **دریافت کلیدهای اتصال پروژه (Project URL & Anon Key):** نحوه کپی کردن مقادیر برای کدهای فرانت‌اند. +9. **مرزهای امنیتی: فرق کلید عمومی و کلید اختصاصی ادمین:** + * چرا کلید anon امن است؟ + * خطرات نابودکننده افشای service role key. +10. **باکس هشدار Quera (`
`):** هرگز کلید service role را در کدهای فرانت‌اند یا گیت‌هاب قرار ندهید! +11. **جمع‌بندی درس‌نامه:** آماده شدن زیرساخت ابری و ورود به درس طراحی و ساخت جداول دیتابیس. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] ویژگی‌های پلتفرم Supabase و تفاوت آن با سرویس‌های بسته به روشنی بیان شده باشد. +- [ ] مراحل ساخت پروژه با انتخاب ریجن بهینه در متن آموزش داده شود. +- [ ] بخش‌های مختلف داشبورد Supabase Studio با اسکرین‌شات‌های برچسب‌دار شرح داده شوند. +- [ ] تمایز حیاتی Anon Key و Service Role Key از منظر امنیت به صراحت تاکید گردد. diff --git a/chapters/07-database-and-backend/04-lesson-tables-and-schema-design/spec.md b/chapters/07-database-and-backend/04-lesson-tables-and-schema-design/spec.md new file mode 100644 index 0000000..a76931e --- /dev/null +++ b/chapters/07-database-and-backend/04-lesson-tables-and-schema-design/spec.md @@ -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:** + * `
`: الگوی جدول تک‌سطری (Single-Row Pattern)؛ ساده‌ترین و مطمئن‌ترین ترفند برای نگهداری متادیتای سئو و اطلاعات عمومی سایت. + * `
`: تله مقادیر پیش‌فرض فراموش‌شده؛ چرا ستون‌های تاریخ و آرایه همیشه باید مقدار دیفالت داشته باشند تا با خطای `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 (`
`):** راز سادگی و پایداری الگوی Single-Row در مدیریت تنظیمات سایت. +8. **اجرای اسکریپت کامل ساخت جداول و تزریق داده‌های اولیه (Seed Data):** + * کد کامل و آماده برای کپی در SQL Editor. + * اجرای کوئری با یک کلیک. +9. **بازرسی رکوردهای زنده در Table Editor:** مشاهده داده‌ها و تست ویرایش یک ستون. +10. **باکس هشدار Quera (`
`):** اهمیت تعریف مقادیر پیش‌فرض برای پیشگیری از باگ‌های Null در آینده. +11. **جمع‌بندی درس‌نامه:** تولد جداول واقعی در پایگاه داده ابری و آماده شدن برای متصل کردن فرانت‌اند Next.js به این داده‌ها در درس بعد. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] ساختار جداول `projects` و `site_settings` به همراه انواع داده و قیود به دقت مستند شده باشد. +- [ ] اسکریپت کامل و قابل اجرای SQL در متن درس‌نامه قرار گیرد. +- [ ] الگوی جدول تک‌سطری برای تنظیمات سئو با استدلال فنی تشریح شود. +- [ ] تزریق داده‌های نمونه اولیه (Seed Data) در ادامه اسکریپت گنجانده شده باشد. diff --git a/chapters/07-database-and-backend/05-lesson-connecting-app-to-database/spec.md b/chapters/07-database-and-backend/05-lesson-connecting-app-to-database/spec.md new file mode 100644 index 0000000..d44f438 --- /dev/null +++ b/chapters/07-database-and-backend/05-lesson-connecting-app-to-database/spec.md @@ -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:** + * `
`: چرا خواندن داده در Server Component بدون نیاز به `useEffect` یا لودینگ‌های خسته‌کننده کلاینتی، اوج قدرت Next.js است؟ + * `
`: خطای نخواندن متغیرهای جدید؛ الزام ریستارت کردن سرور (`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 (`
`):** سرعت خیره‌کننده خواندن داده‌ها در کامپوننت‌های سرور Next.js. +9. **تست عملی ارسال داده جدید به دیتابیس ابری:** ثبت اولین پروژه از طریق فرم فرانت‌اند. +10. **باکس هشدار Quera (`
`):** الزام ریستارت سرور توسعه پس از ویرایش فایل‌های `.env`. +11. **جمع‌بندی درس‌نامه:** زنده شدن پورتفولیو با داده‌های ابری و ورود به درس حیاتی احراز هویت ادمین. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] فرایند نصب پکیج و تنظیم `.env.local` با رعایت منوهای کشویی سیستم‌عامل‌ها آموزش داده شود. +- [ ] ماژول کلاینت `src/lib/supabase.ts` به همراه کدهای استاندارد در متن قرار گیرد. +- [ ] کوئری دریافت داده در کامپوننت‌های سرور به طور شفاف مستند گردد. +- [ ] نحوه تست و راستی‌آزمایی افزوده شدن اطلاعات به دیتابیس زنده نشان داده شود. diff --git a/chapters/07-database-and-backend/06-lesson-authentication/spec.md b/chapters/07-database-and-backend/06-lesson-authentication/spec.md new file mode 100644 index 0000000..a799ce3 --- /dev/null +++ b/chapters/07-database-and-backend/06-lesson-authentication/spec.md @@ -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:** + * `
`: تفاوت بنیادین Authentication و Authorization؛ دو ستون تفکیک‌ناپذیر امنیت نرم‌افزار. + * `
`: غیرفعال کردن ثبت‌نام عمومی؛ پورتفولیوی شخصی متعلق به شماست، اجازه ندهید افراد متفرقه با ایمیل خود در دیتابیس شما کاربر بسازند! + +### آنچه نباید وارد آن شویم (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 (`
`):** اهمیت قفل کردن ثبت‌نام در پورتفولیوی تک‌کاربره. +7. **طراحی و ساخت صفحه ورود شیک (`/login`):** + * کامپوننت‌های فرم و وضعیت لودینگ. + * مدیریت خطاهای رمز عبور نادرست. +8. **فراخوانی متد لاگین با کلاینت سوپابیس (`signInWithPassword`):** ورود به حریم امن. +9. **محافظت از مسیرها با Route Guard در Next.js:** ریدایرکت خودکار غریبه‌ها به صفحه ورود. +10. **باکس نکته Quera (`
`):** تمایز دو مفهوم AuthN و AuthZ در مهندسی وب مدرن. +11. **دکمه خروج ایمن (Sign Out):** پاک کردن نشست و بازگشت به صفحه اصلی. +12. **جمع‌بندی درس‌نامه:** امن شدن کامل پنل مدیریت و ورود به درس نهایی فصل: امنیت سطح ردیف (RLS) در دیتابیس. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] تفاوت احراز هویت و مجوز دسترسی با ادبیات دقیق و تمثیل ملموس تبیین شده باشد. +- [ ] مراحل ساخت کاربر ادمین در Supabase و لزوم غیرفعال‌سازی ثبت‌نام عمومی مستند گردد. +- [ ] کدهای صفحه لاگین و فراخوانی متد `signInWithPassword` به طور کامل در متن لحاظ شوند. +- [ ] منطق محافظت از مسیر `/admin` با مکانیزم ریدایرکت امن تشریح شود. diff --git a/chapters/07-database-and-backend/07-lesson-database-security-rls/spec.md b/chapters/07-database-and-backend/07-lesson-database-security-rls/spec.md new file mode 100644 index 0000000..2959697 --- /dev/null +++ b/chapters/07-database-and-backend/07-lesson-database-security-rls/spec.md @@ -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:** + * `
`: چرا امنیت در سطح پایگاه داده (Database-Level Security) هزاران بار نفوذناپذیرتر از چک‌های ظاهری در کدهای جاوااسکریپت است؟ + * `
`: پرچم قرمز مرگبار؛ هرگز پروژه‌ای را در وضعیت «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 (`
`):** چرا چک‌های امنیتی فرانت‌اند هرگز کافی نیستند؟ +8. **اجرای اسکریپت فعال‌سازی و قفل‌گذاری RLS در SQL Editor:** کپی و اجرای کوئری در چند ثانیه. +9. **آزمون نفوذپذیری و تست زنده امنیت:** + * راستی‌آزمایی در تب ناشناس مرورگر. + * اثبات مسدود شدن درخواست‌های غیرمجاز با خطای ۴۰۳. +10. **باکس هشدار قرمز Quera (`
`):** هرگز پروژه‌ای را با RLS خاموش به پروداکشن نبرید! +11. **جشن پایان فصل هفتم:** اعلام آماده‌سازی ۱۰۰٪ فرانت‌اند، دیتابیس، احراز هویت و امنیت برای ورود به پروژه عملی اول (فصل ۸). + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] مفهوم RLS و خطرات غیرفعال بودن آن به زبانی رسا و هشداردهنده تبیین شده باشد. +- [ ] سیاست‌های امنیتی برای دو جدول `projects` و `site_settings` با کدهای کامل SQL ارائه گردند. +- [ ] تمایز دسترسی عمومی خواندن با دسترسی اختصاصی نگارش ادمین شفاف شده باشد. +- [ ] آزمون عملی تست سیاست‌ها با تب ناشناس مرورگر در متن گنجانده شود.