# مشخصات درس‌نامه: رمزگشایی از مستندات 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 ارائه شود.
- [ ] دستورات ترمینالی کپی فایل محیطی برای سیستم‌عامل‌های مختلف در تب‌های کشویی گنجانده شود.