# مشخصات درس‌نامه: ساختار و آناتومی پروژه (Project Anatomy & File Architecture)
- **شناسه در سیلابس:** `L3.8`
- **فصل:** فصل ۳: راه‌اندازی محیط کار (Ch 3)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۲ دقیقه
- **پیش‌نیازهای مستقیم:** `L3.7` (استفاده از Skillها و MCPها)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** نقش و جایگاه پوشه‌ها و فایل‌های اصلی یک پروژه مدرن وب (کانفیگ‌های ریشه، پوشه سورس کد `src/`، پوشه فایل‌های استاتیک `public/` و مخزن پکیج‌ها `node_modules/`) چیست.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** فایل حیاتی `package.json` را بازخوانی کند؛ ساختار بخش اسکریپت‌ها (`scripts`) و لیست وابستگی‌ها (`dependencies`) را به عنوان شناسنامه پروژه تحلیل نماید.
- [ ] **درک کند (Understand):** پوشه حجیم `node_modules/` چیست، چرا هرگز نباید دستی ویرایش یا در گیت ذخیره شود، و چگونه با یک فرمان ساده `npm install` دوباره دانلود و بازسازی می‌شود.
- [ ] **به‌کار ببندد (Apply):** فایل محیطی `.env` را به عنوان صندوقچه امن رمزها بشناسد و متغیرهای حساس را جدا از کدهای پروژه نگهداری کند.
- [ ] **به‌کار ببندد (Apply):** دستورات مشاهده ساختار درختی پروژه در ترمینال را بر اساس سیستم‌عامل خود (ویندوز، مک، لینوکس) با منوهای کشویی اجرا کند.

---

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

### آنچه باید پوشش داده شود (In-Scope):
1. **شکستن ترس از شلوغی کدهای پروژه:**
   * در نخستین نگاه به درخت فایل‌های یک پروژه وب، ده‌ها پوشه و فایل نامفهوم دیده می‌شود. در این درس معماری استاندارد و منطق پشت هرکدام را کالبدشکافی می‌کنیم.
2. **آناتومی ۴ گانه ساختار پروژه:**
   * **۱. پوشه سورس کد (`src/` یا `app/`):** قلب تپنده نرم‌افزار؛ کدهایی که ایجنت می‌نویسد، صفحات، دکمه‌ها و استایل‌ها اینجا قرار دارند.
   * **۲. پوشه فایل‌های ایستا (`public/`):** انبار عکس‌ها، آیکون‌ها، فونت‌ها و فایل‌هایی که بدون تغییر به کاربر تحویل داده می‌شوند.
   * **۳. انبار پکیج‌ها (`node_modules/`):** پوشه غول‌پیکری که npm تمام کتابخانه‌های دانلودشده را در آن می‌ریزد.
   * **۴. فایل‌های پیکربندی ریشه (Root Config Files):** نگهبانان و شناسنامه پروژه.
3. **کالبدشکافی فایل شناسنامه پروژه (`package.json`):**
   * نام و نسخه پروژه (`name`, `version`).
   * دستورات اجرایی (`scripts` مثل `npm run dev` برای بالا آوردن سرور محلی یا `npm run build`).
   * فهرست پکیج‌ها و کتابخانه‌های مورد نیاز (`dependencies`).
4. **راز پوشه مخوف `node_modules` (The Scary Folder):**
   * استعاره انبار بزرگ قطعات یدکی خودرو.
   * چرا نباید از حجم بالای آن ترسید؟ اگر این پوشه پاک شود، فقط با تایپ `npm install` در چند ثانیه مجدداً ساخته می‌شود.
5. **فایل محرمانه `.env` (صندوقچه امن):**
   * چرا کلیدهای هوش مصنوعی، رمزهای پایگاه داده و درگاه پرداخت نباید داخل کدهای برنامه هاردکد (Hardcode) شوند.
   * تفاوت فایل نمونه `.env.example` با فایل اصلی `.env`.
6. **مشاهده ساختار پروژه در ترمینال با منوهای کشویی سیستم‌عامل‌ها:**
   * `<details><summary>دستورات در ویندوز (PowerShell / CMD)</summary> ... </details>`: دستور `dir` و `tree /F`.
   * `<details><summary>دستورات در مک‌اواس (macOS Terminal)</summary> ... </details>`: دستور `ls -la` و `tree`.
   * `<details><summary>دستورات در لینوکس (Linux Bash)</summary> ... </details>`: دستور `ls -la` و پکیج `tree`.
7. **کال‌اوت‌های Quera:**
   * `<details class="violet">`: کالبدشکافی سریع `package.json`؛ روش حرفه‌ای بررسی یک پروژه جدید در کمتر از ۲ دقیقه.
   * `<details class="red">`: قانون ممنوعه: هرگز کدهای درون پوشه `node_modules` را با دست تغییر ندهید چون با اولین آپدیت بازنویسی می‌شوند!

