# مشخصات درس‌نامه: بهبود ساختار کد، پاک‌سازی و ری‌فکتورینگ امن (Safe Refactoring) با هوش مصنوعی
- **شناسه در سیلابس:** `L15.5`
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
- **پیش‌نیازهای مستقیم:** `L15.4` (کالبدشکافی و کاوش در Codebase با ایجنت‌ها)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** مفهوم ری‌فکتورینگ (Refactoring: اصلاح ساختار درونی بدون تغییر در رفتار بیرونی سیستم) را شرح دهد و بداند چرا کدهای شتاب‌زده MVP نیازمند بازطراحی و پاک‌سازی هستند.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** نشانه‌های بدبویی کد (Code Smells: کامپوننت‌های غول‌پیکر چندصدخطی، کدهای کپی-پیست تکراری، و تایپ‌های مجهول `any`) را در پروژه شناسایی و ارزیابی کند.
- [ ] **به‌کار ببندد (Apply):** پروتکل ۴ مرحله‌ای ری‌فکتورینگ امن (سپر تست قبلی $\rightarrow$ پرامپت ایزوله اتمیک $\rightarrow$ بازبینی Diff $\rightarrow$ بیلد مجدد) را برای شکستن کامپوننت‌های بزرگ به ماژول‌های تمیز پیاده کند.
- [ ] **ایجاد کند (Create):** یک کامپوننت ۳۰۰ خطی پنل مدیریت پورتفولیو را با هدایت ایجنت به ۴ ساب‌کامپوننت خوانا، ماژولار و تست‌پذیر تفکیک نماید.

---

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

### آنچه باید پوشش داده شود (In-Scope):
1. **استعاره تمیزکاری و مرتب‌سازی ابزارهای کارگاه:**
   * در هنگام ساخت اولیه میخ‌ها و اره‌ها کف کارگاه می‌ریزند؛ پس از ساخت، ابزارها را روی دیوار می‌چینید تا در کارهای بعدی مانع پای شما نشوند.
2. **شکار «بوی بد کد» (Code Smells) در پروژه‌های ساخته‌شده با AI:**
   * بوی بد ۱: کامپوننت‌های خدای‌گونه (God Components)؛ یک فایل ۴۰۰ خطی که هم دیتابیس می‌خواند، هم فرم رندر می‌کند، هم مودال باز می‌کند و هم انیمیشن دارد!
   * بوی بد ۲: منطق تکراری کپی-پیست‌شده (Duplicate Queries)؛ نوشتن کوئری‌های یکسان سوپابیس در ۵ صفحه مختلف به جای یک تابع واحد.
   * بوی بد ۳: اعدام تایپ‌اسکریپت با کلمه `any`؛ تنبلی در تعریف تایپ داده‌ها که امنیت کد را از بین می‌برد.
3. **پروتکل ۴ مرحله‌ای ری‌فکتورینگ ایمن با ایجنت:**
   * مرحله ۱ (سپر دفاعی): اطمینان از پاس شدن تست‌های Vitest/Playwright و اجرای بیلد سالم قبل از هرگونه تغییر.
   * مرحله ۲ (پرامپت اتمیک ایزوله): درخواست جراحی محدود: «فقط این فایل را بشکن؛ به هیچ فایل دیگری دست نزن و نام Props را تغییر نده».
   * مرحله ۳ (بازبینی خط‌به‌خط Git Diff): بررسی اینکه آیا منطق یا استایلی ناخواسته حذف یا مفقود شده است یا خیر.
   * مرحله ۴ (تست تایید سلامت): اجرای مجدد تست‌ها و بیلد نهایی برای اطمینان از صفر بودن خطای پس‌رفتی.
4. **کارگاه عملی: جراحی و ماژولار کردن جدول مدیریت پروژه‌ها:**
   * تبدیل فایل متورم `AdminProjectsTable.tsx` به:
     - `ProjectRow.tsx` (رندر هر سطر)
     - `DeleteProjectDialog.tsx` (مودال حذف)
     - `ProjectStatusBadge.tsx` (بج وضعیت)
     - `hooks/useProjects.ts` (هوک اختصاصی مدیریت استیت‌ها).
5. **جعبه پرامپت طلایی برای ری‌فکتورینگ تمیز:**
   * پرامپت تخصصی بازنویسی با شرط حفظ ۱۰۰٪ رفتار قبلی.
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): قانون طلایی مارتین فاولر؛ ری‌فکتورینگ نباید یک پروژه ۶ ماهه جداگانه باشد، بلکه عادتی پیوسته در حین اضافه کردن هر فیچر جدید است.
   * کال‌اوت سبز (`<details class="green">`): لذت دیدن کدهای تمیز، خوانا و کوتاه که هر برنامه‌نویس ارشدی از دیدن آن شگفت‌زده می‌شود.
   * کال‌اوت قرمز (`<details class="red">`): اشتباه فاجعه‌بار؛ هرگز به ایجنت نگویید: «کل پروژه را ریفکتور کن!»؛ این پرامپت به توهمات گسترده و شکستن کل برنامه‌ منجر می‌شود.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- مهاجرت از فریم‌ورکی به فریم‌ورک دیگر (مثلاً Next.js به Remix یا Vue).
- بازطراحی کل اسکیمای دیتابیس که نیازمند از دست رفتن داده‌های پروداکشن باشد.

