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