vibe-coding-college-specs/chapters/07-database-and-backend/05-lesson-connecting-app-to-database/spec.md

مشخصات درس‌نامه: اتصال پروژه به دیتابیس (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 با منوهای کشویی سیستم‌عامل‌ها:
   • دستور نصب پکیج:

     npm install @supabase/supabase-js
     

   • منوی کشویی ویندوز (Windows).
   • منوی کشویی مک‌اواس (macOS).
   • منوی کشویی لینوکس (Linux).
3. پیکربندی متغیرهای محیطی در .env.local:
   • ساخت فایل محرمانه .env.local در ریشه پروژه.
   • درج کلیدها:

     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:

     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 فوق‌العاده سریع):

     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 به همراه کدهای استاندارد در متن قرار گیرد.
• کوئری دریافت داده در کامپوننت‌های سرور به طور شفاف مستند گردد.
• نحوه تست و راستی‌آزمایی افزوده شدن اطلاعات به دیتابیس زنده نشان داده شود.