### آنچه نباید وارد آن شویم (Out-of-Scope):
- کانفیگ‌های پیچیده بیلد مانند Webpack یا Rollup و Vite پلاگین‌های تخصصی.
- نوشتن کدهای کامپوننت‌های فرانت‌اند (شروع از فصل ۶).

---

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

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Project Anatomy | آناتومی / ساختار پروژه | معماری و نحوه چیدمان استاندارد فایل‌ها و پوشه‌ها در یک نرم‌افزار |
| package.json | شناسنامه و مانیفست پروژه | فایل مرکزی در پروژه‌های جاوااسکریپت که اطلاعات، پکیج‌ها و دستورات اجرایی را فهرست می‌کند |
| Dependencies | وابستگی‌ها / پکیج‌های پیش‌نیاز | کتابخانه‌ها و ابزارهای خارجی که پروژه شما برای کار کردن به آن‌ها وابسته است |
| node_modules | پوشه پکیج‌های نصب‌شده | پوشه محلی ذخیره‌سازی فایل‌های کتابخانه‌های دانلودشده توسط مدیریت پکیج npm |
| Environment Variables (.env) | متغیرهای محیطی | فایل محرمانه نگهداری آدرس‌ها، رمزها و کلیدهای API دور از چشم عموم و کدهای عمومی |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** کاور مدرن نمایش‌دهنده کالبدشکافی شماتیک ساختار درختی فایل‌ها به همراه نورپردازی آیکون‌های کد، انبار داده و پوشه‌ها.
2. **اسکلت و آناتومی پروژه مدرن وب:** `images/project-anatomy-skeleton.png`
   * **موضوع:** تصویر شماتیک بدن یک اپلیکیشن: پوشه `src` (قلب و اندام‌ها)، پوشه `public` (لباس و ویترین)، `package.json` (کارت ملی) و `node_modules` (انبار ابزارها).
3. **کالبدشکافی فایل `package.json`:** `images/package-json-anatomy.png`
   * **موضوع:** اسکرین‌شات برچسب‌گذاری‌شده با فلش‌های رنگی که بخش‌های Scripts، Dependencies و DevDependencies را توضیح می‌دهد.
4. **استعاره انبار `node_modules` و بازسازی آن:** `images/node-modules-warehouse.png`
   * **موضوع:** تصویر انبار بزرگ قطعات و فلش اجرای دستور `npm install` که نشان می‌دهد در صورت حذف پوشه، فوراً قابل بازسازی است.
5. **صندوقچه امن متغیرهای محیطی (`.env`):** `images/env-secrets-vault.png`
   * **موضوع:** دیاگرام یک گاوصندوق دیجیتال محرمانه که کلیدهای API را از دید کدهای عمومی و گیت‌هاب پنهان نگه می‌دارد.

---

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

1. **تیتر اصلی:** `# ساختار و آناتومی پروژه: رمزگشایی از فایل‌ها و پوشه‌ها`
2. **مقدمه:** چرا یادگیری نقشه فایل‌های پروژه، ترس شما از مواجهه با کدبیس‌ها را برای همیشه از بین می‌برد؟
3. **جدول کاور درس**
4. **چهار ستون تشکیل‌دهنده یک پروژه وب:** مرور پوشه‌های اصلی `src`، `public`، `node_modules` و فایل‌های ریشه.
5. **شناسنامه پروژه: کالبدشکافی `package.json`:**
   * نام و اسکریپت‌های کاربردی (`npm run dev`).
   * لیست وابستگی‌ها و پکیج‌ها.
6. **باکس نکته Quera (`<details class="violet">`):** اولین جایی که یک مهندس حرفه‌ای در یک پروژه ناشناس باز می‌کند.
7. **اسرار پوشه `node_modules`: چرا انقدر بزرگ است؟:** استعاره انبار و آموزش دستور نجات‌بخش `npm install`.
8. **باکس هشدار Quera (`<details class="red">`):** هرگز فایل‌های درون `node_modules` را ویرایش نکنید!
9. **صندوقچه امن کلیدها: فایل `.env`:** نحوه نگهداری کلیدهای هوش مصنوعی دور از کدهای مخزن.
10. **دستورات مشاهده ساختار فایل‌ها در ترمینال:**
    * کشوی ویندوز (Windows).
    * کشوی مک‌اواس (macOS).
    * کشوی لینوکس (Linux).
11. **جمع‌بندی درس‌نامه:** پایان موفقیت‌آمیز دروس آموزشی فصل ۳ و آماده‌سازی برای آزمون جامع راه‌اندازی محیط کار.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] ساختار پوشه‌ها و فایل‌های کلیدی (`package.json`، `node_modules`، `.env`، `src`، `public`) بدون ابهام و با زبان ساده تشریح شده باشد.
- [ ] چرخه حیات `package.json` و نحوه بازسازی پوشه `node_modules` با `npm install` آموزش داده شود.
- [ ] مفهوم امنیت متغیرهای محیطی در فایل `.env` مورد تاکید قرار گیرد.
- [ ] دستورات ترمینالی در ۳ منوی کشویی مجزا برای سیستم‌عامل‌ها پیاده شوند.