108 lines
11 KiB
Markdown
108 lines
11 KiB
Markdown
# مشخصات درس‌نامه: ساختار و آناتومی پروژه (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` مورد تاکید قرار گیرد.
|
||
- [ ] دستورات ترمینالی در ۳ منوی کشویی مجزا برای سیستم‌عامل‌ها پیاده شوند.
|