128 lines
12 KiB
Markdown
128 lines
12 KiB
Markdown
# مشخصات درس‌نامه: اصول دیباگ کردن خطاها و خواندن لاگ‌ها با کمک هوش مصنوعی
|
||
- **شناسه در سیلابس:** `L9.5`
|
||
- **فصل:** فصل ۹: تست و Debugging (Ch 9)
|
||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||
- **زمان تقریبی مطالعه:** ۱۵ دقیقه
|
||
- **پیش‌نیازهای مستقیم:** `L9.4` (بررسی خروجی، تست دستی و چک‌لیست QA)
|
||
|
||
---
|
||
|
||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||
- [ ] **درک کند (Understand):** چرا مواجهه با صفحه قرمز خطا (Error Overlay) یا لاگ‌های ترمینال نباید ترسناک باشد و چگونه پیام‌های خطا به عنوان راهنمای مستقیم و گره‌گشای سیستم عمل می‌کنند.
|
||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ساختار یک پیام خطا و ردپای اجرا (Stack Trace) را تفکیک کرده و تفاوت خطاهای فرانت‌اند (کنسول مرورگر / Hydration) را با خطاهای سرور و پایگاه داده (ترمینال / Supabase / 500 / RLS) ارزیابی کند.
|
||
- [ ] **به‌کار ببندد (Apply):** روش سیستماتیک ۴ مرحله‌ای دیباگ (مشاهده دقیق $\rightarrow$ ایزوله‌سازی $\rightarrow$ کشف ریشه با فرضیه‌سازی $\rightarrow$ اصلاح از طریق ایجنت) را روی باگ‌های شبیه‌سازی‌شده در پروژه پورتفولیو پیاده کند.
|
||
- [ ] **ایجاد کند (Create):** پرامپت طلایی «کالبدشکافی و کشف ریشه قبل از نوشتن کد» (Root Cause Analysis Prompt) را تنظیم کند تا از افتادن ایجنت در چرخه وصله‌پینه‌های بی‌اثر جلوگیری نماید.
|
||
|
||
---
|
||
|
||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||
|
||
### آنچه باید پوشش داده شود (In-Scope):
|
||
1. **شکستن طلسم ترس از خطاهای سرخ:**
|
||
* کامپیوترها دروغ نمی‌گویند؛ وقتی خطایی چاپ می‌شود، دقیقاً نام فایل، شماره خط و علت رخ دادن را فریاد می‌زنند.
|
||
2. **کالبدشکافی پیام خطا و استک‌تریس (Anatomy of a Stack Trace):**
|
||
* خط اصلی پیام خطا (Error Message): مشکل چیست؟ (مانند `TypeError: Cannot read properties of undefined`).
|
||
* شماره خط و فایل مبدأ (File and Line Number): مشکل کجاست؟ (مانند `components/ProjectCard.tsx:42:15`).
|
||
* ردپای توابع فراخواننده (Call Stack): چطور به این نقطه رسیدیم؟
|
||
3. **تفکیک جغرافیای خطاهای مدرن وب:**
|
||
* خطاهای مرورگر (Client-side): بررسی در تب Console در Chrome DevTools.
|
||
* خطاهای سرور (Server-side): بررسی در پنجره ترمینال ران‌کننده Next.js (`npm run dev`).
|
||
* خطاهای پایگاه داده و شبکه: بررسی در تب Network و خطاهای HTTP (400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error).
|
||
4. **تکنیک «حل اولین خطا اول» (First Error First):**
|
||
* در بسیاری از مواقع، یک خطای پایه‌ای باعث ایجاد ۲۰ خطای آبشاری بعدی می‌شود. تمرکز فقط بر روی بالاترین خطای رخ داده.
|
||
5. **روش ۴ مرحله‌ای دیباگ سیستماتیک با ایجنت:**
|
||
* گام ۱: متوقف کردن سردرگمی و خواندن آرام پیام.
|
||
* گام ۲: تفکیک کد از لاگ؛ کپی کردن فقط خطوط مفید لاگ (نه ۵۰۰ خط بی‌ربط).
|
||
* گام ۳: ارسال متن خطا + فایل مرتبط با کلید `@` به چت ایجنت.
|
||
* گام ۴: الزام ایجنت به توضیح علت ریشه‌ای (Root Cause) پیش از ارائه پچ و کد جدید.
|
||
6. **دستورات چندسکویی برای تمیز کردن کش و ری‌استارت محیط:**
|
||
* دستورات پاک کردن فولدر `.next` و ری‌استارت سرور توسعه در سه سیستم‌عامل.
|
||
7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<details class="violet">`): مفهوم Hydration Mismatch در Next.js و دلیل تفاوت محتوای سرور و کلاینت.
|
||
* کال‌اوت سبز (`<details class="green">`): قانون طلایی «قانون ۵ دقیقه»؛ اگر ایجنت در دو تلاش باگ را رفع نکرد، کش را پاک کنید و سرور را ری‌استارت کنید.
|
||
* کال‌اوت قرمز (`<details class="red">`): هشدار کپی کردن کامل خروجی‌های غول‌پیکر ترمینال بدون انتخاب پیام خطای هدف.
|
||
|
||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||
- ابزارهای مانیتورینگ آنلاین لاگ‌ها نظیر Sentry یا Datadog (فصل ۱۳).
|
||
- تست‌های نفوذ و دیباگ حملات امنیتی (فصل ۱۱).
|
||
|
||
---
|
||
|
||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||
|
||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||
| :--- | :--- | :--- |
|
||
| Stack Trace | ردپای اجرا / استک‌تریس | فهرست ترتیبی توابعی که در حافظه اجرا شدند تا در نهایت به نقطه بروز خطا رسیدند |
|
||
| Root Cause Analysis | تحلیل ریشه‌ای خطا | فرآیند کشف سرچشمه واقعی مشکل، به جای دستکاری یا وصله‌پینه کردن علائم ظاهری |
|
||
| Hydration Mismatch | ناهمخوانی هایدریشن | خطای فرانت‌اند ناشی از تفاوت محتوای ساخته‌شده توسط سرور با محتوای رندر شده مرورگر |
|
||
| Error Overlay | پرده نمایش خطای زنده | صفحه گرافیکی قرمزرنگی که فریمورک‌هایی مثل Next.js هنگام بروز باگ روی صفحه باز می‌کنند |
|
||
| Cascading Errors | خطاهای آبشاری | خطاهای زنجیره‌ای پرشماری که تنها در اثر یک اشتباه منفرد در ابتدای برنامه پدیدار می‌شوند |
|
||
| Server Action Error | خطای اکشن‌های سرور | باگ‌های مربوط به عملیات سمت سرور در Next.js هنگام برقراری ارتباط با دیتابیس یا فایل‌ها |
|
||
|
||
---
|
||
|
||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** نمایش دیجیتال کاربری که شبیه کارآگاه، سرنخ‌های پیام خطای قرمز در کنسول را دنبال کرده و به قطعه کد معیوب می‌رسد.
|
||
2. **کالبدشکافی پیام خطا و استک‌تریس:** `images/stack-trace-anatomy.png`
|
||
* **موضوع:** اسکرین‌شات از پنجره قرمز خطای Next.js با فلش‌های توضیحی روی پیام خطا، فایل، شماره خط و کال استک.
|
||
3. **دیاگرام جغرافیای خطاها در وب مدرن:** `images/error-geography-diagram.png`
|
||
* **موضوع:** تفکیک سه‌گانه خطاها: کلاینت (کنسول DevTools)، سرور (ترمینال Next.js)، دیتابیس (شبکه و هدرهای Supabase).
|
||
4. **چرخه ۴ مرحله‌ای دیباگ سیستماتیک:** `images/four-step-debugging-flow.png`
|
||
* **موضوع:** فلوچارت تعاملی: مشاهده آرام $\rightarrow$ استخراج لاگ تمیز $\rightarrow$ تحلیل علت با ایجنت $\rightarrow$ تست اصلاحیه.
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# اصول دیباگ کردن خطاها و خواندن لاگ‌ها با کمک هوش مصنوعی`
|
||
2. **مقدمه:** چرا مواجهه با صفحه تماماً قرمز Next.js نشانه شکست نیست، بلکه دقیق‌ترین قطب‌نمای شما برای حل مشکل است؟
|
||
3. **جدول کاور درس**
|
||
4. **استعاره پزشک اورژانس و آزمایش خون:**
|
||
* بیمار داد می‌زند «دلم درد می‌کند» (ظاهر باگ)، اما پزشک به آزمایش خون و برگه علائم حیاتی نگاه می‌کند (لاگ و استک‌تریس).
|
||
5. **کالبدشکافی یک استک‌تریس واقعی در پروژه پورتفولیو:**
|
||
* بررسی عمیق یک خطای متداول:
|
||
`TypeError: Cannot read properties of null (reading 'title')` در صفحه جزئیات پروژه.
|
||
* چگونه شماره خط و نام فایل را بخوانیم و فایل هدف را باز کنیم.
|
||
6. **جغرافیای خطاها: باگ من دقیقاً کجاست؟**
|
||
* خطاهای مرورگر (تب Console در DevTools).
|
||
* خطاهای سرور (صفحه مشکی ترمینال ادیتور).
|
||
* خطاهای ارتباطی و شبکه (تب Network و کدهای وضعیت 401 و 404).
|
||
7. **باکس نکته Quera (`<details class="violet">`):** خطای مشهور Hydration Error در React/Next.js و چرایی وقوع آن هنگام استفاده از افزونه‌های مرورگر یا توابع زمان.
|
||
8. **روش ۴ مرحله‌ای دیباگ سیستماتیک در وایب کدینگ:**
|
||
* گام‌به‌گام از کپی کردن بخش مرتبط تا پرامپت‌نویسی بدون ایجاد سردرگمی برای ایجنت.
|
||
9. **دستورات چندسکویی پاک‌سازی کش در زمان هنگ کردن یا باگ‌های مرموز:**
|
||
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||
- Windows (PowerShell):
|
||
```powershell
|
||
Remove-Item -Recurse -Force .next
|
||
npm run dev
|
||
```
|
||
- macOS (Terminal):
|
||
```bash
|
||
rm -rf .next
|
||
npm run dev
|
||
```
|
||
- Linux (Bash):
|
||
```bash
|
||
rm -rf .next
|
||
npm run dev
|
||
```
|
||
10. **جعبه پرامپت طلایی: تحلیل ریشه‌ای خطا قبل از دستکاری کد:**
|
||
* نمونه پرامپت رسمی:
|
||
> «من با خطای زیر مواجه شدم. پیش از اینکه هیچ تغییری در فایل‌ها اعمال کنی، ۱) به زبان بسیار ساده علت ریشه‌ای بروز این خطا را توضیح بده، ۲) دقیقاً مشخص کن کدام بخش از جریان داده مشکل دارد، ۳) سپس کد اصلاح‌شده پیشنهادی را ارائه بده.»
|
||
11. **باکس هشدار Quera (`<details class="red">`):** پرهیز از بمباران ایجنت با کل متن ترمینال؛ نویز کمتر، دقت بالاتر هوش مصنوعی.
|
||
12. **باکس نکته اطمینان‌بخش Quera (`<details class="green">`):** قانون اولویت اولین خطا (First Error First)؛ حل اولین خطا اغلب ۱۹ خطای بعدی را مانند دومینو ناپدید می‌کند.
|
||
13. **جمع‌بندی درس‌نامه:** تسلط بر مهارت خواندن پیام خطا و آمادگی برای تکنیک‌های دیباگ تعاملی و ابزارهای حاشیه‌نویسی (Annotation) در درس پایانی فصل.
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] ساختار استک‌تریس به همراه مثال کاربردی و ملموس از پورتفولیو توضیح داده شود.
|
||
- [ ] تفکیک شفاف بین خطاهای کلاینت، سرور و دیتابیس با ارجاع به ابزارهای بازرسی انجام گیرد.
|
||
- [ ] پرامپت تحلیل ریشه‌ای (Root Cause Prompt) به همراه استراتژی ۴ مرحله‌ای گنجانده شود.
|
||
- [ ] دستورات ترمینالی پاک‌سازی کش در تب‌های سه‌گانه ویندوز، مک و لینوکس آورده شود.
|