# مشخصات درس‌نامه: اتصال پروژه به دیتابیس (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` به همراه کدهای استاندارد در متن قرار گیرد.
- [ ] کوئری دریافت داده در کامپوننت‌های سرور به طور شفاف مستند گردد.
- [ ] نحوه تست و راستی‌آزمایی افزوده شدن اطلاعات به دیتابیس زنده نشان داده شود.