feat: add chapter 13-product-maintenance specs
This commit is contained in:
@@ -0,0 +1,82 @@
|
|||||||
|
# مشخصات درس‌نامه: اهداف فصل سیزدهم (Chapter Goals)
|
||||||
|
- **شناسه در سیلابس:** `L13.1`
|
||||||
|
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۵ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L12.7` (اتصال دامنه اختصاصی، DNS و SSL)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چرا انتشار نرم‌افزار پایان کار نیست بلکه آغاز زندگی واقعی آن است و تفاوت یک کدنویس موقت با یک مالک محصول حرفه‌ای در هنر «نگهداری و پایش پایدار» (Product Maintenance & Observability) نهفته است.
|
||||||
|
- [ ] **درک کند (Understand):** نقشه راه ۷ درس‌نامه تخصصی فصل سیزدهم شامل: مشاهده‌پذیری و سلامت منابع (Monitoring)، هشدارهای زنده آپتایم با UptimeRobot، ثبت و ردگیری خطاهای سرور زنده با Sentry و لاگ‌های لیارا/ورسل، به‌روزرسانی امنیتی پکیج‌ها، سئو تکنیکال و تحلیل رفتار کاربر با Google Search Console و Microsoft Clarity، و مستندسازی حرفه‌ای پروژه را بشناسد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ارزش آگاهی پیش‌دستانه از خرابی سیستم (باخبر شدن سازنده قبل از گلایه کاربران) را در برابر نادیده گرفتن وضعیت پس از انتشار ارزیابی نماید.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** ابزارهای مانیتورینگ سلامت، داشبوردهای رصد باگ، و تحلیل‌گرهای رفتار کاربر را روی پورتفولیوی زنده خود مستقر سازد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **ورود به فاز حیات و مراقبت از محصول زنده:**
|
||||||
|
* خودرویی که ساخته شده نیاز به کیلومترشمار، نشانگر بنزین و هشدارهای تعویض روغن دارد؛ پورتفولیو و نرم‌افزار شما نیز به همین ابزارها نیاز دارد.
|
||||||
|
2. **مرور سرفصل‌های تخصصی فصل ۱۳:**
|
||||||
|
* درس ۱۳.۲: مشاهده‌پذیری و مانیتورینگ (Observability)؛ بررسی مصرف رم، پردازنده، پهنای باند و نرخ درخواست‌ها در داشبورد لیارا و Vercel.
|
||||||
|
* درس ۱۳.۳: سامانه‌های آپتایم و اعلان خطر (Alerting)؛ پایش وضعیت ۲۴ ساعته با UptimeRobot و ارسال هشدار فوری تلگرام و ایمیل در صورت قطعی سرور.
|
||||||
|
* درس ۱۳.۴: ثبت لاگ‌ها و ردگیری خطاهای پروداکشن (Error Tracking)؛ عیب‌یابی خطاهای زنده کاربران با Sentry و اتصال لاگ‌های سرور.
|
||||||
|
* درس ۱۳.۵: به‌روزرسانی امنیتی و نگهداری دوره‌ای؛ روش ایمن آپدیت کتابخانه‌ها با `npm update` و مدیریت آسیب‌پذیری‌ها بدون شکستن پروژه.
|
||||||
|
* درس ۱۳.۶: سئو تکنیکال و تحلیل رفتار کاربر؛ ثبت سایت در Google Search Console، تولید داینامیک نقشه سایت (`sitemap.ts`)، و مشاهده فیلم تعامل کاربران با Microsoft Clarity.
|
||||||
|
* درس ۱۳.۷: مستندسازی و کتابچه راهنمای نگهداری (Playbooks)؛ تدوین `README.md` فاخر، راهنمای مشارکت و سناریوهای رفع بحران با کمک ایجنت‌های هوش مصنوعی.
|
||||||
|
3. **هم‌راستایی با پروژه پورتفولیو:**
|
||||||
|
* تجهیز پورتفولیو به سنسورهای هوشمند برای رصد اینکه کارفرمایان چه بخش‌هایی از رزومه را بیشتر نگاه می‌کنند و آیا در ثبت پیام با خطایی روبرو می‌شوند یا خیر.
|
||||||
|
4. **کال‌اوت‌های کوئرا:**
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): خواب راحت شبانه با داشتن سیستم هشدار تلگرامی که در صورت هرگونه نقص فنی به شما پیام می‌دهد.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- توسعه فیچرهای بنیادین جدید یا بازنویسی معماری با هوش مصنوعی (فصل ۱۵).
|
||||||
|
- ساخت پایپ‌لاین‌های اتوماسیون CI/CD سازمانی پیچیده.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Observability | مشاهده‌پذیری سیستم | توانایی درک و استنتاج وضعیت درونی و سلامت نرم‌افزار از روی خروجی‌ها و داده‌های بیرونی آن |
|
||||||
|
| Uptime Monitoring | پایش پایداری و در دسترس بودن | بررسی مستمر و خودکار آنلاین بودن سایت در فواصل زمانی کوتاه (مثلاً هر ۵ دقیقه) |
|
||||||
|
| Error Tracking | ردگیری و تله‌گذاری خطاها | ثبت خودکار استک‌تریس و جزئیات خطاهای رخ داده در مرورگر یا سرور کاربران بدون نیاز به گزارش آن‌ها |
|
||||||
|
| Technical SEO | سئوی تکنیکال و فنی | بهینه‌سازی ساختار کدها، متاتگ‌ها و نقشه سایت برای فهم آسان صفحات توسط خزنده‌های موتور جستجو |
|
||||||
|
| Heatmap & Session Replay | نقشه حرارتی و بازپخش نشست | ابزار بصری ثبت محل کلیک‌ها، اسکرول‌ها و تماشای ویدیویی نحوه گشت‌وگذار کاربر در صفحات سایت |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** اتاق کنترل دیجیتال مدرن و تاریک با نمودارهای زنده مانیتورینگ ضربان قلب سرور، نقشه‌های حرارتی سایت و زنگ هشدارهای امنیتی.
|
||||||
|
2. **نقشه راه جامع فصل ۱۳:** `images/chapter-13-roadmap.png`
|
||||||
|
* **موضوع:** اینفوگرافیک ۷ مرحله‌ای فصل ۱۳ با نمادهای سلامت سرور، UptimeRobot، سنتری، آپدیت وابستگی‌ها، سرچ کنسول، کلاریتی و مستندات گیت‌هاب.
|
||||||
|
3. **مثلث مراقبت از محصول پس از عرضه:** `images/product-maintenance-triangle.png`
|
||||||
|
* **موضوع:** دیاگرام مثلثی: ۱) مشاهده‌پذیری و آپتایم $\rightarrow$ ۲) کشف باگ و لاگینگ $\rightarrow$ ۳) بهینه‌سازی بر اساس رفتار واقعی کاربر.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# اهداف فصل سیزدهم: نگهداری محصول؛ اتاق کنترل سلامت، پایداری و رشد`
|
||||||
|
2. **مقدمه کوتاه:** چرا بزرگ‌ترین اشتباه یک توسعه‌دهنده، رها کردن سایت به حال خود پس از انتشار است؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **سرفصل‌های طلایی فصل در یک نگاه:** مرور ۷ ایستگاه مراقبت و مانیتورینگ محصول.
|
||||||
|
5. **جدول نقشه راه یادگیری فصل**
|
||||||
|
6. **سه‌گانه طلایی مراقبت: آپتایم، عیب‌یابی با سنتری و تحلیل رفتار با مایکروسافت کلاریتی.**
|
||||||
|
7. **پورتفولیوی شخصی به عنوان یک سیستم هوشمند و پویا:** دیدن اینکه چه کارفرمایی رزومه شما را دانلود کرده یا روی کدام پروژه کلیک کرده است.
|
||||||
|
8. **کال‌اوت روحیه‌بخش Quera (`<details class="green">`):** وقتی باگ‌ها قبل از باخبر شدن کارفرما در جیب شما آلارم بزنند، به اوج پرستیژ مهندسی دست یافته‌اید!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] اهداف کلان فصل ۱۳ و لزوم مراقبت پس از استقرار تبیین شود.
|
||||||
|
- [ ] سرفصل‌های ۷ درس‌نامه بعدی با ذکر ابزارهای مصوب (Sentry, UptimeRobot, Clarity, Search Console) معرفی گردند.
|
||||||
|
- [ ] مفهوم مشاهده‌پذیری (Observability) به زبان ساده و قابل فهم ارائه شود.
|
||||||
@@ -0,0 +1,100 @@
|
|||||||
|
# مشخصات درس‌نامه: مشاهده‌پذیری و مانیتورینگ منابع سرور (Observability & Monitoring)
|
||||||
|
- **شناسه در سیلابس:** `L13.2`
|
||||||
|
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L13.1` (اهداف فصل سیزدهم)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت میان «مانیتورینگ ساده» (آیا سرور بالاست؟) با «مشاهده‌پذیری عمیق» (چرا حافظه رم پر شده و کدام روت باعث کندی است؟) را شرح دهد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** چهار سیگنال طلایی پایداری نرم‌افزار (تأخیر Latency، ترافیک Traffic، نرخ خطا Errors، و درجه اشباع منابع Saturation) را در داشبوردهای ابری تحلیل کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** نمودارهای زنده‌ی مصرف حافظه (RAM)، پردازنده (CPU)، دیسک، و اتصالات فعال دیتابیس Supabase را در پنل‌های لیارا و ورسل بازرسی و مدیریت نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** راهکارهای برطرف‌سازی نشت حافظه (Memory Leaks) در روت‌های Next.js را با کمک ابزارهای بهینه‌سازی شناسایی کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **استعاره علائم حیاتی بیمار در اتاق مراقبت‌های ویژه (ICU):**
|
||||||
|
* پزشک تنها به زنده بودن بیمار نگاه نمی‌کند؛ فشار خون، ضربان قلب و اکسیژن خون را رصد می‌کند.
|
||||||
|
2. **چهار سیگنال طلایی گوگل برای ارزیابی سلامت سیستم‌ها (Four Golden Signals):**
|
||||||
|
* ۱. تاخیر (Latency): مدت زمانی که طول می‌کشد تا سرور به درخواست کاربر پاسخ دهد (بررسی شاخص‌های p50 و p95).
|
||||||
|
* ۲. ترافیک (Traffic): حجم تقاضا و تعداد درخواست‌های وارده در ثانیه/دقیقه.
|
||||||
|
* ۳. نرخ خطا (Errors): درصد درخواست‌هایی که با کدهای خطای ۵۰۰ یا ۴۰۰ شکست می‌خورند در مقایسه با پاسخ‌های ۲۰۰ موفق.
|
||||||
|
* ۴. درجه اشباع (Saturation): درصد مصرف منابع محدود سرور (رم، پردازنده، دیسک، تعداد اتصالات استخر دیتابیس).
|
||||||
|
3. **رصد زنده منابع در کنسول پلتفرم ابری لیارا:**
|
||||||
|
* نمودارهای لحظه‌ای پردازنده (CPU) و رم (Memory) در داشبورد برنامه پورتفولیو.
|
||||||
|
* تشخیص وضعیت کرش ناشی از کمبود رم (Out of Memory - OOM) و نحوه ارتقای اندازه پلن یا ری‌استارت کانتینر.
|
||||||
|
4. **رصد متریک‌ها در داشبورد Vercel:**
|
||||||
|
* مشاهده درصد درخواست‌های کش‌شده در لبه (Edge Cache Hit Ratio) و تاخیر توابع سرورلس.
|
||||||
|
5. **رصد شاخص‌های پایگاه داده در کنسول Supabase:**
|
||||||
|
* تعداد کانکشن‌های باز به PostgreSQL و اطمینان از بسته شدن مناسب اتصالات در Server Actions.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم شاخص صدک ۹۵ام (p95 Latency)؛ چرا بررسی «میانگین» گول‌زننده است و تاخیر کندترین ۵ درصد کاربران را پنهان می‌کند.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): مشاهده نمودار مصرف رم لیارا در مقیاس مگابایت که برای پورتفولیو معمولاً زیر ۱۵۰ مگابایت بسیار پایدار است.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): خطر نشت حافظه (Memory Leak)؛ ذخیره آرایه‌های غول‌پیکر در متغیرهای سراسری خارج از توابع که سرور را وادار به ریستارت مداوم می‌کند.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- نصب سیستم‌های پیچیده پایش کلاستری Prometheus و Grafana.
|
||||||
|
- تنظیمات شبکه SDN دیتاسنترها.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Golden Signals | سیگنال‌های طلایی سلامت | چهار معیار کلیدی سنجش عملکرد و قابلیت اطمینان سیستم‌های نرم‌افزاری تحت شبکه |
|
||||||
|
| Latency (p95) | تاخیر صدک نود و پنج | حداکثر زمانی که طول می‌کشد تا ۹۵٪ کاربران پاسخ درخواست خود را دریافت کنند |
|
||||||
|
| Saturation | اشباع منابع | میزان پر بودن یا نزدیک شدن ظرفیت پردازنده، حافظه یا شبکه به سقف ۱۰۰ درصدی |
|
||||||
|
| Memory Leak | نشت حافظه | باگی که در آن حافظه اشغال‌شده پس از اتمام کار آزاد نشده و سرور را به سمت کرش OOM می‌برد |
|
||||||
|
| OOM (Out of Memory) | خطای اتمام حافظه | وضعیتی که سیستم‌عامل به دلیل پر شدن ۱۰۰٪ رم، فرآیند اجرای برنامه را اجباراً متوقف می‌کند |
|
||||||
|
| Connection Pooling | استخر اتصالات دیتابیس | مدیریت اشتراکی کانکشن‌های پایگاه داده برای جلوگیری از باز شدن صدها اتصال همزمان سنگین |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** مانیتورهای نئونی مدرن با نمودارهای ضربان قلب دیجیتال، مصرف رم و پردازنده و عقربه‌های سرعت لود صفحات.
|
||||||
|
2. **چهار سیگنال طلایی سلامت سیستم:** `images/four-golden-signals-infographic.png`
|
||||||
|
* **موضوع:** اینفوگرافیک ۴ گانه: تاخیر (کرنومتر)، ترافیک (موج ورودی)، خطا (آیکون ارور قرمز)، و اشباع (گیج نشانگر رم و سی‌پی‌یو).
|
||||||
|
3. **نمودارهای مصرف منابع در داشبورد لیارا:** `images/liara-metrics-graphs.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از پنل پایش لیارا با خطوط نمودار مصرف رم و پردازنده بر حسب درصد و مگابایت در طول ۲۴ ساعت.
|
||||||
|
4. **داشبورد متریک‌های پایگاه داده Supabase:** `images/supabase-database-metrics.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از بخش Database Metrics در سوپابیس با نمودار کانکشن‌های فعال و فضای اشغال‌شده دیسک.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# مشاهده‌پذیری و مانیتورینگ منابع سرور (Observability & Monitoring)`
|
||||||
|
2. **مقدمه:** سایت بالا آمد؛ اما چگونه مثل یک پزشک متخصص، ضربان قلب و علائم حیاتی سرور خود را از راه دور رصد کنیم؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره رانندگی با سرعت ۲۰۰ کیلومتر با داشبورد خاموش!**
|
||||||
|
* اگر عقربه بنزین، دمای آب و سرعت‌سنج نباشد، هر لحظه منتظر انفجار موتور باشید.
|
||||||
|
5. **معرفی ۴ سیگنال طلایی گوگل برای سنجش پایداری وب:**
|
||||||
|
* تاخیر (Latency)، ترافیک (Traffic)، خطاها (Errors)، و اشباع منابع (Saturation).
|
||||||
|
6. **خوانش نمودارهای مصرف در پلتفرم ابری لیارا:**
|
||||||
|
* بررسی رم و پردازنده؛ چه موقع سرور زیر بار کم می‌آورد و نیاز به افزایش پلن دارد؟
|
||||||
|
7. **کالبدشکافی خطای مرگبار Out of Memory (OOM):**
|
||||||
|
* چرا رم سرور پر می‌شود و چطور با کدهای استاندارد از نشت حافظه جلوگیری کنیم؟
|
||||||
|
8. **پایش اتصالات پایگاه داده در Supabase:**
|
||||||
|
* مفهوم Connection Pooling و جلوگیری از قفل شدن دیتابیس توسط اکشن‌های سرور.
|
||||||
|
9. **باکس نکته Quera (`<details class="violet">`):** جادوی شاخص صدک ۹۵ام (p95)؛ چرا میانگین‌ها دروغ می‌گویند و تاخیر افراد با اینترنت ضعیف را پنهان می‌کنند.
|
||||||
|
10. **باکس هشدار Quera (`<details class="red">`):** هرگز فایل‌های بزرگ یا استریم‌های ویدیویی را بدون کش روی سرور اصلی پردازش نکنید؛ فشار آنی پردازنده مساوی با قطع سایت خواهد بود.
|
||||||
|
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** تماشای نمودارهای آرام و سبز مصرف منابع پورتفولیو پس از استقرار موفق و پایدار.
|
||||||
|
12. **جمع‌بندی درس‌نامه:** تسلط بر پایش منابع سرور؛ ورود به مبحث حیاتی هشدارهای زنده و سیستم اعلان آپتایم ۲۴ ساعته در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] تمایز میان Monitoring سطحی و Observability عمیق تبیین شود.
|
||||||
|
- [ ] سیگنال‌های چهارگانه طلایی به همراه شاخص‌های آماری نظیر p95 تشریح گردند.
|
||||||
|
- [ ] نحوه خواندن داشبوردهای مصرف منابع در لیارا و ورسل آموزش داده شود.
|
||||||
|
- [ ] مفهوم خطای OOM و روش‌های پیشگیری از نشت حافظه لحاظ گردد.
|
||||||
@@ -0,0 +1,104 @@
|
|||||||
|
# مشخصات درس‌نامه: سامانه‌های پایش آپتایم (Uptime Monitoring) و تنظیم هشدارهای تلگرام و ایمیل با UptimeRobot
|
||||||
|
- **شناسه در سیلابس:** `L13.3`
|
||||||
|
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L13.2` (مشاهده‌پذیری و مانیتورینگ منابع سرور)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** مفهوم پایداری و زمان آنلاین بودن (Uptime Percentage) را شرح دهد و بداند چرا کارفرما هرگز نباید اولین نفری باشد که خرابی سایت را به شما گزارش می‌دهد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** نحوه عملکرد پایش شبیه‌سازی‌شده بیرونی (Synthetic HTTP Health Check) و تفاوت پایش وضعیت HTTP را با پایش کلیدواژه (Keyword Monitoring) تحلیل کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** سرویس رایگان **UptimeRobot** را برای پایش ۲۴ ساعته دامنه پورتفولیو در فواصل زمانی ۵ دقیقه‌ای از دیتاسنترهای مختلف جهان راه‌اندازی کند.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک کانال هشدار فوری در **تلگرام (Telegram Bot)** و ایمیل متصل نماید که در صورت قطعی سرور یا بازگشت به وضعیت آنلاین، در کمتر از یک دقیقه اعلان فوری دریافت کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **قانون طلایی اعتبار مهندسی: باخبر شدن سازنده قبل از بقیه دنیا:**
|
||||||
|
* چرا وقتی یک استخدام‌کننده لینک پورتفولیو را باز می‌کند و با صفحه سفید روبرو می‌شود، فرصت شغلی برای همیشه می‌سوزد؟
|
||||||
|
2. **ریاضیات آپتایم: قانون سه نُه (99.9% Uptime):**
|
||||||
|
* ۹۹.۹٪ به معنای حدود ۸.۷ ساعت قطعی در کل سال است؛ هدف شما پایداری ۹۹.۹۵٪ یا بالاتر است.
|
||||||
|
3. **پایشگرهای سلامت بیرونی (Synthetic Heartbeat Monitoring):**
|
||||||
|
* چرا پایش باید از بیرون سرور انجام شود؟ ربات‌های سراسر دنیا هر ۵ دقیقه یک پینگ HTTPS به سایت شما می‌فرستند.
|
||||||
|
* پایش کدهای وضعیت: کد ۲۰۰ به معنای وضعیت سبز (UP) و هرگونه خطای ۵۰۰، ۵۰۲، ۵۰۳ یا تاخیر طولانی به معنای قطعی (DOWN).
|
||||||
|
* پایش کلیدواژه‌ای (Keyword Check): اطمینان از اینکه متن مشخصی (مثلاً نام شما یا عنوان پورتفولیو) در خروجی هست و صفحه سفید خالی رندر نشده است.
|
||||||
|
4. **راه‌اندازی گام‌به‌گام UptimeRobot (پلن رایگان با ۵۰ مانیتور):**
|
||||||
|
* ثبت نام سریع و زدن دکمه Add New Monitor.
|
||||||
|
* انتخاب نوع HTTPS، وارد کردن دامنه و تنظیم بازه چک ۵ دقیقه‌ای.
|
||||||
|
5. **اتصال کانال‌های اعلام خطر فوری (Alerting Contacts):**
|
||||||
|
* اتصال ایمیل شخصی برای دریافت گزارش‌های قطعی و اتصال مجدد.
|
||||||
|
* اتصال ربات رسمی تلگرام UptimeRobot: عضویت در ربات، دریافت شناسه چت و دریافت پیام‌های آنی قطعی به محض بروز حادثه.
|
||||||
|
6. **ساخت صفحه وضعیت عمومی (Public Status Page):**
|
||||||
|
* ساخت یک صفحه وضعیت شیک با تاریخچه ۹۰ روزه پایداری برای نشان دادن حرفه‌ای‌گری به کارفرمایان و مشتریان.
|
||||||
|
7. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم آلارم کاذب (False Positive)؛ چرا مانیتور باید بعد از ۲ تلاش ناموفق متوالی آلارم بزند تا با نوسانات چندثانیه‌ای اینترنت هشدار اشتباه ندهد.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): دریافت نوتیفیکیشن تلگرام در کمتر از ۶۰ ثانیه بعد از قطعی سرور روی گوشی موبایل.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): پایش روت‌های سنگین دیتابیسی را در بازه‌های ۳۰ ثانیه‌ای نگذارید؛ پینگ‌های سنگین مداوم خودشان باعث کندی سرور می‌شوند!
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- سامانه‌های پیجینگ تلفنی گران‌قیمت شرکتی نظیر PagerDuty یا Opsgenie.
|
||||||
|
- کانفیگ سیستم‌های بررسی پکت‌های خام شبکه ICMP در فایروال‌ها.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Uptime / Downtime | زمان پایداری / زمان قطعی | درصد مدت زمانی که سرویس اینترنتی به درستی در دسترس بوده در مقایسه با زمان از کارافتادگی |
|
||||||
|
| Synthetic Monitoring | پایش ساختگی شبیه‌ساز | ارسال خودکار درخواست‌های دوره‌ای از سرورهای مختلف جهان برای سنجش دسترسی به سایت |
|
||||||
|
| Heartbeat Ping | پالس ضربان قلب | سیگنال دوره‌ای منظم برای اطمینان از زنده بودن و پاسخ‌گویی سرور |
|
||||||
|
| Alerting Channel | کانال اعلام خطر | بستر ارتباطی (تلگرام، پیامک، ایمیل) که اعلان اضطراری قطعی سرور را به مدیر سیستم می‌رساند |
|
||||||
|
| Public Status Page | صفحه وضعیت عمومی | صفحه‌ای شفاف و عمومی که آمار زنده سلامت، پایداری تاریخی و قطعی‌های سیستم را نمایش می‌دهد |
|
||||||
|
| False Positive | زنگ خطر کاذب | اعلام اشتباه قطعی سیستم به دلیل افت موقت شبکه در یک نقطه محلی بدون اینکه سرور واقعاً خاموش باشد |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** زنگ نئونی هشدار دیجیتال در حال مخابره پیام به یک گوشی هوشمند با نماد ربات تلگرام و چراغ سبز فعال سرور.
|
||||||
|
2. **چرخه پایش سلامت و ارسال هشدار:** `images/uptime-monitoring-flow.png`
|
||||||
|
* **موضوع:** فلوچارت: ربات‌های UptimeRobot درخواست می‌فرستند $\rightarrow$ سرور پاسخ نمی‌دهد (خطای ۵۰۲) $\rightarrow$ تست مجدد بعد از ۳۰ ثانیه $\rightarrow$ ارسال پیام هشدار فوری به تلگرام توسعه‌دهنده.
|
||||||
|
3. **تنظیم مانیتور و هشدارهای تلگرام در کنسول UptimeRobot:** `images/uptimerobot-dashboard-setup.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از داشبورد UptimeRobot با فرم ثبت مانیتور جدید، تنظیم اینتروال و تیک زدن تلگرام و ایمیل.
|
||||||
|
4. **نمونه پیام هشدار قطعی و اتصال مجدد در تلگرام:** `images/telegram-alert-message-preview.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از چت‌باکس تلگرام با پیام‌های قرمز «Monitor is DOWN» و پیام سبز بعدی «Monitor is UP».
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# سامانه‌های پایش آپتایم (Uptime Monitoring) و تنظیم هشدارهای تلگرام و ایمیل با UptimeRobot`
|
||||||
|
2. **مقدمه:** اگر ساعت ۴ صبح سایت شما قطع شود، ترجیح می‌دهید ساعت ۹ صبح با صدای اعتراض کارفرما بیدار شوید یا ساعت ۴:۰۱ با اعلان هوشمند در تلگرامتان؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره نگهبان شبانه ۲۴ ساعته:**
|
||||||
|
* سیستم پایشگری که هرگز نمی‌خوابد و هر ۵ دقیقه یک بار سلامت دروازه قلعه شما را چک می‌کند.
|
||||||
|
5. **مفهوم پایداری و در دسترس بودن (Uptime):**
|
||||||
|
* معنی درصدهای ۹۹.۹٪ و تاثیر مستقیم آن بر سئو و اعتماد کاربران.
|
||||||
|
6. **آموزش عملی ثبت مانیتور در UptimeRobot:**
|
||||||
|
* گام‌به‌گام ساخت حساب، انتخاب پروتکل HTTPS، و تعیین فاصله زمانی ۵ دقیقه‌ای.
|
||||||
|
7. **تکنیک پیشرفته: پایش کلیدواژه (Keyword Monitoring):**
|
||||||
|
* چرا گاهی سرور کد ۲۰۰ برمی‌گرداند اما صفحه سفید یا پیام خطاست؟ جستجوی هوشمند کلمات داخل صفحه.
|
||||||
|
8. **اتصال کانال تلگرام برای دریافت اعلان‌های آنی:**
|
||||||
|
* آموزش استارت ربات رسمی تلگرام UptimeRobot و اتصال آن به اکانت کاربری.
|
||||||
|
9. **ساخت صفحه وضعیت عمومی (Status Page) برای پورتفولیو:**
|
||||||
|
* نمایش کارنامه درخشان پایداری و ایجاد حس اعتماد در اولین نگاه کارفرما.
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** جلوگیری از آلارم‌های کاذب؛ تنظیم شرط اعلام قطعی تنها پس از ۲ بار تلاش ناموفق پیاپی.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** مانیتور را روی صفحات سنگین نیازمند لاگین نگذارید؛ همیشه صفحه اصلی یا یک اندپوینت سبک `/api/health` را مانیتور کنید.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** شبیه‌سازی قطعی سرور (توقف موقت در پنل) و شنیدن صدای زنگ هشدار تلگرام در کمتر از ۶۰ ثانیه روی گوشی.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** مجهز شدن به سیستم هشدار سریع؛ ورود به ایستگاه کالبدشکافی خطاهای زنده پروداکشن با سنتری (Sentry) در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] مفهوم آپتایم و چرخه مانیتورینگ بیرونی به روشنی بیان شود.
|
||||||
|
- [ ] راه‌اندازی گام‌به‌گام UptimeRobot به صورت عملی آموزش داده شود.
|
||||||
|
- [ ] نحوه اتصال ربات تلگرام و دریافت اعلان‌های لحظه‌ای در متن لحاظ گردد.
|
||||||
|
- [ ] مفهوم پایش کلیدواژه و صفحه وضعیت عمومی (Status Page) تشریح شود.
|
||||||
@@ -0,0 +1,106 @@
|
|||||||
|
# مشخصات درس‌نامه: ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن با Sentry و کنسول‌های ابری
|
||||||
|
- **شناسه در سیلابس:** `L13.4`
|
||||||
|
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L13.3` (سامانه‌های پایش آپتایم و هشدارهای تلگرام)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** نقطه کور بزرگ محیط پروداکشن را بشناسد؛ جایی که بر خلاف لوکال، هیچ خطای قرمزی روی مانیتور شما چاپ نمی‌شود و کاربران در سکوت با خطا مواجه شده و سایت را ترک می‌کنند.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ساختار سیستم ردگیری خطای حرفه‌ای **Sentry** و تفاوت لاگ‌های ساده کنسول (Server Logs در لیارا/ورسل) را با ثبت عمیق ردپا (Breadcrumbs) و استک‌تریس زنده ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** پکیج `@sentry/nextjs` را در پروژه پورتفولیو راه‌اندازی کرده و خطاهای ثبت‌نشده در کلاینت، سرور و تراکنش‌های زرین‌پال/پیامک را به صورت خودکار به دام بیندازد.
|
||||||
|
- [ ] **ایجاد کند (Create):** یک جریان دیباگ سریع با ایجنت بسازد که با دریافت گزارش تفصیلی خطای سنتری، ریشه باگ پروداکشن را در کمتر از ۱۰ دقیقه شناسایی و پچ امنیتی ارائه دهد.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **نقطه کور پروداکشن: «کاربر چه کرد که این باگ رخ داد؟»:**
|
||||||
|
* کاربر دکمه رزرو مشاوره را می‌زند، صفحه لودینگ گیر می‌کند، کاربر پنجره را می‌بندد و شما هرگز نمی‌فهمید چرا!
|
||||||
|
2. **لایه اول دیدبانی: لاگ‌های زنده سرور ابری (Server Runtime Logs):**
|
||||||
|
* خواندن خروجی‌های استاندارد (`stdout` و `stderr`) در تب لاگ‌های لیارا و پنل ورسل.
|
||||||
|
* تفکیک سطوح لاگ‌نویسی: `INFO`، `WARN` و `ERROR`.
|
||||||
|
3. **لایه دوم دیدبانی: شکارچی باگ‌های زنده با Sentry:**
|
||||||
|
* سنتری چیست؟ پلتفرم استاندارد جهانی برای ثبت، گروه‌بندی و تحلیل باگ‌های نرم‌افزار.
|
||||||
|
* ثبت جزئیات طلایی در هر گزارش خطا:
|
||||||
|
- ردپای دقیق توابع و شماره خط کد (Stack Trace).
|
||||||
|
- مدل دستگاه و سیستم‌عامل کاربر، مرورگر و موقعیت جغرافیایی.
|
||||||
|
- خرده‌نان‌ها یا تاریخچه اقدامات کاربر (Breadcrumbs): مثلاً «کاربر منو را باز کرد $\rightarrow$ روی دکمه کلیک کرد $\rightarrow$ فیلد تلفن را پر کرد $\rightarrow$ خطا رخ داد».
|
||||||
|
4. **راه‌اندازی فوق‌سریع سنتری در Next.js:**
|
||||||
|
* اجرای ویزارد خودکار: `npx @sentry/wizard@latest -i nextjs`.
|
||||||
|
* اضافه شدن فایل‌های کانفیگ کلاینت، سرور و لبه به صورت خودکار توسط ویزارد.
|
||||||
|
* استفاده از `Sentry.captureException(error)` داخل بلوک‌های حساس `try/catch` در Server Actions.
|
||||||
|
5. **روش دیباگ خطای پروداکشن با ترکیب گزارش Sentry و ایجنت هوش مصنوعی:**
|
||||||
|
* کپی کردن گزارش سنتری و پرامپت طلایی برای کشف باگ‌های پنهان داده‌های خاص کاربران.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم حریم خصوصی و فیلتر خودکار دیتای حساس (Data Scrubbing)؛ سنتری به صورت پیش‌فرض رمزها و اطلاعات کارت بانکی را از لاگ‌ها ماسک می‌کند.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): سهمیه رایگان سخاوتمندانه ماهیانه ۵۰۰۰ خطا در پلن توسعه‌دهنده سنتری.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): پاک‌سازی کدهای `console.log("Password:", pass)` قبل از انتشار؛ هرگز اطلاعات محرمانه را در کنسول چاپ نکنید.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- مباحث Enterprise پرفورمنس ردیابی توزیع‌شده چندسروری (Distributed Tracing در مقیاس‌های میلیونی).
|
||||||
|
- نوشتن افزونه‌های اختصاصی C++ برای هسته سنتری.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Error Tracking | ردگیری و تله‌گذاری خطا | پایش، جمع‌آوری و گروه‌بندی خودکار خطاهای کلاینت و سرور به همراه زمینه وقوع حادثه |
|
||||||
|
| Sentry | پلتفرم سنتری | مطرح‌ترین سرویس مانیتورینگ خطا و مشاهده‌پذیری پایداری کد در برنامه‌های وب و موبایل |
|
||||||
|
| Breadcrumbs | ردپاها / خرده‌نان‌های اقدام | سلسله‌مراتب گام‌به‌گام اقداماتی که کاربر پیش از رخ دادن باگ در صفحه انجام داده است |
|
||||||
|
| Unhandled Exception | استثنای مدیریت‌نشده | خطایی غیرمنتظره در کد که در بلوک try/catch مهار نشده و موجب اختلال در اجرای برنامه می‌شود |
|
||||||
|
| Data Scrubbing | پاک‌سازی خودکار دیتای حساس | فیلتر کردن رمزهای عبور، شماره کارت و اطلاعات هویتی از گزارش‌های خطا برای حفظ حریم خصوصی |
|
||||||
|
| Structured Logging | لاگ‌نویسی ساختاریافته | ثبت پیام‌های سیستمی با فرمت منظم (مانند JSON) به همراه زمان دقیق و سطح اهمیت پیام |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** اسکنر تله‌گذار باگ با لوگوی سنتری که خطاهای مخفی کدهای زنده وب را به دام انداخته و در یک داشبورد شفاف نمایش می‌دهد.
|
||||||
|
2. **داشبورد بررسی لاگ‌های زنده در کنسول لیارا:** `images/liara-app-runtime-logs.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از تب «لاگ‌ها» در پنل لیارا با پیام‌های رنگی درخواست‌های HTTP و خطاهای سرور.
|
||||||
|
3. **کالبدشکافی یک گزارش خطا در پنل Sentry:** `images/sentry-issue-details-anatomy.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از صفحه یک خطا در سنتری با بخش‌های هایلایت‌شده: استک‌تریس، نام فایل، مشخصات سیستم کاربر و بخش Breadcrumbs.
|
||||||
|
4. **چرخه حل باگ پروداکشن با هوش مصنوعی:** `images/sentry-ai-debugging-loop.png`
|
||||||
|
* **موضوع:** اینفوگرافیک: وقوع خطا در مرورگر کاربر $\rightarrow$ ثبت در سنتری $\rightarrow$ کپی خلاصه گزارش به ایجنت $\rightarrow$ تولید پچ اصلاحی $\rightarrow$ استقرار سریع.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن با Sentry و کنسول‌های ابری`
|
||||||
|
2. **مقدمه:** وقتی کاربری در آن سوی دنیا با یک باگ مواجه می‌شود و بدون یک کلمه اعتراض سایت را می‌بندد، چگونه باگ او را در کسری از ثانیه روی مانیتور خود ببینیم؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره جعبه سیاه هواپیما:**
|
||||||
|
* ثبت تک‌تک حرکات خلبان و شرایط جوی تا در صورت بروز هر سانحه، علت ریشه‌ای بلافاصله مشخص شود.
|
||||||
|
5. **پایش لایه اول: خواندن لاگ‌های سرور در لیارا و Vercel:**
|
||||||
|
* چطور لاگ‌های زنده ترمینال سرور را روی مرورگر رصد کنیم و سطوح لاگ‌ها را تفکیک نماییم.
|
||||||
|
6. **پایش لایه دوم: نصب و راه‌اندازی شکاری باگ‌های سنتری (Sentry):**
|
||||||
|
* ساخت پروژه در sentry.io و اجرای ویزارد خودکار Next.js در ترمینال.
|
||||||
|
7. **کالبدشکافی گزارش باگ در سنتری: قدرت شگفت‌انگیز Breadcrumbs:**
|
||||||
|
* دیدن گام‌های کاربر ثانیه‌هایی قبل از وقوع خطا (کلیک‌ها، ورودی‌ها، روت‌ها).
|
||||||
|
8. **به‌دام‌اندازی خطاهای پنهان در توابع حساس پورتفولیو:**
|
||||||
|
* ایمن‌سازی روت‌های پرداخت زرین‌پال، ارسال پیامک و چت‌بات با `Sentry.captureException`.
|
||||||
|
9. **جعبه پرامپت طلایی: تحلیل گزارش خطای سنتری توسط ایجنت:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من این گزارش خطا را از سنتری پروداکشن دریافت کرده‌ام: [کپی استک‌تریس و بردکرامب‌ها]. لطفاً ۱) علت بروز خطا را توضیح بده، ۲) مشخص کن این باگ تحت چه سناریوی نادری رخ داده است، و ۳) کد اصلاحی تاب‌آور (Defensive) به همراه تست اعتبارسنجی ارائه بده.»
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** ماجرای امنیت و حریم خصوصی داده‌ها در سنتری؛ خیالتان راحت باشد، توکن‌ها و اطلاعات کارت به صورت خودکار ستاره‌دار (`[Filtered]`) می‌شوند.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** لاگ‌های اضافه و حجیم در پروداکشن ننویسید؛ چاپ بیهوده هزاران خط در هر ثانیه به هدررفت منابع و هزینه سرور می‌انجامد.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** ایجاد یک خطای عمدی آزمایشی در سایت و مشاهده ظاهر شدن آن در داشبورد سنتری در کمتر از ۳ ثانیه.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تجهیز کامل سیستم به جعبه سیاه عیب‌یابی؛ ورود به مبحث به‌روزرسانی‌های امنیتی و ارتقای دوره‌ای پکیج‌ها در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] نقطه کور پروداکشن و ضرورت ثبت لاگ‌ها و ردگیری خطاها به روشنی تبیین شود.
|
||||||
|
- [ ] تفاوت میان لاگ‌های سرور (لیارا/ورسل) با سرویس‌های Error Tracking (سنتری) تشریح گردد.
|
||||||
|
- [ ] راه‌اندازی گام‌به‌گام سنتری در Next.js به همراه مفاهیم Breadcrumbs آموزش داده شود.
|
||||||
|
- [ ] پرامپت دیباگ خطای پروداکشن با استفاده از لاگ‌های سنتری ارائه شود.
|
||||||
@@ -0,0 +1,127 @@
|
|||||||
|
# مشخصات درس‌نامه: به‌روزرسانی‌های امنیتی دوره‌ای و ارتقای ایمن وابستگی‌ها (SemVer & Updates)
|
||||||
|
- **شناسه در سیلابس:** `L13.5`
|
||||||
|
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۶ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L13.4` (ثبت لاگ‌ها و ردگیری هوشمند خطاهای پروداکشن)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** پدیده «پوسیدگی نرم‌افزار» (Software Rot) را تحلیل کرده و بداند چرا کدی که امروز کاملاً سالم است، شش ماه دیگر به دلیل کشف آسیب‌پذیری‌های امنیتی جدید (CVEs) نیازمند مراقبت و ارتقاست.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ساختار سیستم نسخه‌بندی معنایی (Semantic Versioning - SemVer) شامل تفاوت‌های حیاتی Major، Minor و Patch را بشناسد و تفاوت نمادهای `^` و `~` در `package.json` را ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** یک رویه ۴ مرحله‌ای ایمن برای به‌روزرسانی وابستگی‌ها (بررسی با `npm outdated` $\rightarrow$ ایجاد شاخه گیت اختصاصی $\rightarrow$ آپدیت با `npm update` $\rightarrow$ راستی‌آزمایی با `npm run build`) اجرا نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** ربات هشدارهای امنیتی گیت‌هاب (GitHub Dependabot) را برای دریافت خودکار درخواست‌های ادغام (PR) اصلاحی آسیب‌پذیری‌های بحرانی فعال کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **استعاره سرویس دوره‌ای خودرو و تعویض روغن:**
|
||||||
|
* خودرویی که در پارکینگ پارک شده هم روغن فاسد می‌کند؛ نرم‌افزاری که دست نخورده هم به مرور زمان مشمول کشف رخنه‌های امنیتی جهانی می‌شود.
|
||||||
|
2. **رمزگشایی از نگارش معنایی (Semantic Versioning - SemVer):**
|
||||||
|
* ساختار سه‌گانه `MAJOR.MINOR.PATCH` (مثلاً نسخه `15.2.1`):
|
||||||
|
- پچ (Patch): رفع باگ‌ها و آسیب‌پذیری‌های امنیتی؛ بدون هیچ تغییر در کارکرد قبلی (کاملاً امن برای آپدیت).
|
||||||
|
- ماینور (Minor): اضافه شدن قابلیت‌های جدید با حفظ سازگاری با کدهای قبلی (Backward Compatible).
|
||||||
|
- میجر (Major): تغییرات بنیادین و شکننده (Breaking Changes) که ممکن است کدهای فعلی را بشکند و نیازمند بررسی دقیق مستندات است.
|
||||||
|
* تفاوت عملگر کلاهک (`^`) و مد (`~`) در قفل کردن نسخه‌ها در `package.json`.
|
||||||
|
3. **رویه استاندارد ۴ مرحله‌ای ارتقای بسته‌ها بدون خرابی پروژه:**
|
||||||
|
* گام ۱: رصد وضعیت پکیج‌ها با دستور `npm outdated`.
|
||||||
|
* گام ۲: ساخت برنچ مجزا در گیت (`git checkout -b chore/update-deps`) برای جلوگیری از خرابی شاخه اصلی.
|
||||||
|
* گام ۳: اجرای `npm update` برای دریافت آخرین پچ‌ها و ماینورهای سازگار.
|
||||||
|
* گام ۴: اجرای `npm run build` و تست‌های خودکار برای تایید سلامت کامل و ادغام در شاخه `main`.
|
||||||
|
4. **ابزار تعاملی ارتقای نسخه‌های ماژور (`npm-check-updates`):**
|
||||||
|
* نحوه استفاده از `npx npm-check-updates -i` برای انتخاب آگاهانه پکیج‌هایی که می‌خواهیم به نسخه جدیدتر ببریم.
|
||||||
|
5. **فعال‌سازی هوشمند Dependabot در مخزن گیت‌هاب:**
|
||||||
|
* دریافت ایمیل‌های هشدار خودکار در صورت کشف باگ‌های امنیتی بحرانی در کتابخانه‌ها و امکان مرج با یک کلیک.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم Breaking Changes در آپدیت‌های ماژور (نظیر جهش از Next.js 14 به 15) و چرایی لزوم خواندن راهنمای رسمی ارتقا (Migration Guide).
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): آرامش خاطر با به‌روزرسانی‌های ماهانه ۱۵ دقیقه‌ای که مانع از انباشت بدهی فنی (Technical Debt) می‌شود.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): هرگز آپدیت‌های ماژور را بدون داشتن کامیت ذخیره و در شب پیش از ارائه به کارفرما انجام ندهید!
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- بازنویسی کامل معماری کدها در اثر تغییر پارادایم‌های بنیادین فریم‌ورک‌ها.
|
||||||
|
- انتشار دستی بسته‌های شخصی در رجیستری جهانی npm.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Software Rot | پوسیدگی نرم‌افزار | فرسودگی تدریجی نرم‌افزار به دلیل منسوخ شدن کتابخانه‌ها و کشف آسیب‌پذیری‌های امنیتی جدید |
|
||||||
|
| Semantic Versioning (SemVer) | نسخه‌بندی معنایی | سیستم استاندارد جهانی شماره‌گذاری نسخه‌ها به صورت MAJOR.MINOR.PATCH برای بیان ماهیت تغییرات |
|
||||||
|
| Breaking Change | تغییر شکننده ناسازگار | تغییری در نسخه جدید یک کتابخانه که نیازمند بازنویسی بخش‌هایی از کدهای استفاده‌کننده است |
|
||||||
|
| Dependabot | بات امنیتی دیپندابات | ربات خودکار گیت‌هاب برای اسکن وابستگی‌ها و ایجاد پول ریکوئست‌های خودکار ارتقای امنیتی |
|
||||||
|
| Technical Debt | بدهی فنی | هزینه و زحمت پنهان ناشی از تعویق انداختن نگهداری، بازنویسی و به‌روزرسانی کدهای سیستم |
|
||||||
|
| CVE (Common Vulnerabilities) | پایگاه جهانی آسیب‌پذیری‌ها | شناسه عمومی و استاندارد بین‌المللی برای گزارش رخنه‌های امنیتی کشف‌شده در نرم‌افزارها |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** جعبه دنده‌های نئونی دیجیتال که به آرامی در حال تعویض و روغن‌کاری هستند و قطعات قدیمی با قطعات نو و درخشان جایگزین می‌شوند.
|
||||||
|
2. **کالبدشکافی اعداد نسخه‌بندی معنایی (SemVer):** `images/semver-breakdown-anatomy.png`
|
||||||
|
* **موضوع:** اینفوگرافیک توضیحی: نمایش عدد ۱۵.۲.۱ با فلش‌های رنگی روی Major (شکننده)، Minor (فیچر جدید)، و Patch (رفع باگ امنیتی).
|
||||||
|
3. **خروجی دستور `npm outdated` در ترمینال:** `images/npm-outdated-terminal-screen.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از جدول رنگی ترمینال با ستون‌های Package، Current، Wanted و Latest.
|
||||||
|
4. **درخواست ادغام خودکار امنیتی Dependabot در گیت‌هاب:** `images/github-dependabot-pr-preview.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از یک Pull Request خودکار در گیت‌هاب با تگ سبز «Security Update: bump library version to fix CVE».
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# به‌روزرسانی‌های امنیتی دوره‌ای و ارتقای ایمن وابستگی‌ها (SemVer & Updates)`
|
||||||
|
2. **مقدمه:** چرا کدی که امروز بی‌نقص کار می‌کند، اگر به حال خود رها شود سال آینده به لانه زنبور رخنه‌های امنیتی تبدیل خواهد شد؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **پدیده پوسیدگی نرم‌افزار (Software Rot):**
|
||||||
|
* جهان اطراف کد شما در حال حرکت است؛ مرورگرها آپدیت می‌شوند و هکرها رخنه‌های جدید کشف می‌کنند.
|
||||||
|
5. **زبان بین‌المللی نسخه‌ها: SemVer را مثل یک حرفه‌ای بخوانید:**
|
||||||
|
* تفاوت Patch (بدون دردسر)، Minor (امکانات نو)، و Major (احتیاط، زمین لغزنده است!).
|
||||||
|
* نمادهای `^` و `~` در `package.json` چه دستوری به npm می‌دهند؟
|
||||||
|
6. **پروتکل ۴ گانه به‌روزرسانی بدون خرابکاری در پورتفولیو:**
|
||||||
|
* گام ۱: بازرسی وضعیت با `npm outdated`.
|
||||||
|
* گام ۲: باز کردن یک برنچ امن در گیت.
|
||||||
|
* گام ۳: اجرای `npm update`.
|
||||||
|
* گام ۴: راستی‌آزمایی با تست بیلد محلی `npm run build`.
|
||||||
|
7. **استفاده از ابزار شیک `npm-check-updates` برای ارتقای هدفمند:**
|
||||||
|
* انتخاب گرافیکی بسته‌ها در ترمینال و مشاهده پیش‌نمایش نسخه‌های جدید.
|
||||||
|
8. **فعال‌سازی نگهبان خودکار گیت‌هاب (Dependabot):**
|
||||||
|
* سپردن رصد ۲۴ ساعته آسیب‌پذیری‌های روز دنیا به ربات‌های گیت‌هاب.
|
||||||
|
9. **دستورات چندسکویی برای بررسی و آپدیت وابستگی‌ها:**
|
||||||
|
* منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
|
||||||
|
- Windows (PowerShell):
|
||||||
|
```powershell
|
||||||
|
npm outdated
|
||||||
|
npm update
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
- macOS (Terminal):
|
||||||
|
```bash
|
||||||
|
npm outdated
|
||||||
|
npm update
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
- Linux (Bash):
|
||||||
|
```bash
|
||||||
|
npm outdated
|
||||||
|
npm update
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** اهمیت مطالعه فایل CHANGELOG یا Releases در گیت‌هاب کتابخانه قبل از آپدیت‌های بزرگ ماژور.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** هرگز همه پکیج‌ها را به یکباره و بدون تست با دستورات فورس آپدیت نکنید؛ یک ناسازگاری کوچک می‌تواند ساعت‌ها وقت شما را برای ریکاوری تلف کند.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** پورتفولیویی که همیشه تمیز، مدرن و مجهز به آخرین پچ‌های امنیتی روز دنیاست.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر نگهداری زیرساختی؛ ورود به مبحث رشد و دیده شدن: سئو تکنیکال و تحلیل رفتار کاربر در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] پدیده فرسودگی نرم‌افزار و ضرورت به‌روزرسانی‌های مستمر تشریح شود.
|
||||||
|
- [ ] ساختار نسخه‌بندی معنایی (SemVer) و علائم `^` و `~` به روشنی آموزش داده شود.
|
||||||
|
- [ ] پروتکل ۴ مرحله‌ای ایمن ارتقای وابستگی‌ها به همراه دستورات چندسکویی ارائه گردد.
|
||||||
|
- [ ] شیوه فعال‌سازی و کاربرد Dependabot در مخزن گیت‌هاب تشریح شود.
|
||||||
@@ -0,0 +1,107 @@
|
|||||||
|
# مشخصات درس‌نامه: سئو تکنیکال (Google Search Console) و تحلیل رفتار کاربر با Microsoft Clarity
|
||||||
|
- **شناسه در سیلابس:** `L13.6`
|
||||||
|
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L13.5` (به‌روزرسانی‌های امنیتی دوره‌ای)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** تفاوت میان جذب ترافیک از موتورهای جستجو با سئو تکنیکال (Technical SEO) و درک تعاملات عمیق کاربران با ابزارهای تحلیل رفتار (Behavioral Analytics) را شرح دهد.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** نقشه سایت خودکار (`sitemap.ts`)، فایل هدایت خزنده‌ها (`robots.ts`)، و ساختار داده‌های معنایی JSON-LD را برای رتبه‌بندی نام و تخصص خود در نتایج جستجوی گوگل ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** دامنه پورتفولیو را در **Google Search Console** ثبت و اعتبارسنجی کرده و نقشه سایت داینامیک پروژه‌ها را به گوگل معرفی نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** سرویس **Microsoft Clarity** را برای ضبط ویدیویی نشست‌های کاربری (Session Replay)، تحلیل نقشه‌های حرارتی (Heatmaps) و کشف کلیک‌های خشمگینانه (Rage Clicks) روی پورتفولیو راه‌اندازی کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **دو نیمه موفقیت محصول پس از انتشار: کشف شدن توسط گوگل + درک رفتار انسان‌ها:**
|
||||||
|
* داشتن بهترین پورتفولیو بدون سئو مثل باز کردن یک مغازه لوکس در کوچه بن‌بست یک بیابان است!
|
||||||
|
2. **سئو تکنیکال خودکار در Next.js مدرن:**
|
||||||
|
* ساخت خودکار نقشه سایت در `app/sitemap.ts`: استخراج داینامیک اسلاگ پروژه‌ها از Supabase و تولید `sitemap.xml`.
|
||||||
|
* ساخت فایل هدایت خزنده‌ها در `app/robots.ts`: اجازه ورود به صفحات عمومی و مسدودسازی خزنده‌ها از ورود به مسیرهای ادمین (`/admin/*`).
|
||||||
|
* ساخت داده‌های ساختاریافته معنایی (Schema.org JSON-LD): معرفی خودتان به عنوان یک `Person` متخصص، مهارت‌ها و لینک‌های شبکه‌های اجتماعی برای نمایش ریچ‌اسنیپت اختصاصی در گوگل.
|
||||||
|
3. **ثبت رسمی در Google Search Console (GSC):**
|
||||||
|
* اعتبارسنجی مالکیت با رکورد DNS TXT یا تگ متا.
|
||||||
|
* ارسال نقشه سایت (`/sitemap.xml`) برای ایندکس سریع صفحات.
|
||||||
|
* تحلیل کوئری‌های جستجو (Search Queries): کارفرمایان با چه کلماتی به سایت شما رسیده‌اند؟
|
||||||
|
4. **تحلیل رفتار کاربر با مایکروسافت کلاریتی (Microsoft Clarity):**
|
||||||
|
* چرا کلاریتی؟ ۱۰۰٪ رایگان، بدون سقف ترافیک، و رعایت کامل حریم خصوصی.
|
||||||
|
* بازپخش نشست‌ها (Session Replay): تماشای ناشناس حرکت ماوس و اسکرول کارفرما درست شبیه تماشای یک فیلم ویدیویی.
|
||||||
|
* نقشه‌های حرارتی (Heatmaps): نقاط داغ کلیک و عمق اسکرول (Scroll Depth)؛ آیا کارفرمایان به بخش فرم تماس در انتهای صفحه می‌رسند؟
|
||||||
|
* کشف کلیک‌های خشمگینانه (Rage Clicks) و کلیک‌های مرده (Dead Clicks): جاهایی که کاربر فکر می‌کند لینکی وجود دارد و مکرراً کلیک می‌کند!
|
||||||
|
5. **نصب اسکریپت کلاریتی در `app/layout.tsx`:**
|
||||||
|
* نحوه الصاق تمیز اسکریپت با کامپوننت `next/script` بدون افت نمره لایت‌هاوس.
|
||||||
|
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): مفهوم کلیک‌های خشمگینانه (Rage Clicks) و چگونه این شاخص به شما نشان می‌دهد کدام دکمه یا کارت در سایت گمراه‌کننده است.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): مشاهده اولین ویدیوی گشت‌وگذار یک بازدیدکننده در پورتفولیو و حس شگفت‌انگیز درک رفتار کاربر واقعی.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): مسدود کردن مسیرهای `/admin` در `robots.txt`؛ هرگز اجازه ندهید صفحات لاگین مدیریت شما در نتایج جستجوی گوگل لیست شوند.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- مباحث پیچیده تبلیغات کلیکی گوگل ادز (Google Ads).
|
||||||
|
- کمپین‌های بک‌لینک‌سازی کلاه‌سیاه و خرید رپورتاژهای انبوه.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| Technical SEO | سئوی تکنیکال | بهینه‌سازی فنی زیرساخت سایت، سرعت، کدها و متادیتاها جهت خوانایی حداکثری برای موتورهای جستجو |
|
||||||
|
| Sitemap.xml | نقشه سایت اینترنتی | سندی استاندارد حاوی فهرست تمام آدرس‌های فعال سایت برای تسهیل خزش و ایندکس توسط گوگل |
|
||||||
|
| Robots.txt | فایل هدایت خزنده‌ها | فایل متنی در ریشه سایت که مشخص می‌کند خزنده‌های وب مجاز به بررسی کدام صفحات هستند و از کدام باید دور بمانند |
|
||||||
|
| JSON-LD Schema | داده‌های ساختاریافته معنایی | قالب استاندارد افزودن اطلاعات مفهومی به کدها برای تولید نتایج غنی (Rich Snippets) در جستجو |
|
||||||
|
| Session Replay | بازپخش نشست کاربری | شبیه‌سازی ویدیویی کامل نحوه تعامل، کلیک‌ها و اسکرول بازدیدکننده در طول زمان حضور در سایت |
|
||||||
|
| Rage Clicks | کلیک‌های خشمگینانه | کلیک‌های پیاپی و سریع کاربر روی یک نقطه که نشان‌دهنده ناکامی و کار نکردن یک المان ظاهری است |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** ربات خزنده گوگل با ذره‌بین درخشان در کنار نقشه حرارتی نئونی پر از لکه‌های قرمز و زرد کلیک کاربران روی صفحات سایت.
|
||||||
|
2. **داشبورد عملکرد در Google Search Console:** `images/google-search-console-performance.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از پنل سرچ کنسول گوگل با نمودارهای Total Clicks، Total Impressions و کلمات کلیدی ورودی.
|
||||||
|
3. **نمای بازپخش نشست ویدیویی در Microsoft Clarity:** `images/clarity-session-replay-screen.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از پلیر کلاریتی با نمایش ردپای ماوس کاربر روی کارت پروژه‌ها و تایم‌لاین رویدادها.
|
||||||
|
4. **نقشه حرارتی کلیک‌ها (Heatmap) در پورتفولیو:** `images/clarity-heatmap-preview.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از صفحه پورتفولیو با لکه‌های حرارتی قرمز روی دکمه‌های «مشاهده پروژه» و «رزرو مشاوره».
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# سئو تکنیکال (Google Search Console) و تحلیل رفتار کاربر با Microsoft Clarity`
|
||||||
|
2. **مقدمه:** چگونه کاری کنیم که هم ربات‌های گوگل عاشق ساختار سایت ما شوند و هم پشت صحنه ببینیم کاربران چگونه با پروژه‌های ما زندگی می‌کنند؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره تابلوهای راهنما و دوربین‌های مداربسته فروشگاه:**
|
||||||
|
* سئو تابلوهای هدایت مشتری از اتوبان است؛ کلاریتی دوربین‌های داخل فروشگاه برای فهمیدن اینکه مشتری جلوی کدام قفسه مکث کرده است.
|
||||||
|
5. **سئوی تکنیکال با ساخت فایل‌های جادویی Next.js:**
|
||||||
|
* کدنویسی `app/sitemap.ts` به صورت پویا با خواندن اسلاگ پروژه‌ها از Supabase.
|
||||||
|
* کدنویسی `app/robots.ts` برای محافظت از روت‌های مدیریت.
|
||||||
|
6. **تزریق هویت معنایی با JSON-LD Schema:**
|
||||||
|
* ساخت قطعه کد اسکیما در `layout.tsx` برای معرفی برند شخصی به خزنده‌های گوگل.
|
||||||
|
7. **ثبت دامنه در Google Search Console:**
|
||||||
|
* اعتبارسنجی دامنه و ارسال سیت‌مپ و درخواست ایندکس سریع اولین صفحات.
|
||||||
|
8. **راه‌اندازی جادوی مایکروسافت کلاریتی (Microsoft Clarity):**
|
||||||
|
* ثبت نام رایگان و دریافت کد رهگیری اختصاصی پروژه.
|
||||||
|
* افزودن امن اسکریپت کلاریتی به `app/layout.tsx` با کامپوننت `next/script`.
|
||||||
|
9. **تحلیل شاهکارهای کلاریتی: تماشای فیلم و کشف کلیک‌های خشمگینانه:**
|
||||||
|
* چگونه با دیدن ۱۰ ویدیوی اول، نقاط ضعف چیدمان و دکمه‌های گیج‌کننده پورتفولیو را بازطراحی کنیم.
|
||||||
|
10. **باکس نکته Quera (`<details class="violet">`):** اهمیت داده‌های Rage Clicks؛ کشف المان‌هایی که شبیه لینک طراحی شده‌اند اما کار نمی‌کنند و اصلاح فوری آن‌ها.
|
||||||
|
11. **باکس هشدار Quera (`<details class="red">`):** مسدود کردن صفحات پنل مدیریت در `robots.txt`؛ امنیت و حریم خصوصی پنل ادمین با سئو مخدوش نشود.
|
||||||
|
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** دیدن اولین نتایج سرچ کنسول و تماشای حرکات زنده بازدیدکنندگان روی دکمه رزرو و دانلود رزومه.
|
||||||
|
13. **جمع‌بندی درس‌نامه:** تسلط بر دیدبانی رفتار و سئو؛ ورود به آخرین درس این فصل: مستندسازی فاخر و راهنمای نگهداری پروژه در درس بعدی.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] اصول سئو تکنیکال مدرن (sitemap.ts, robots.ts, JSON-LD) با کدهای استاندارد پیاده شود.
|
||||||
|
- [ ] مراحل ثبت سایت و ارسال نقشه سایت در Google Search Console تشریح گردد.
|
||||||
|
- [ ] راه‌اندازی و کاربرد Microsoft Clarity (Session Replays, Heatmaps, Rage Clicks) آموزش داده شود.
|
||||||
|
- [ ] کدهای ادغام اسکریپت با استفاده از کامپوننت بهینه‌ساز Next.js ارائه گردد.
|
||||||
@@ -0,0 +1,101 @@
|
|||||||
|
# مشخصات درس‌نامه: مستندسازی فاخر، شناسنامه مخزن (README.md) و کتابچه راهنمای نگهداری (Runbooks)
|
||||||
|
- **شناسه در سیلابس:** `L13.7`
|
||||||
|
- **فصل:** فصل ۱۳: نگهداری محصول (Ch 13)
|
||||||
|
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||||||
|
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||||||
|
- **پیش‌نیازهای مستقیم:** `L13.6` (سئو تکنیکال و تحلیل رفتار کاربر)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||||||
|
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||||||
|
- [ ] **درک کند (Understand):** چرا کدی که مستندات نداشته باشد یک معماست نه یک محصول، و چگونه یک صفحه گیت‌هاب حرفه‌ای با `README.md` فاخر، اولین ویترین قضاوت مهندسی کارفرمایان و مدیران فنی است.
|
||||||
|
- [ ] **تحلیل/ارزیابی کند (Evaluate):** ۶ بخش طلایی یک سند مستندات استاندارد (عنوان و بج‌های وضعیت، اسکرین‌شات‌ها، معماری سیستم، راهنمای راه‌اندازی محلی، پیکربندی متغیرها، و لایسنس) را ارزیابی کند.
|
||||||
|
- [ ] **به‌کار ببندد (Apply):** کتابچه‌های عملیاتی راهنمای بحران (Operational Runbooks) را برای سناریوهای اضطراری (نظیر اتمام شارژ پیامک، بازیابی پشتیبان دیتابیس، و تعویض کلیدها) تدوین نماید.
|
||||||
|
- [ ] **ایجاد کند (Create):** با هدایت ایجنت‌های هوش مصنوعی، مستندات کامل پروژه پورتفولیو را به همراه دیاگرام‌های Mermaid آماده رندر در گیت‌هاب تولید و منتشر کند.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||||||
|
|
||||||
|
### آنچه باید پوشش داده شود (In-Scope):
|
||||||
|
1. **داستان دو پروژه یکسان با دو سرنوشت متفاوت:**
|
||||||
|
* پروژه‌ای عالی بدون داکیومنت که در گیت‌هاب خاک می‌خورد در برابر پروژه‌ای با بج‌های شکیل و داکیومنت جذاب که صدها ستاره می‌گیرد و مصاحبه‌کنندگان را مجذوب می‌کند.
|
||||||
|
2. **ارکان ۶ گانه یک `README.md` در سطح استاندارد جهانی:**
|
||||||
|
* ۱. بخش هدر: عنوان، شعار تک‌خطی جذاب، بج‌های شیلدز (Shields.io: نسخه Next.js، لایسنس MIT، وضعیت استقرار).
|
||||||
|
* ۲. پیش‌نمایش بصری: اسکرین‌شات‌های باکیفیت یا تصاویر متحرک گیف از محیط لایو و پنل مدیریت.
|
||||||
|
* ۳. جعبه ابزار و پشته فناوری (Tech Stack): معرفی شفاف Next.js, Supabase, Tailwind, Kavenegar, Zarinpal, Sentry.
|
||||||
|
* ۴. معماری سیستم و نمودار جریان داده با فرمت Mermaid (رندر مستقیم داخل گیت‌هاب).
|
||||||
|
* ۵. راهنمای راه‌اندازی سریع گام‌به‌گام (Quickstart): کلون کردن، نصب پکیج‌ها، ساخت فایل `.env` و دستور ران.
|
||||||
|
* ۶. راهنمای استقرار، مشارکت (Contributing) و لایسنس.
|
||||||
|
3. **کتابچه راهنمای واکنش به بحران (Operational Runbooks / Playbooks):**
|
||||||
|
* سناریوی ۱: اگر پیامک‌ها نرسید چه کنیم؟ (چک کردن شارژ کاوه‌نگار و لاگ‌های وب‌سرویس).
|
||||||
|
* سناریوی ۲: نحوه دریافت نسخه پشتیبان اضطراری از جداول دیتابیس در کنسول Supabase.
|
||||||
|
* سناریوی ۳: چرخه تعویض کلیدهای فاش‌شده بدون خاموش کردن سایت.
|
||||||
|
4. **تکنیک تولید و به‌روزرسانی مستندات با ایجنت‌های هوش مصنوعی:**
|
||||||
|
* خوراندن ساختار فایل‌ها (`tree`) و `package.json` به ایجنت و دریافت داکیومنت ساختاریافته.
|
||||||
|
5. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||||||
|
* کال‌اوت بنفش (`<details class="violet">`): قابلیت رندر مستقیم دیاگرام‌های Mermaid در ریپازیتوری‌های گیت‌هاب بدون نیاز به تصویر خارجی.
|
||||||
|
* کال‌اوت سبز (`<details class="green">`): استفاده از بج‌های رنگی Shields.io برای ایجاد حس محصولات متن‌باز سطح یک سیلیکون‌ولی.
|
||||||
|
* کال‌اوت قرمز (`<details class="red">`): هرگز مقادیر واقعی کلیدهای اختصاصی را داخل مثال‌های `README.md` کپی نکنید؛ همیشه از مقادیر فرضی استفاده نمایید.
|
||||||
|
|
||||||
|
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||||||
|
- راه‌اندازی پورتال‌های مستندات بزرگ شرکتی مثل Docusaurus یا GitBook.
|
||||||
|
- تولید مستندات اتوماتیک API با ابزارهای Swagger/OpenAPI در سطح کدهای بک‌اند پیچیده.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||||||
|
|
||||||
|
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| README.md | سند معرفی و راهنمای مخزن | فایل ورودی اصلی هر پروژه نرم‌افزاری که هویت، ویژگی‌ها و شیوه اجرای آن را معرفی می‌کند |
|
||||||
|
| Runbook / Playbook | کتابچه عملیاتی راهنمای بحران | دستورالعمل گام‌به‌گام مدون برای نگهداری دوره‌ای و واکنش سریع به حوادث و خطاهای سیستم |
|
||||||
|
| Shields.io Badges | نشان‌ها و بج‌های وضعیت | برچسب‌های گرافیکی متنی کوچک برای نمایش وضعیت بیلد، پلتفرم‌ها و نسخه‌ها در بالای مستندات |
|
||||||
|
| Quickstart Guide | راهنمای راه‌اندازی سریع | خلاصه دستورات ترمینالی ضروری برای اجرای پروژه در ۵ دقیقه توسط فرد تازه وارد |
|
||||||
|
| Mermaid in Markdown | نمودارهای درون‌خطی مرمید | رسم فلوچارت‌ها و ساختارهای گرافیکی با کدهای متنی ساده که مستقیماً در گیت‌هاب رندر می‌شوند |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||||
|
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||||||
|
|
||||||
|
1. **تصویر کاور درس:** `images/cover.png`
|
||||||
|
* **موضوع:** کتابچه بازشده نئونی مدرن با کدهای درخشان، برچسب‌های رنگارنگ و نماد تیک سبز استاندارد جهانی روی مانیتور گیت‌هاب.
|
||||||
|
2. **کالبدشکافی یک سند README فاخر در گیت‌هاب:** `images/readme-anatomy-infographic.png`
|
||||||
|
* **موضوع:** اسکرین‌شات از صفحه مخزن گیت‌هاب با کادرهای نئونی دور بج‌ها، اسکرین‌شات سایت، جدول فیچرها، دیاگرام معماری و بخش Quickstart.
|
||||||
|
3. **نمودار معماری رندر شده با Mermaid در گیت‌هاب:** `images/github-mermaid-architecture-render.png`
|
||||||
|
* **موضوع:** نمایش تصویری فلوچارت سیستم پورتفولیو که مستقیماً از کدهای متنی Markdown در گیت‌هاب رندر شده است.
|
||||||
|
4. **نمونه برگ کتابچه واکنش به بحران (Runbook Card):** `images/operational-runbook-card-preview.png`
|
||||||
|
* **موضوع:** کارت مستند راهنمای بحران با عنوان «در صورت اتمام شارژ پیامک چه کنیم؟» با مراحل ۳ گانه ترتیبی و چک‌لیست سریع.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||||||
|
|
||||||
|
1. **تیتر اصلی:** `# مستندسازی فاخر، شناسنامه مخزن (README.md) و کتابچه راهنمای نگهداری (Runbooks)`
|
||||||
|
2. **مقدمه:** چرا یک مدیر فنی قبل از اینکه کدهای شما را ببیند، به `README.md` پروژه نگاه می‌کند و چطور در همان ثانیه اول او را شگفت‌زده کنیم؟
|
||||||
|
3. **جدول کاور درس**
|
||||||
|
4. **استعاره تابلوی ورودی و بروشور راهنمای موزه:**
|
||||||
|
* بدون راهنما، اشیای عتیقه فقط تکه‌های خاک‌خورده سنگ به نظر می‌رسند؛ مستندات ارزش کار شما را هویدا می‌کند.
|
||||||
|
5. **آناتومی ۶ ستون یک README در کلاس جهانی:**
|
||||||
|
* نشان‌های شیک Shields.io، پیش‌نمایش‌های بصری، جدول استک، دیاگرام معماری، و بخش راه‌اندازی سریع.
|
||||||
|
6. **رسم جادویی دیاگرام‌های معماری با کدهای Mermaid:**
|
||||||
|
* چرا نباید دیاگرام را با عکس‌های سنگین بگذاریم؟ نوشتن کدهای تمیز فلوچارت که در گیت‌هاب رندر می‌شوند.
|
||||||
|
7. **تدوین کتابچه‌های واکنش اضطراری به بحران (Operational Runbooks):**
|
||||||
|
* ۳ سناریوی بحرانی در پروژه پورتفولیو و دستورالعمل مهار آن‌ها.
|
||||||
|
8. **جعبه پرامپت طلایی: ساخت شناسنامه کامل پروژه با ایجنت هوش مصنوعی:**
|
||||||
|
* پرامپت دقیق:
|
||||||
|
> «من می‌خواهم برای مخزن گیت‌هاب پورتفولیو یک فایل `README.md` فوق‌العاده شکیل، حرفه‌ای و جذاب بنویسم. پشته فناوری پروژه شامل Next.js 15، TypeScript، TailwindCSS، Supabase، Liara، ZarinPal، Kavenegar و Sentry است. لطفاً مستندی با بج‌های رنگی، جدول ویژگی‌ها، کد Mermaid فلوچارت سیستم، راهنمای گام‌به‌گام اجرای لوکال با متغیرهای فرضی، و راهنمای استقرار تدوین کن.»
|
||||||
|
9. **باکس نکته Quera (`<details class="violet">`):** استفاده از فایل `CONTRIBUTING.md` برای ایجاد حس یک پروژه اوپن‌سورس بالغ و آماده همکاری تیمی.
|
||||||
|
10. **باکس هشدار Quera (`<details class="red">`):** هرگز کلیدهای معتبر را در بخش تنظیمات فایل‌های محیطی README نگذارید؛ همیشه از مقادیر مثل `your_key_here` استفاده کنید.
|
||||||
|
11. **باکس رضایت‌بخش Quera (`<details class="green">`):** ثبت دکمه Commit و باز کردن صفحه اصلی مخزن پورتفولیو در گیت‌هاب و تحسین نظم و زیبایی آن.
|
||||||
|
12. **جمع‌بندی فصل سیزدهم و پرش به فصل پانزدهم:** پایان کامل فاز نگهداری؛ یادآوری گذر از پروژه ۲ (فصل ۱۴) و پرتاب به سوی فصل جذاب پانزدهم: تکامل محصول با AI (بازنویسی کدها، ایجنت‌های خودکار، PWA و اپ موبایل/دسکتاپ).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||||||
|
- [ ] ارکان شش‌گانه یک `README.md` حرفه‌ای به همراه نمونه کدهای Markdown تشریح گردند.
|
||||||
|
- [ ] نحوه ترسیم فلوچارت‌های سیستمی با فرمت Mermaid آموزش داده شود.
|
||||||
|
- [ ] مفهوم کتابچه‌های راهنمای عملیاتی (Runbooks) با سناریوهای پورتفولیو تبیین شود.
|
||||||
|
- [ ] پرامپت تولید خودکار مستندات جامع با ایجنت در متن درس لحاظ گردد.
|
||||||
Reference in New Issue
Block a user