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