---

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

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Refactoring | بازنویسی و بهسازی ساختار | بهبود خوانایی، سادگی و نگهداری‌پذیری کدها بدون تغییر در عملکرد ظاهری آن‌ها |
| Code Smell | نشانه‌های بدبویی کد | ساختارها و الگوهای نامناسب در کد که نشان‌دهنده نقص در طراحی یا پتانسیل بروز باگ در آینده هستند |
| God Component | کامپوننت همه‌کاره غول‌پیکر | کامپوننتی تک‌افتاده که وظایف بیش از حد متعددی را بر عهده گرفته و فهم و نگهداری آن کابوس است |
| Single Responsibility (SRP) | اصل تک‌مسئولیتی | اصل بنیادین مهندسی که می‌گوید هر ماژول یا کامپوننت فقط و فقط باید یک وظیفه مشخص داشته باشد |
| Atomic Refactoring | بازنویسی اتمیک و دانه‌دانه | اصلاح پله‌پله و ایزوله بخش‌های کوچک کد برای پیشگیری از بروز خطاهای آبشاری در پروژه |

---

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

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** سیم‌پیچی‌های آشفته و گره‌خورده دیجیتال که توسط بازوهای نوری ایجنت باز شده و به کابل‌های مرتب و موازی درخشان تبدیل می‌شوند.
2. **شکستن یک کامپوننت غول‌پیکر به ماژول‌های تمیز:** `images/god-component-decomposition.png`
   * **موضوع:** دیاگرام ساختاری: فایل ۴۰۰ خطی بزرگ در چپ $\rightarrow$ فلش بازطراحی $\rightarrow$ تفکیک به ۴ فایل کوچک، هوک و کامپوننت مستقل در راست.
3. **چرخه ۴ مرحله‌ای ری‌فکتورینگ امن:** `images/safe-refactoring-loop.png`
   * **موضوع:** فلوچارت محافظتی: تست سبز قبلی $\rightarrow$ پرامپت ایزوله $\rightarrow$ بررسی Git Diff $\rightarrow$ راستی‌آزمایی با بیلد موفق.
4. **تفاوت Git Diff یک ری‌فکتور موفق:** `images/refactored-git-diff-view.png`
   * **موضوع:** اسکرین‌شات از نمایش خطوط پاک‌شده اضافه و جایگزینی با ایمپورت‌های ماژولار و بسیار کوتاه.

---

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

1. **تیتر اصلی:** `# بهبود ساختار کد، پاک‌سازی و ری‌فکتورینگ امن (Safe Refactoring) با هوش مصنوعی`
2. **مقدمه:** کدهایتان کار می‌کند، اما شبیه یک کمد لباس به هم ریخته است که هر بار درش را باز می‌کنید چیزی روی سرتان می‌افتد؟ وقت یک خانه‌تکانی لذت‌بخش مهندسی است!
3. **جدول کاور درس**
4. **تعریف ری‌فکتورینگ: تغییر لباس بدون تغییر ماهیت:**
   * چرا کاربر نباید هیچ تفاوتی در ظاهر حس کند، اما شما در توسعه آینده ۱۰ برابر سریع‌تر می‌شوید.
5. **شکار ۳ بوی بد رایج در پروژه‌های وایب کدینگ:**
   * کامپوننت‌های همه‌کاره (God Components)، کدهای تکراری، و فرار از تایپ‌های دقیق.
6. **پروتکل ۴ مرحله‌ای جراحی امن کد:**
   * تست سلامت $\rightarrow$ پرامپت اتمیک $\rightarrow$ کنترل گیت‌دیف $\rightarrow$ تایید نهایی با بیلد.
7. **مطالعه موردی: جراحی جدول ۴۰۰ خطی پنل مدیریت پورتفولیو:**
   * تفکیک عملی به ساب‌کامپوننت‌های `ProjectRow`, `DeleteDialog` و ساخت هوک `useProjects`.
8. **جعبه پرامپت طلایی: ری‌فکتورینگ اتمیک با ایجنت هوش مصنوعی:**
   * پرامپت دقیق:
     > «من می‌خواهم فایل `AdminProjectsTable.tsx` را ری‌فکتور کنم. بدون تغییر در هیچ‌یک از قابلیت‌های فعلی و بدون تغییر نام Props، ۱) این فایل را به ۳ کامپوننت تک‌مسئولیتی در پوشه `components/admin/` تقسیم کن، ۲) منطق مدیریت وضعیت‌ها را به یک کاستوم هوک در `hooks/useProjects.ts` منتقل کن، و ۳) تایپ‌های دقیق تایپ‌اسکریپت بدون استفاده از any برای آن بنویس.»
9. **باکس نکته Quera (`<details class="violet">`):** استفاده از تکنیک Boy Scout Rule: «کدبیس را همیشه تمیزتر از آنچه تحویل گرفته‌اید تحویل دهید».
10. **باکس هشدار Quera (`<details class="red">`):** هرگز فیچر جدید را همزمان با ریفکتورینگ کد قبلی ننویسید! این دو کار باید در دو کامیت کاملاً مجزا انجام شوند تا در صورت بروز باگ، تفکیک امکان‌پذیر باشد.
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** باز کردن فایل اصلی پروژه و دیدن کاهش حجم کد از ۴۰۰ خط به ۵۰ خط بسیار تمیز و سازمان‌یافته.
12. **جمع‌بندی درس‌نامه:** مجهز شدن به سلاح پاک‌سازی کد؛ ورود به جهان هیجان‌انگیز قابلیت‌های پیشرفته هوش مصنوعی (Semantic Search و خلاصه‌سازها) در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] مفهوم ری‌فکتورینگ و چرایی اهمیت آن در پروژه‌های فعال تبیین شود.
- [ ] نشانه‌های بدبویی کد (Code Smells) با مثال‌های ملموس پورتفولیو شرح داده شوند.
- [ ] پروتکل ۴ مرحله‌ای ری‌فکتورینگ امن به همراه پرامپت‌های اتمیک ارائه گردد.
- [ ] کارگاه عملی شکستن کامپوننت بزرگ به کامپوننت‌های ماژولار در متن درس گنجانده شود.