# مشخصات درس‌نامه: ساخت جداول و کار با داده‌ها در 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) در ادامه اسکریپت گنجانده شده باشد.