feat: add chapter 10-external-services specs

2026-09-05 22:26:08 +08:00
parent 5b26a487c1
commit 8059df0781
8 changed files with 900 additions and 0 deletions
--- a/chapters/10-external-services/02-lesson-reading-docs-and-managing-keys/spec.md
+++ b/chapters/10-external-services/02-lesson-reading-docs-and-managing-keys/spec.md
@@ -0,0 +1,119 @@
+# مشخصات درس‌نامه: رمزگشایی از مستندات API و مدیریت امن کلیدها (Credentials & .env)
+- **شناسه در سیلابس:** `L10.3`
+- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
+- **نوع محتوا:** 📘 درس‌نامه متنی
+- **زمان تقریبی مطالعه:** ۱۵ دقیقه
+- **پیش‌نیازهای مستقیم:** `L10.2` (سرویس Third-Party چیست)
+
+---
+
+## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
+دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
+- [ ] **درک کند (Understand):** ساختار استاندارد مستندات فنی API (شامل Base URL، هدرهای احراز هویت، اندپوینت‌ها، متدهای HTTP و نمونه‌های cURL/JSON) را به راحتی بخواند و درک کند.
+- [ ] **تحلیل/ارزیابی کند (Evaluate):** تفاوت متغیرهای محیطی امن سمت سرور با متغیرهای عمومی کلاینتی با پیشوند `NEXT_PUBLIC_` را تشخیص داده و خطرات نشت اطلاعات حساس را ارزیابی کند.
+- [ ] **به‌کار ببندد (Apply):** فایل‌های `.env.local` و `.env.example` را به شکل استاندارد در پروژه پورتفولیو ایجاد و مقادیر آزمایشی کلیدها را در آن ذخیره نماید.
+- [ ] **ایجاد کند (Create):** یک پرامپت طلایی برای ایجنت بنویسد که با دریافت نمونه کد cURL یا مستندات وب‌سرویس، یک ماژول ارتباطی تمیز با تایپ‌های کامل TypeScript تولید کند.
+
+---
+
+## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
+
+### آنچه باید پوشش داده شود (In-Scope):
+1. **شکستن ترس از مستندات انگلیسی و جداول پارامترها:**
+   * مستندات API شبیه دفترچه راهنمای یک تلویزیون جدید است؛ لازم نیست همه صفحات را بخوانید، فقط باید بدانید دکمه روشن و پورت ورودی کجاست!
+2. **کالبدشکافی ۵ بخش اصلی هر سند API:**
+   * ۱. آدرس پایه (Base URL): سرور مرکزی کجاست؟ (مثلاً `https://api.kavenegar.com/v1/`).
+   * ۲. شیوه ارسال احراز هویت (Authentication): کلید در هدر `Authorization: Bearer <KEY>` است یا داخل پارامترهای آدرس؟
+   * ۳. مسیرها و متدها (Endpoints & Methods): آیا داده می‌فرستیم (`POST`) یا داده می‌خوانیم (`GET`)؟
+   * ۴. بدنه درخواست (Request Body / Payload): چه فیلدهایی اجباری (Required) و چه فیلدهایی اختیاری (Optional) هستند؟
+   * ۵. پاسخ سرور و کدهای وضعیت (Response & Status Codes): پاسخ موفق ۲۰۰۰، خطای ۴۰۱ احراز هویت، خطای ۴۲۹ محدودیت درخواست و خطای ۵۰۰ سرور.
+3. **تکنیک میانبر وایب کدینگ: خوراندن مستندات به ایجنت هوش مصنوعی:**
+   * نحوه کپی کردن دستور cURL از مستندات و تبدیل آن به کدهای تایپ‌اسکریپت تمیز توسط ایجنت با دستور `@docs`.
+4. **قوانین طلایی مدیریت کلیدها و گاوصندوق `.env.local`:**
+   * قانون شماره ۱: هرگز کلید را هاردکد نکنید (`const apiKey = "123"` ممنوع!).
+   * قانون شماره ۲: فایل `.env.local` باید در `.gitignore` ثبت شده باشد تا هیچ‌وقت روی گیت‌هاب آپلود نشود.
+   * قانون شماره ۳: ساخت فایل نمونه `.env.example` بدون مقادیر واقعی برای سایر اعضای تیم یا ریپازیتوری عمومی.
+   * قانون شماره ۴: تفاوت حیاتی متغیرهای معمولی (مخفی در سرور) با متغیرهای دارای پیشوند `NEXT_PUBLIC_` (آشکار در مرورگر کاربر).
+5. **دستورات چندسکویی برای کپی و مدیریت فایل‌های محیطی:**
+   * ساخت `.env.local` از روی `.env.example` با دستورات ترمینال برای ویندوز، مک و لینوکس.
+6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
+   * کال‌اوت بنفش (`<details class="violet">`): نحوه کار ربات‌های اسکنر گیت‌هاب که کلیدهای لو رفته را در عرض چند ثانیه سرقت می‌کنند.
+   * کال‌اوت سبز (`<details class="green">`): ابزارهای تستی سریع مانند Thunder Client یا استفاده از دستور ساده `curl` برای راستی‌آزمایی کارکرد کلید در ۳۰ ثانیه.
+   * کال‌اوت قرمز (`<details class="red">`): هرگز کلیدهای واقعی و اعتباری خود را داخل چت‌بات‌های عمومی یا تیکت‌های پشتیبانی نگذارید.
+
+### آنچه نباید وارد آن شویم (Out-of-Scope):
+- مباحث پیشرفته هشینگ و امضای دیجیتال توکن‌های JWT (فصل ۱۱).
+- اتصال اختصاصی وب‌سرویس‌های خاص (در درس‌های بعدی فصل ۱۰ به تفکیک بررسی می‌شوند).
+
+---
+
+## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
+
+| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
+| :--- | :--- | :--- |
+| API Documentation | مستندات رابط برنامه‌نویسی | راهنمای رسمی ارائه‌دهنده سرویس که نحوه ارسال درخواست و قالب پاسخ را شرح می‌دهد |
+| Base URL | آدرس پایه سرور | ریشه اصلی آدرس وب‌سرویس که تمام مسیرها و درخواست‌ها به انتهای آن متصل می‌شوند |
+| Bearer Token | توکن حامل | فرمت استاندارد ارسال کلید امنیتی در هدر درخواست HTTP برای اثبات هویت مجاز |
+| Environment Variable | متغیر محیطی | مقادیر تنظیمی خارج از کد برنامه که در فایل‌های محلی تنظیم و متناسب با محیط تغییر می‌کنند |
+| GitLeaks / Secret Leak | نشت اطلاعات محرمانه | حادثه امنیتی خطرناک انتشار ناخواسته رمزها و کلیدهای خصوصی در تاریخچه گیت |
+| cURL | ابزار خط فرمان cURL | دستور ترمینالی استاندارد برای شبیه‌سازی و ارسال درخواست‌های شبکه به سرورها |
+
+---
+
+## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
+> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
+
+1. **تصویر کاور درس:** `images/cover.png`
+   * **موضوع:** گاوصندوق دیجیتال مستحکم نئونی که کلیدهای API را محافظت می‌کند در کنار یک دفترچه راهنمای مدرن که مسیرهای نوری از آن خارج می‌شوند.
+2. **کالبدشکافی ساختار سند API مدرن:** `images/api-docs-anatomy.png`
+   * **موضوع:** اسکرین‌شات از صفحه مستندات یک وب‌سرویس مدرن با فلش‌های توضیحی روی Base URL، Header، Request Body و Response JSON.
+3. **تفکیک دو دنیای متغیرهای محیطی در Next.js:** `images/env-variables-boundary.png`
+   * **موضوع:** اینفوگرافیک مقایسه‌ای: سمت سرور (دیوار محرمانه، متغیرهای بدون پیشوند) در برابر سمت کلاینت (پیشوند NEXT_PUBLIC_، دید همگانی در سورس صفحه مرورگر).
+4. **تبدیل نمونه cURL به کد تایپ‌اسکریپت با ایجنت:** `images/curl-to-typescript-prompt.png`
+   * **موضوع:** پنجره چت ادیتور که دستور cURL مستندات به ایجنت داده شده و ایجنت یک فانکشن تمیز تایپ‌شده تحویل داده است.
+
+---
+
+## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
+
+1. **تیتر اصلی:** `# رمزگشایی از مستندات API و مدیریت امن کلیدها (Credentials & .env)`
+2. **مقدمه:** چگونه مستندات وب‌سرویس‌ها را در ۵ دقیقه رمزگشایی کنیم و کلیدهای محرمانه را مثل طلا در گاوصندوق نگه داریم؟
+3. **جدول کاور درس**
+4. **استعاره منوی رستوران و گارسون:**
+   * مستندات API دقیقاً مثل منوی رستوران است: غذاها چیست (Endpoints)، هزینه چیست (Payload)، و غذا چطور سرو می‌شود (Response).
+5. **کالبدشکافی ۵ رکن اساسی هر سند API با مثال واقعی:**
+   * آدرس پایه، هدرهای Authorization، متدهای GET/POST، بدنه جیسون و کدهای پاسخ موفق و خطا.
+6. **سریع‌ترین تست با دستور cURL در ترمینال:**
+   * تست یک‌خطی ساده برای راستی‌آزمایی پاسخ سرور قبل از شروع کدنویسی.
+7. **روش تبدیل مستندات به ماژول آماده تایپ‌اسکریپت با ایجنت هوش مصنوعی:**
+   * جعبه پرامپت طلایی:
+     > «من این نمونه درخواست cURL را از مستندات وب‌سرویس دارم: [نمونه cURL]. لطفاً یک تابع Server Action تایپ‌اسکریپت تمیز در Next.js با تایپ‌های مشخص برای ورودی‌ها و خروجی‌ها بساز که کلید API را از `process.env` بخواند و خطاهای شبکه را با پیام خطای خوانا به زبان فارسی مدیریت کند.»
+8. **مدیریت گاوصندوق `.env.local` و جلوگیری از فاجعه نشت کلید:**
+   * چرا کلیدها هرگز داخل کدهای گیت وارد نمی‌شوند؟
+   * تفاوت حساسیت‌برانگیز بین متغیرهای معمولی سروری و متغیرهای `NEXT_PUBLIC_`.
+9. **دستورات چندسکویی ساخت فایل تنظیمات محیطی:**
+   * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
+     - Windows (PowerShell):
+       ```powershell
+       Copy-Item .env.example .env.local
+       ```
+     - macOS (Terminal):
+       ```bash
+       cp .env.example .env.local
+       ```
+     - Linux (Bash):
+       ```bash
+       cp .env.example .env.local
+       ```
+10. **باکس نکته Quera (`<details class="violet">`):** ماجرای وحشتناک ربات‌های اسکنر گیت‌هاب؛ نشت یک کلید API در یک مخزن عمومی و مصرف میلیون‌ها تومان اعتبار در کمتر از چند دقیقه!
+11. **باکس راهنمای Quera (`<details class="green">`):** افزونه‌های ساده مثل Thunder Client در ادیتور برای تست اندپوینت‌ها با یک کلیک.
+12. **باکس هشدار Quera (`<details class="red">`):** چک‌لیست نهایی فایل `.gitignore`؛ مطمئن شوید عبارت `.env*.local` در خطوط گیت‌ایگنور وجود دارد.
+13. **جمع‌بندی درس‌نامه:** تسلط کامل بر زبان مستندات API و گاوصندوق متغیرهای محیطی؛ ورود به اولین اتصال واقعی: ارسال پیامک با وب‌سرویس‌های کاوه‌نگار و SMS.ir در درس بعدی.
+
+---
+
+## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
+- [ ] پنج بخش اصلی مستندات API با مثال‌های بصری و ملموس تشریح شوند.
+- [ ] مرز امنیتی متغیرهای سروری و متغیرهای دارای پیشوند `NEXT_PUBLIC_` تبیین گردد.
+- [ ] پرامپت طلایی تبدیل مستندات و نمونه cURL به کدهای تمیز TypeScript ارائه شود.
+- [ ] دستورات ترمینالی کپی فایل محیطی برای سیستم‌عامل‌های مختلف در تب‌های کشویی گنجانده شود.