vibe-coding-college-specs/chapters/10-external-services/02-lesson-reading-docs-and-managing-keys/spec.md

مشخصات درس‌نامه: رمزگشایی از مستندات 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):

       Copy-Item .env.example .env.local
       

     • macOS (Terminal):

       cp .env.example .env.local
       

     • Linux (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 ارائه شود.
• دستورات ترمینالی کپی فایل محیطی برای سیستم‌عامل‌های مختلف در تب‌های کشویی گنجانده شود.