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