feat: add chapter 07-database-and-backend specs

2026-09-05 22:15:28 +08:00
parent 405cab3828
commit d6c371f485
8 changed files with 858 additions and 0 deletions
--- 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
@@ -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 از منظر امنیت به صراحت تاکید گردد.