vibe-coding-college-specs/chapters/07-database-and-backend/04-lesson-tables-and-schema-design/spec.md

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