vibe-coding-college-specs/chapters/03-workspace-setup/07-lesson-project-anatomy/spec.md

مشخصات درس‌نامه: ساختار و آناتومی پروژه (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 مورد تاکید قرار گیرد.
• دستورات ترمینالی در ۳ منوی کشویی مجزا برای سیستم‌عامل‌ها پیاده شوند.