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/05-lesson-connecting-app-to-database/spec.md
+++ b/chapters/07-database-and-backend/05-lesson-connecting-app-to-database/spec.md
@@ -0,0 +1,128 @@
+# مشخصات درس‌نامه: اتصال پروژه به دیتابیس (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` به همراه کدهای استاندارد در متن قرار گیرد.
+- [ ] کوئری دریافت داده در کامپوننت‌های سرور به طور شفاف مستند گردد.
+- [ ] نحوه تست و راستی‌آزمایی افزوده شدن اطلاعات به دیتابیس زنده نشان داده شود.