vibe-coding-college-specs/chapters/07-database-and-backend/03-lesson-intro-to-supabase/spec.md

مشخصات درس‌نامه: آشنایی با 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 از منظر امنیت به صراحت تاکید گردد.