feat: add chapter 07-database-and-backend specs

chapters/07-database-and-backend/04-lesson-tables-and-schema-design/spec.md

@@ -0,0 +1,106 @@
+# مشخصات درس‌نامه: ساخت جداول و کار با داده‌ها در Supabase (Database Schema Design & Tables)
+- **شناسه در سیلابس:** `L7.5`
+- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
+- **نوع محتوا:** 📘 درس‌نامه متنی
+- **زمان تقریبی مطالعه:** ۱۵ دقیقه
+- **پیش‌نیازهای مستقیم:** `L7.4` (آشنایی با Supabase و راه‌اندازی پروژه)
+
+---
+
+## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
+دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
+- [ ] **درک کند (Understand):** دو روش ساخت جداول در Supabase (روش بصری Table Editor و روش حرفه‌ای اسکریپت SQL) چگونه کار می‌کنند و چرا روش اسکریپت SQL برای وایب کدینگ دقیق‌تر و سریع‌تر است.
+- [ ] **به‌کار ببندد (Apply):** اسکیمای کامل دو جدول اختصاصی پروژه محوری شامل جدول پروژه‌ها (`projects`) و جدول تنظیمات و سئو (`site_settings`) را با انواع داده دقیق طراحی کند.
+- [ ] **به‌کار ببندد (Apply):** اسکریپت استاندارد SQL را در تب SQL Editor سوپابیس اجرا کرده و جداول را در چند ثانیه بسازد.
+- [ ] **به‌کار ببندد (Apply):** داده‌های نمونه فصل ۶ (Mock Data) را در قالب کوئری درج (`INSERT`) وارد پایگاه داده ابری کند تا جداول از وضعیت خالی خارج شوند.
+- [ ] **تحلیل/ارزیابی کند (Evaluate):** الگوی معماری «جدول تک‌سطری (Single-Row Table Pattern)» را برای مدیریت تنظیمات و متادیتای سئو تحلیل و پیاده‌سازی نماید.
+
+---
+
+## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
+
+### آنچه باید پوشش داده شود (In-Scope):
+1. **دو مسیر ساخت جدول در Supabase:**
+   * **مسیر بصری (Table Editor):** کلیک روی New Table و افزودن ستون‌ها با ماوس (خوب برای بررسی اولیه).
+   * **مسیر مهندسی (SQL Editor):** کپی کردن اسکریپت تمیز SQL و زدن دکمه Run (روش ایده‌آل برای همکاری با ایجنت‌های هوش مصنوعی بدون خطر خطای دستی).
+2. **طراحی اسکیمای جدول پروژه‌ها (`projects`):**
+   * `id`: نوع `uuid` با مقدار پیش‌فرض `gen_random_uuid()` به عنوان کلید اصلی.
+   * `created_at`: نوع `timestamptz` با مقدار پیش‌فرض `now()`.
+   * `title`: نوع `text` اجباری (NOT NULL).
+   * `description`: نوع `text` برای توضیحات کوتاه کارت.
+   * `long_description`: نوع `text` برای متن کامل در مودال جزئیات.
+   * `image_url`: نوع `text` آدرس عکس کاور.
+   * `tags`: نوع `text[]` (آرایه متنی) با مقدار پیش‌فرض `'{}'`.
+   * `live_url`: نوع `text` آدرس دموی اینترنتی.
+   * `github_url`: نوع `text` آدرس گیت‌هاب.
+   * `featured`: نوع `boolean` با مقدار پیش‌فرض `false`.
+3. **طراحی اسکیمای جدول تنظیمات سئو و مشخصات سایت (`site_settings`):**
+   * الگوی جدول تک‌سطری: فقط یک رکورد با `id = 1` وجود دارد که اطلاعات کل پورتفولیو را نگهداری می‌کند.
+   * ستون‌های `site_title`, `meta_description`, `og_image_url`, `author_name`, `bio`, `contact_email`.
+4. **اسکریپت آماده و کامل SQL (Copy-Paste Migration Script):**
+   * ارائه قطعه کد کامل ساخت جداول به همراه مقادیر اولیه (Seed Data) از پروژه‌های تستی فصل ۶.
+5. **مشاهده زنده رکوردهای ثبت‌شده در Table Editor:**
+   * باز کردن ادیتور بصری و دیدن ۶ ردیف پروژه همراه با تصاویر و تگ‌ها در بستر ابری سوپابیس.
+   * تست ویرایش درون‌خطی (Inline Edit) یک عنوان به عنوان تمرین عملی.
+6. **کال‌اوت‌های Quera:**
+   * `<details class="violet">`: الگوی جدول تک‌سطری (Single-Row Pattern)؛ ساده‌ترین و مطمئن‌ترین ترفند برای نگهداری متادیتای سئو و اطلاعات عمومی سایت.
+   * `<details class="red">`: تله مقادیر پیش‌فرض فراموش‌شده؛ چرا ستون‌های تاریخ و آرایه همیشه باید مقدار دیفالت داشته باشند تا با خطای `null` مواجه نشویم.
+
+### آنچه نباید وارد آن شویم (Out-of-Scope):
+- پیکربندی روابط پیچیده چندبه‌چند (Many-to-Many) یا جوین‌های سنگین دیتابیس.
+- اتصال مستقیم کد فرانت‌اند به این جداول (درس بعدی ۷.۶).
+
+---
+
+## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
+
+| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
+| :--- | :--- | :--- |
+| SQL Editor | ویرایشگر فرامین اس‌کیو‌ال | محیط اجرای مستقیم دستورات متنی پایگاه داده برای ساخت و مدیریت ساختار جداول |
+| Single-Row Pattern | الگوی جدول تک‌سطری | ساختار جدولی که فقط یک رکورد ثابت دارد و برای ذخیره تنظیمات سراسری سیستم استفاده می‌شود |
+| Default Value | مقدار پیش‌فرض | مقداری که در صورت عدم ارسال دیتا توسط کاربر، به صورت خودکار در ستون ثبت می‌شود |
+| Seed Data | داده‌های اولیه / بذری | اطلاعات نمونه و آماده‌ای که در بدو راه‌اندازی برای تست اولیه به دیتابیس تزریق می‌شوند |
+| Text Array (text[]) | آرایه متنی در پستگرس | قابلیت ذخیره چندین برچسب یا کلمه در قالب یک لیست درون یک ستون واحد دیتابیس |
+
+---
+
+## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
+> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
+
+1. **تصویر کاور درس:** `images/cover.png`
+   * **موضوع:** کاور مدرن با تم تیره که جداول شفاف و نورانی دیتابیس را با ستون‌های مرتب و کدهای SQL اجرا شده در پس‌زمینه نمایش می‌دهد.
+2. **نقشه دیاگرام دو جدول پورتفولیو:** `images/portfolio-database-schema-diagram.png`
+   * **موضوع:** اینفوگرافیک مقایسه‌ای دو جدول: جدول چندسطری `projects` (برای نمونه‌کارها) در کنار جدول تک‌سطری `site_settings` (برای متادیتای سئو).
+3. **اجرای اسکریپت در SQL Editor سوپابیس:** `images/supabase-sql-editor-run.png`
+   * **موضوع:** اسکرین‌شات تمیز از محیط کدنویسی SQL در Supabase با دکمه سبز Run و پیام موفقیت‌آمیز `Success. No rows returned`.
+4. **نمای رکوردهای ماک در Table Editor:** `images/supabase-table-editor-projects.png`
+   * **موضوع:** اسکرین‌شات از جدول واقعی `projects` در سوپابیس که ردیف‌های شیک پروژه‌ها با تگ‌ها و تصاویر را نشان می‌دهد.
+5. **الگوی جدول تک‌سطری سئو در عمل:** `images/single-row-settings-demo.png`
+   * **موضوع:** نمایش تصویری جدول `site_settings` با ردیف واحد و فیلدهای تایتل، دیسکریپشن و آدرس عکس اوپن‌گراف.
+
+---
+
+## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
+
+1. **تیتر اصلی:** `# ساخت جداول و کار با داده‌ها در Supabase: پیاده‌سازی اسکلت اطلاعات`
+2. **مقدمه:** چرا نوشتن اسکریپت SQL با هوش مصنوعی بسیار مطمئن‌تر از کلیک‌های دستی در منوهاست؟
+3. **جدول کاور درس**
+4. **انتخاب استراتژی: ویرایشگر بصری یا اسکریپت سریع SQL؟:** مقایسه دو رویکرد.
+5. **کالبدشکافی اسکیمای جدول پروژه‌ها (`projects`):** فیلدهای شناسه، عنوان، تگ‌ها و لینک‌ها.
+6. **معماری جدول تنظیمات سئو (`site_settings`):**
+   * چرا الگوی جدول تک‌سطری بهترین راهکار مدیریت متادیتا است؟
+7. **باکس نکته Quera (`<details class="violet">`):** راز سادگی و پایداری الگوی Single-Row در مدیریت تنظیمات سایت.
+8. **اجرای اسکریپت کامل ساخت جداول و تزریق داده‌های اولیه (Seed Data):**
+   * کد کامل و آماده برای کپی در SQL Editor.
+   * اجرای کوئری با یک کلیک.
+9. **بازرسی رکوردهای زنده در Table Editor:** مشاهده داده‌ها و تست ویرایش یک ستون.
+10. **باکس هشدار Quera (`<details class="red">`):** اهمیت تعریف مقادیر پیش‌فرض برای پیشگیری از باگ‌های Null در آینده.
+11. **جمع‌بندی درس‌نامه:** تولد جداول واقعی در پایگاه داده ابری و آماده شدن برای متصل کردن فرانت‌اند Next.js به این داده‌ها در درس بعد.
+
+---
+
+## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
+- [ ] ساختار جداول `projects` و `site_settings` به همراه انواع داده و قیود به دقت مستند شده باشد.
+- [ ] اسکریپت کامل و قابل اجرای SQL در متن درس‌نامه قرار گیرد.
+- [ ] الگوی جدول تک‌سطری برای تنظیمات سئو با استدلال فنی تشریح شود.
+- [ ] تزریق داده‌های نمونه اولیه (Seed Data) در ادامه اسکریپت گنجانده شده باشد.