vibe-coding-college-specs/chapters/12-deployment-and-shipping/05-lesson-production-environment-variables/spec.md

مشخصات درس‌نامه: پیکربندی متغیرهای محیطی پروداکشن در پنل‌های ابری (Environment Variables)

• شناسه در سیلابس: L12.6
• فصل: فصل ۱۲: انتشار روی اینترنت (Ch 12)
• نوع محتوا: 📘 درس‌نامه متنی
• زمان تقریبی مطالعه: ۱۶ دقیقه
• پیش‌نیازهای مستقیم: L12.5 (استقرار عملی پروژه پورتفولیو در لیارا و ورسل)

---

۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)

دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:

• درک کند (Understand): چرا ۹۵٪ خطاهای ناگهانی صفحه سفید یا کرش سرور پس از استقرار اولیه (خطای ۵۰۰)، ناشی از غیبت متغیرهای محیطی در سرور ابری است و چرا فایل .env.local هرگز به همراه کدها به سرور فرستاده نمی‌شود.
• تحلیل/ارزیابی کند (Evaluate): تفاوت‌های حیاتی میان مقادیر متغیرها در محیط لوکال و محیط واقعی (به‌ویژه متغیر NEXT_PUBLIC_APP_URL برای آدرس‌های بازگشت زرین‌پال و اوت‌اوت گوگل) را ارزیابی کند.
• به‌کار ببندد (Apply): تمام متغیرهای محیطی پروژه پورتفولیو (کلیدهای سوپابیس، کاوه‌نگار، لیارا SMTP، زرین‌پال، Upstash و OpenRouter) را در بخش تنظیمات متغیرهای کنسول لیارا و Vercel تزریق نماید.
• ایجاد کند (Create): چرخه بازاستقرار (Trigger Redeploy) را پس از ذخیره متغیرها اجرا کرده و پایداری کامل برنامه در محیط پروداکشن را راستی‌آزمایی کند.

---

۲. محدوده و مرزهای محتوا (Scope & Boundaries)

آنچه باید پوشش داده شود (In-Scope):

1. معمای سرور گیج: «من کلیدها را از کجا بخوانم؟»:
   • شما به درستی .env.local را در .gitignore گذاشتید تا فاش نشود؛ در نتیجه سرور ابری پروژه‌ای خالی از کلید دریافت کرده است!
2. کالبدشکافی تزریق متغیرها در داشبورد لیارا:
   • ورود به برنامه پورتفولیو در پنل Liara.ir \rightarrow بخش «تنظیمات» \rightarrow تب «متغیرها».
   • امکان افزودن تکی یا پیست کردن دسته‌ای (Bulk Paste) تمام خطوط .env.
   • راه‌اندازی مجدد (Restart) برنامه برای خوانده شدن متغیرهای جدید توسط کانتینر.
3. کالبدشکافی تزریق متغیرها در داشبورد Vercel:
   • ورود به پروژه در Vercel \rightarrow تب Settings \rightarrow انتخاب Environment Variables.
   • تفکیک محیط‌ها: Production، Preview و Development.
   • لزوم زدن دکمه Redeploy برای اعمال متغیرها در مرحله بیلد.
4. تغییرات کلیدی متغیرها از لوکال به پروداکشن:
   • متغیر شماره یک: NEXT_PUBLIC_APP_URL
     • در لوکال: http://localhost:3000
     • در پروداکشن: https://my-portfolio.liara.run یا دامنه شخصی شما.
     • چرا این متغیر حیاتی است؟ زرین‌پال کاربر را بعد از پرداخت به این آدرس برمی‌گرداند؛ تگ‌های Open Graph عکس‌های شبکه‌های اجتماعی را از این آدرس می‌خوانند!
5. بررسی چک‌لیست کامل متغیرهای پروژه پورتفولیو:
   • جدول جامع تمام متغیرها: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, KAVENEGAR_API_KEY, SMTP_HOST, ZARINPAL_MERCHANT_ID, UPSTASH_REDIS_REST_URL, OPENROUTER_API_KEY, ADMIN_EMAIL.
6. کال‌اوت‌های آموزشی و هشدار کوئرا:
   • کال‌اوت بنفش (<details class="violet">): مفهوم تزریق در زمان بیلد (Build-time Inlining) برای متغیرهای با پیشوند NEXT_PUBLIC_ و چرایی نیاز به بیلد مجدد پس از تغییر آن‌ها.
   • کال‌اوت سبز (<details class="green">): قابلیت کپی-پیست یکجای کل محتوای فایل .env در پنل متغیرهای لیارا در ۲ ثانیه.
   • کال‌اوت قرمز (<details class="red">): تله راه‌اندازی مجدد نکردن؛ تغییر متغیرها بدون ری‌استارت برنامه در پنل ابری هیچ اثری نخواهد داشت.

آنچه نباید وارد آن شویم (Out-of-Scope):

• استفاده از سرویس‌های مدیریت متغیرهای توزیع‌شده بین‌سازمانی (Doppler یا Infisical).
• رمزنگاری کلیدها با کلیدهای نامتقارن PGP در خط فرمان.

---

۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

