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

chapters/07-database-and-backend/02-lesson-api-and-http-methods/spec.md

@@ -0,0 +1,101 @@
+# مشخصات درس‌نامه: مفهوم API و ارتباط سرور با فرانت‌اند (APIs & HTTP Methods)
+- **شناسه در سیلابس:** `L7.3`
+- **فصل:** فصل ۷: داده و بک‌اند (Ch 7)
+- **نوع محتوا:** 📘 درس‌نامه متنی
+- **زمان تقریبی مطالعه:** ۱۲ دقیقه
+- **پیش‌نیازهای مستقیم:** `L7.2` (داده و دیتابیس چیست)
+
+---
+
+## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
+دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
+- [ ] **درک کند (Understand):** رابط برنامه‌نویسی نرم‌افزار (API) چیست و استعاره مشهور «گارسون رستوران» چگونه چرخه ارتباط میان مشتری (فرانت‌اند) و آشپزخانه (پایگاه داده) را توضیح می‌دهد.
+- [ ] **درک کند (Understand):** چرخه درخواست و پاسخ (Request-Response Cycle) و ساختار داده‌های مبادلاتی در قالب زبان جهانی **JSON** چگونه کار می‌کنند.
+- [ ] **تحلیل/ارزیابی کند (Evaluate):** چهار متد اساسی پروتکل HTTP و تطبیق آن‌ها با عملیات چهارگانه CRUD شامل: **GET (خواندن)، POST (ایجاد)، PUT/PATCH (ویرایش)، و DELETE (حذف)** را درک کند.
+- [ ] **تحلیل/ارزیابی کند (Evaluate):** کدهای وضعیت استاندارد HTTP (کدهای ۲۰۰ موفق، ۴۰۱ عدم دسترسی، ۴۰۴ پیدا نشدن، و ۵۰۰ خطای سرور) را برای خطایابی ارتباطات نرم‌افزار تفسیر کند.
+- [ ] **درک کند (Understand):** پلتفرم‌های نوین BaaS (مانند Supabase) چگونه بدون نیاز به نوشتن دستی صدها خط کد سرور، به صورت خودکار برای هر جدول یک REST API امن تولید می‌کنند.
+
+---
+
+## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
+
+### آنچه باید پوشش داده شود (In-Scope):
+1. **استعاره گارسون رستوران (The Restaurant Waiter Analogy):**
+   * شما (کاربر/فرانت‌اند) پشت میز نشسته‌اید و منو را می‌بینید، اما اجازه ندارید خودتان وارد آشپزخانه (دیتابیس) شوید و قابلمه‌ها را دستکاری کنید!
+   * گارسون (API): سفارش شما را به آشپزخانه می‌برد، سرآشپز غذا را آماده می‌کند، و گارسون بشقاب آماده (پاسخ داده‌ها) را به میز شما بازمی‌گرداند.
+2. **کالبدشکافی چرخه درخواست و پاسخ (Request & Response):**
+   * **درخواست (Request):** شامل آدرس اینترنتی (Endpoint)، روش عمل (HTTP Method)، سربرگ‌ها (Headers شامل توکن ورود)، و بدنه داده‌ها (Body).
+   * **پاسخ (Response):** شامل کد وضعیت (Status Code) و بسته اطلاعات نهایی در قالب استاندارد **JSON**.
+3. **متدهای چهارگانه HTTP در پروژه محوری (عملیات CRUD):**
+   * `GET /api/projects`: دریافت لیست تمام کارت‌های پروژه‌ها برای نمایش در ویترین عمومی (خواندن - Read).
+   * `POST /api/projects`: ارسال اطلاعات یک پروژه جدید توسط ادمین برای ذخیره در دیتابیس (ایجاد - Create).
+   * `PATCH /api/projects/123`: ویرایش عنوان یا عکس یک پروژه مشخص (بروزرسانی - Update).
+   * `DELETE /api/projects/123`: حذف دائمی یک پروژه از پایگاه داده (حذف - Delete).
+4. **الفبای کدهای وضعیت (Status Codes): چراغ راهنمایی وب:**
+   * خانواده ۲۰۰ (سبز - موفقیت): `200 OK` (عملیات موفق)، `201 Created` (پروژه با موفقیت ساخته شد).
+   * خانواده ۴۰۰ (زرد - خطای کلاینت): `400 Bad Request` (ورودی نامعتبر)، `401 Unauthorized` (لاگین نکرده‌اید)، `404 Not Found` (یافت نشد).
+   * خانواده ۵۰۰ (قرمز - خطای سرور): `500 Internal Server Error` (کرش دیتابیس یا خطای باگ بک‌اند).
+5. **فرمت جهانی JSON:** نمایش ساختار کلید-مقدار ساده در زبان تبادل داده‌ها.
+6. **کال‌اوت‌های Quera:**
+   * `<details class="violet">`: استعاره گارسون رستوران؛ امن‌ترین روش حفظ پایگاه داده از دسترسی مستقیم مرورگرها.
+   * `<details class="red">`: کدهای وضعیت HTTP؛ نیمی از مهارت حل باگ در وایب کدینگ، نگاه کردن به کد عددی پاسخ سرور در تب Network مرورگر است.
+
+### آنچه نباید وارد آن شویم (Out-of-Scope):
+- نوشتن سرور دستی با پایتون FastAPI یا Node.js Express (سوپابیس این کار را خودکار می‌کند).
+- پروتکل‌های GraphQL یا gRPC (پیچیدگی غیرضروری برای این دوره).
+
+---
+
+## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
+
+| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
+| :--- | :--- | :--- |
+| API (Application Programming Interface) | رابط برنامه‌نویسی کاربردی | پل و زبان مشترک ارتباطی که اجازه می‌دهد دو نرم‌افزار با یکدیگر تبادل داده کنند |
+| REST API | رِست ای‌پی‌آی | معماری استاندارد و وب‌محور برای تبادل داده‌ها با استفاده از متدهای پروتکل HTTP |
+| HTTP Methods / Verbs | متدهای پروتکل وب | دستورات استاندارد مشخص‌کننده نوع عملیات روی داده‌ها (GET, POST, PUT, DELETE) |
+| HTTP Status Code | کد وضعیت پاسخ وب | عدد سه‌رقمی استاندارد که موفقیت یا نوع خطای پاسخ سرور را نشان می‌دهد |
+| JSON | نمادگذاری اشیاء جاوااسکریپت | سبک‌ترین و پرکاربردترین فرمت متنی تبادل اطلاعات مبتنی بر جفت‌های کلید و مقدار |
+
+---
+
+## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
+> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
+
+1. **تصویر کاور درس:** `images/cover.png`
+   * **موضوع:** کاور مدرن با تم تیره که دو جزیره دیجیتال فرانت‌اند و دیتابیس را متصل به یک پل نوری درخشان با نشان‌های متدهای GET, POST, DELETE نشان می‌دهد.
+2. **استعاره گارسون رستوران در عملکرد API:** `images/api-restaurant-waiter-analogy.png`
+   * **موضوع:** تصویر شماتیک: مشتری روی صندلی (فرانت‌اند) $\rightarrow$ گارسون مودب (API) $\rightarrow$ آشپزخانه محافظت‌شده (دیتابیس).
+3. **چرخه رفت‌وبرگشت درخواست و پاسخ:** `images/request-response-cycle.png`
+   * **موضوع:** اینفوگرافیک دوسطره: سطر بالا ارسال Request با متد و بادی $\rightarrow$ سطر پایین دریافت Response با کد وضعیت ۲۰۰ و دیتای JSON.
+4. **ماتریس تطبیق متدها با عملیات CRUD:** `images/crud-to-http-verbs.png`
+   * **موضوع:** جدول شماتیک ۴ ردیفه: ایجاد (Create = POST)، خواندن (Read = GET)، ویرایش (Update = PATCH)، حذف (Delete = DELETE).
+5. **چراغ راهنمایی کدهای وضعیت HTTP:** `images/http-status-codes-traffic-light.png`
+   * **موضوع:** تصویر جذاب ۳ چراغ: سبز (۲۰۰ و ۲۰۱)، زرد (۴۰۱ و ۴۰۴)، قرمز (۵۰۰) با توضیحات کوتاه کاربردی.
+
+---
+
+## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
+
+1. **تیتر اصلی:** `# مفهوم API و ارتباط سرور با فرانت‌اند: شاهراه مکالمه در وب`
+2. **مقدمه:** چرا فرانت‌اند هرگز نباید به طور مستقیم به پایگاه داده وصل شود؟
+3. **جدول کاور درس**
+4. **استعاره گارسون رستوران: API دقیقاً چه کار می‌کند؟:** منطق امنیت و واسطه‌گری.
+5. **کالبدشکافی درخواست و پاسخ (Request & Response):** اجزای یک مکالمه در اینترنت.
+6. **چهار متد اصلی HTTP در دنیای واقعی:**
+   * متد GET برای خواندن پروژه‌ها.
+   * متد POST برای ایجاد پروژه جدید.
+   * متد PATCH برای ویرایش متادیتا و سئو.
+   * متد DELETE برای حذف.
+7. **زبان مادری وب: فرمت داده‌های JSON:** ساختار ساده و کاربردی کلید-مقدار.
+8. **باکس نکته Quera (`<details class="violet">`):** چرا Supabase نیاز به نوشتن دستی کدهای API را برای همیشه حذف کرد؟
+9. **رمزگشایی از کدهای وضعیت HTTP (چراغ راهنمای خطاها):** تفاوت خطای ۴۰۱ با ۴۰۴ و ۵۰۰.
+10. **باکس هشدار Quera (`<details class="red">`):** تب Network در ابزار DevTools مرورگر؛ کلید کشف مشکلات ارتباطی فرانت‌اند با سرور.
+11. **جمع‌بندی درس‌نامه:** تسلط بر مفاهیم ارتباطی و ورود به درس راه‌اندازی عملی پروژه در پلتفرم ابری Supabase.
+
+---
+
+## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
+- [ ] استعاره گارسون برای تفهیم نقش واسطه‌ای و امنیتی API به زبان ساده بیان شده باشد.
+- [ ] متدهای چهارگانه HTTP و تطبیق آن‌ها با عملیات CRUD در سناریوی پروژه پورتفولیو توضیح داده شود.
+- [ ] کدهای وضعیت اصلی به همراه تحلیل علت رخداد هرکدام آموزش داده شوند.
+- [ ] فرمت JSON و ساختار تبادل پیام با کدهای نمونه مستند گردد.