106 lines
12 KiB
Markdown
106 lines
12 KiB
Markdown
# مشخصات درس‌نامه: بهبود ساختار کد، پاک‌سازی و ریفکتورینگ امن (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) با مثال‌های ملموس پورتفولیو شرح داده شوند.
|
||
- [ ] پروتکل ۴ مرحله‌ای ریفکتورینگ امن به همراه پرامپت‌های اتمیک ارائه گردد.
|
||
- [ ] کارگاه عملی شکستن کامپوننت بزرگ به کامپوننت‌های ماژولار در متن درس گنجانده شود.
|