اصطلاح انگلیسی	معادل فارسی مصوب	توضیح یک‌خطی ساده
Production Environment Variable	متغیر محیطی پروداکشن	تنظیمات پیکربندی و کلیدهای حساسی که مستقیماً در پنل هاست ابری برای سرور واقعی تعریف می‌شوند
Build-time Inlining	جایگذاری در زمان بیلد	فرآیندی که در آن کامپایلر Next.js مقادیر عمومی (NEXT_PUBLIC_) را در هنگام بیلد داخل کدهای فرانت‌اند حک می‌کند
Bulk Import	بارگذاری یکپارچه دسته‌ای	امکان کپی کردن همزمان تمام خطوط فایل تنظیمات در پنل ابری بدون نیاز به ثبت دانه به دانه
App Restart / Redeploy	راه‌اندازی مجدد / استقرار دوباره	متوقف کردن و اجرای مجدد کانتینر سرور به منظور بارگذاری مقادیر جدید متغیرهای محیطی در حافظه
Root URL Dynamic Mapping	نگاشت پویای آدرس ریشه	تنظیم هوشمند آدرس اصلی سایت به گونه‌ای که لینک‌های بازگشتی با دامنه واقعی محیط همگام باشند

---

۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)

راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ images/ ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. تصویر کاور درس: images/cover.png
   • موضوع: نمایش پنل تنظیمات دیجیتال مدرن با فیلدهای کلیدهای رمزی و دکمه‌های سوئیچ سبز در داشبورد سرور ابری.
2. مسیر تزریق متغیرها در کنسول لیارا: images/liara-environment-variables-panel.png
   • موضوع: اسکرین‌شات از تب متغیرها در پنل لیارا با دکمه بارگذاری دسته‌ای و لیست کلیدهای سوپابیس و کاوه‌نگار.
3. تنظیم متغیرها در داشبورد Vercel با انتخاب محیط: images/vercel-environment-variables-setup.png
   • موضوع: اسکرین‌شات از بخش Settings ورسل با تیک‌باکس‌های Production و Preview برای هر متغیر.
4. اثر حیاتی متغیر NEXT_PUBLIC_APP_URL بر درگاه پرداخت و سئو: images/app-url-importance-flow.png
   • موضوع: اینفوگرافیک مقایسه‌ای: مقدار اشتباه (هدایت کاربر بانک به صفحه خراب localhost:3000) در برابر مقدار صحیح (هدایت کاربر به دامنه زنده پورتفولیو).

---

۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)

1. تیتر اصلی: # پیکربندی متغیرهای محیطی پروداکشن در پنل‌های ابری (Environment Variables)
2. مقدمه: سایت بالا آمد اما به محض کلیک روی دکمه‌ها ارور ۵۰۰ می‌دهد؟ نفس عمیق بکشید؛ این طبیعی‌ترین اتفاق بعد از اولین دیپلوی است!
3. جدول کاور درس
4. چرا فایل .env.local شما در سرور ابری وجود ندارد؟
   • یادآوری امنیت گیت؛ ما عمداً کلیدها را به گیت‌هاب نفرستادیم تا هک نشویم، اکنون باید آن‌ها را دستی به سرور برسانیم.
5. آموزش تصویری تزریق متغیرها در پنل لیارا (Liara):
   • رفتن به تنظیمات \rightarrow بخش متغیرها \rightarrow کپی کردن محتوای تمیز .env \rightarrow ذخیره و راه‌اندازی مجدد.
6. آموزش تزریق متغیرها در پنل Vercel:
   • انتخاب Environment Variables \rightarrow تنظیم اسکوپ Production \rightarrow زدن دکمه Redeploy.
7. شاه‌کلید تمام آدرس‌های بازگشتی: تنظیم NEXT_PUBLIC_APP_URL:
   • چرا این متغیر را باید با آدرس واقعی سایت (دامنه لیارا، ورسل یا دامنه اختصاصی) پر کنید.
8. جدول چک‌لیست نهایی تمام متغیرهای پروژه پورتفولیو:
   • مروری بر ۸ متغیر ضروری: Supabase, Kavenegar, Liara SMTP, ZarinPal, Upstash, OpenRouter, Admin Email.
9. باکس نکته Quera (<details class="violet">): چرا تغییر متغیرهای عمومی کلاینتی حتماً نیازمند بیلد دوباره (Redeploy) است در حالی که متغیرهای سروری با یک Restart ساده اعمال می‌شوند.
10. باکس هشدار Quera (<details class="red">): هرگز فاصله‌های اضافی (Space) قبل یا بعد از کلیدها در کادر پنل نگذارید؛ این خطای پنهان ساعت‌ها وقت شما را می‌گیرد!
11. باکس رضایت‌بخش Quera (<details class="green">): رفرش کردن سایت زنده پس از تنظیم متغیرها و مشاهده لود شدن آنی پروژه‌ها از دیتابیس Supabase و سلامت کامل سیستم.
12. جمع‌بندی درس‌نامه: تثبیت کامل مغز متغیرهای ابری؛ ورود به گام باشکوه پایانی فصل: ثبت و اتصال دامنه اختصاصی، DNS و CDN در درس بعدی.

---

۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)

• علت بروز خطاهای پس از دیپلوی ناشی از نبود متغیرهای محیطی به زبان ساده تبیین شود.
• شیوه تزریق متغیرها در هر دو پنل لیارا و ورسل به صورت گام‌به‌گام تشریح گردد.
• اهمیت تغییر متغیر NEXT_PUBLIC_APP_URL از لوکال به دامنه واقعی پروداکشن تحلیل شود.
• جدول چک‌لیست تمام کلیدهای مورد نیاز پروژه پورتفولیو در متن ارائه گردد.