diff --git a/chapters/13-product-maintenance/00-lesson-chapter-goals/spec.md b/chapters/13-product-maintenance/00-lesson-chapter-goals/spec.md new file mode 100644 index 0000000..fd16c8c --- /dev/null +++ b/chapters/13-product-maintenance/00-lesson-chapter-goals/spec.md @@ -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. **کال‌اوت‌های کوئرا:** + * کال‌اوت سبز (`
`): خواب راحت شبانه با داشتن سیستم هشدار تلگرامی که در صورت هرگونه نقص فنی به شما پیام می‌دهد. + +### آنچه نباید وارد آن شویم (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 (`
`):** وقتی باگ‌ها قبل از باخبر شدن کارفرما در جیب شما آلارم بزنند، به اوج پرستیژ مهندسی دست یافته‌اید! + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] اهداف کلان فصل ۱۳ و لزوم مراقبت پس از استقرار تبیین شود. +- [ ] سرفصل‌های ۷ درس‌نامه بعدی با ذکر ابزارهای مصوب (Sentry, UptimeRobot, Clarity, Search Console) معرفی گردند. +- [ ] مفهوم مشاهده‌پذیری (Observability) به زبان ساده و قابل فهم ارائه شود. diff --git a/chapters/13-product-maintenance/01-lesson-observability-and-monitoring/spec.md b/chapters/13-product-maintenance/01-lesson-observability-and-monitoring/spec.md new file mode 100644 index 0000000..1d78199 --- /dev/null +++ b/chapters/13-product-maintenance/01-lesson-observability-and-monitoring/spec.md @@ -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. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم شاخص صدک ۹۵ام (p95 Latency)؛ چرا بررسی «میانگین» گول‌زننده است و تاخیر کندترین ۵ درصد کاربران را پنهان می‌کند. + * کال‌اوت سبز (`
`): مشاهده نمودار مصرف رم لیارا در مقیاس مگابایت که برای پورتفولیو معمولاً زیر ۱۵۰ مگابایت بسیار پایدار است. + * کال‌اوت قرمز (`
`): خطر نشت حافظه (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 (`
`):** جادوی شاخص صدک ۹۵ام (p95)؛ چرا میانگین‌ها دروغ می‌گویند و تاخیر افراد با اینترنت ضعیف را پنهان می‌کنند. +10. **باکس هشدار Quera (`
`):** هرگز فایل‌های بزرگ یا استریم‌های ویدیویی را بدون کش روی سرور اصلی پردازش نکنید؛ فشار آنی پردازنده مساوی با قطع سایت خواهد بود. +11. **باکس رضایت‌بخش Quera (`
`):** تماشای نمودارهای آرام و سبز مصرف منابع پورتفولیو پس از استقرار موفق و پایدار. +12. **جمع‌بندی درس‌نامه:** تسلط بر پایش منابع سرور؛ ورود به مبحث حیاتی هشدارهای زنده و سیستم اعلان آپتایم ۲۴ ساعته در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] تمایز میان Monitoring سطحی و Observability عمیق تبیین شود. +- [ ] سیگنال‌های چهارگانه طلایی به همراه شاخص‌های آماری نظیر p95 تشریح گردند. +- [ ] نحوه خواندن داشبوردهای مصرف منابع در لیارا و ورسل آموزش داده شود. +- [ ] مفهوم خطای OOM و روش‌های پیشگیری از نشت حافظه لحاظ گردد. diff --git a/chapters/13-product-maintenance/02-lesson-uptime-and-alerting-systems/spec.md b/chapters/13-product-maintenance/02-lesson-uptime-and-alerting-systems/spec.md new file mode 100644 index 0000000..a224178 --- /dev/null +++ b/chapters/13-product-maintenance/02-lesson-uptime-and-alerting-systems/spec.md @@ -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. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم آلارم کاذب (False Positive)؛ چرا مانیتور باید بعد از ۲ تلاش ناموفق متوالی آلارم بزند تا با نوسانات چندثانیه‌ای اینترنت هشدار اشتباه ندهد. + * کال‌اوت سبز (`
`): دریافت نوتیفیکیشن تلگرام در کمتر از ۶۰ ثانیه بعد از قطعی سرور روی گوشی موبایل. + * کال‌اوت قرمز (`
`): پایش روت‌های سنگین دیتابیسی را در بازه‌های ۳۰ ثانیه‌ای نگذارید؛ پینگ‌های سنگین مداوم خودشان باعث کندی سرور می‌شوند! + +### آنچه نباید وارد آن شویم (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 (`
`):** جلوگیری از آلارم‌های کاذب؛ تنظیم شرط اعلام قطعی تنها پس از ۲ بار تلاش ناموفق پیاپی. +11. **باکس هشدار Quera (`
`):** مانیتور را روی صفحات سنگین نیازمند لاگین نگذارید؛ همیشه صفحه اصلی یا یک اندپوینت سبک `/api/health` را مانیتور کنید. +12. **باکس رضایت‌بخش Quera (`
`):** شبیه‌سازی قطعی سرور (توقف موقت در پنل) و شنیدن صدای زنگ هشدار تلگرام در کمتر از ۶۰ ثانیه روی گوشی. +13. **جمع‌بندی درس‌نامه:** مجهز شدن به سیستم هشدار سریع؛ ورود به ایستگاه کالبدشکافی خطاهای زنده پروداکشن با سنتری (Sentry) در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] مفهوم آپتایم و چرخه مانیتورینگ بیرونی به روشنی بیان شود. +- [ ] راه‌اندازی گام‌به‌گام UptimeRobot به صورت عملی آموزش داده شود. +- [ ] نحوه اتصال ربات تلگرام و دریافت اعلان‌های لحظه‌ای در متن لحاظ گردد. +- [ ] مفهوم پایش کلیدواژه و صفحه وضعیت عمومی (Status Page) تشریح شود. diff --git a/chapters/13-product-maintenance/03-lesson-production-logging-and-error-tracking/spec.md b/chapters/13-product-maintenance/03-lesson-production-logging-and-error-tracking/spec.md new file mode 100644 index 0000000..357ec57 --- /dev/null +++ b/chapters/13-product-maintenance/03-lesson-production-logging-and-error-tracking/spec.md @@ -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. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم حریم خصوصی و فیلتر خودکار دیتای حساس (Data Scrubbing)؛ سنتری به صورت پیش‌فرض رمزها و اطلاعات کارت بانکی را از لاگ‌ها ماسک می‌کند. + * کال‌اوت سبز (`
`): سهمیه رایگان سخاوتمندانه ماهیانه ۵۰۰۰ خطا در پلن توسعه‌دهنده سنتری. + * کال‌اوت قرمز (`
`): پاک‌سازی کدهای `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 (`
`):** ماجرای امنیت و حریم خصوصی داده‌ها در سنتری؛ خیالتان راحت باشد، توکن‌ها و اطلاعات کارت به صورت خودکار ستاره‌دار (`[Filtered]`) می‌شوند. +11. **باکس هشدار Quera (`
`):** لاگ‌های اضافه و حجیم در پروداکشن ننویسید؛ چاپ بیهوده هزاران خط در هر ثانیه به هدررفت منابع و هزینه سرور می‌انجامد. +12. **باکس رضایت‌بخش Quera (`
`):** ایجاد یک خطای عمدی آزمایشی در سایت و مشاهده ظاهر شدن آن در داشبورد سنتری در کمتر از ۳ ثانیه. +13. **جمع‌بندی درس‌نامه:** تجهیز کامل سیستم به جعبه سیاه عیب‌یابی؛ ورود به مبحث به‌روزرسانی‌های امنیتی و ارتقای دوره‌ای پکیج‌ها در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] نقطه کور پروداکشن و ضرورت ثبت لاگ‌ها و ردگیری خطاها به روشنی تبیین شود. +- [ ] تفاوت میان لاگ‌های سرور (لیارا/ورسل) با سرویس‌های Error Tracking (سنتری) تشریح گردد. +- [ ] راه‌اندازی گام‌به‌گام سنتری در Next.js به همراه مفاهیم Breadcrumbs آموزش داده شود. +- [ ] پرامپت دیباگ خطای پروداکشن با استفاده از لاگ‌های سنتری ارائه شود. diff --git a/chapters/13-product-maintenance/04-lesson-security-updates-and-dependency-upgrades/spec.md b/chapters/13-product-maintenance/04-lesson-security-updates-and-dependency-upgrades/spec.md new file mode 100644 index 0000000..981f93d --- /dev/null +++ b/chapters/13-product-maintenance/04-lesson-security-updates-and-dependency-upgrades/spec.md @@ -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. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم Breaking Changes در آپدیت‌های ماژور (نظیر جهش از Next.js 14 به 15) و چرایی لزوم خواندن راهنمای رسمی ارتقا (Migration Guide). + * کال‌اوت سبز (`
`): آرامش خاطر با به‌روزرسانی‌های ماهانه ۱۵ دقیقه‌ای که مانع از انباشت بدهی فنی (Technical Debt) می‌شود. + * کال‌اوت قرمز (`
`): هرگز آپدیت‌های ماژور را بدون داشتن کامیت ذخیره و در شب پیش از ارائه به کارفرما انجام ندهید! + +### آنچه نباید وارد آن شویم (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 (`
`):** اهمیت مطالعه فایل CHANGELOG یا Releases در گیت‌هاب کتابخانه قبل از آپدیت‌های بزرگ ماژور. +11. **باکس هشدار Quera (`
`):** هرگز همه پکیج‌ها را به یکباره و بدون تست با دستورات فورس آپدیت نکنید؛ یک ناسازگاری کوچک می‌تواند ساعت‌ها وقت شما را برای ریکاوری تلف کند. +12. **باکس رضایت‌بخش Quera (`
`):** پورتفولیویی که همیشه تمیز، مدرن و مجهز به آخرین پچ‌های امنیتی روز دنیاست. +13. **جمع‌بندی درس‌نامه:** تسلط بر نگهداری زیرساختی؛ ورود به مبحث رشد و دیده شدن: سئو تکنیکال و تحلیل رفتار کاربر در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] پدیده فرسودگی نرم‌افزار و ضرورت به‌روزرسانی‌های مستمر تشریح شود. +- [ ] ساختار نسخه‌بندی معنایی (SemVer) و علائم `^` و `~` به روشنی آموزش داده شود. +- [ ] پروتکل ۴ مرحله‌ای ایمن ارتقای وابستگی‌ها به همراه دستورات چندسکویی ارائه گردد. +- [ ] شیوه فعال‌سازی و کاربرد Dependabot در مخزن گیت‌هاب تشریح شود. diff --git a/chapters/13-product-maintenance/05-lesson-technical-seo-and-user-analytics/spec.md b/chapters/13-product-maintenance/05-lesson-technical-seo-and-user-analytics/spec.md new file mode 100644 index 0000000..32b14c6 --- /dev/null +++ b/chapters/13-product-maintenance/05-lesson-technical-seo-and-user-analytics/spec.md @@ -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. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): مفهوم کلیک‌های خشمگینانه (Rage Clicks) و چگونه این شاخص به شما نشان می‌دهد کدام دکمه یا کارت در سایت گمراه‌کننده است. + * کال‌اوت سبز (`
`): مشاهده اولین ویدیوی گشت‌وگذار یک بازدیدکننده در پورتفولیو و حس شگفت‌انگیز درک رفتار کاربر واقعی. + * کال‌اوت قرمز (`
`): مسدود کردن مسیرهای `/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 (`
`):** اهمیت داده‌های Rage Clicks؛ کشف المان‌هایی که شبیه لینک طراحی شده‌اند اما کار نمی‌کنند و اصلاح فوری آن‌ها. +11. **باکس هشدار Quera (`
`):** مسدود کردن صفحات پنل مدیریت در `robots.txt`؛ امنیت و حریم خصوصی پنل ادمین با سئو مخدوش نشود. +12. **باکس رضایت‌بخش Quera (`
`):** دیدن اولین نتایج سرچ کنسول و تماشای حرکات زنده بازدیدکنندگان روی دکمه رزرو و دانلود رزومه. +13. **جمع‌بندی درس‌نامه:** تسلط بر دیدبانی رفتار و سئو؛ ورود به آخرین درس این فصل: مستندسازی فاخر و راهنمای نگهداری پروژه در درس بعدی. + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] اصول سئو تکنیکال مدرن (sitemap.ts, robots.ts, JSON-LD) با کدهای استاندارد پیاده شود. +- [ ] مراحل ثبت سایت و ارسال نقشه سایت در Google Search Console تشریح گردد. +- [ ] راه‌اندازی و کاربرد Microsoft Clarity (Session Replays, Heatmaps, Rage Clicks) آموزش داده شود. +- [ ] کدهای ادغام اسکریپت با استفاده از کامپوننت بهینه‌ساز Next.js ارائه گردد. diff --git a/chapters/13-product-maintenance/06-lesson-project-documentation-and-playbooks/spec.md b/chapters/13-product-maintenance/06-lesson-project-documentation-and-playbooks/spec.md new file mode 100644 index 0000000..20c7468 --- /dev/null +++ b/chapters/13-product-maintenance/06-lesson-project-documentation-and-playbooks/spec.md @@ -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. **کال‌اوت‌های آموزشی و هشدار کوئرا:** + * کال‌اوت بنفش (`
`): قابلیت رندر مستقیم دیاگرام‌های Mermaid در ریپازیتوری‌های گیت‌هاب بدون نیاز به تصویر خارجی. + * کال‌اوت سبز (`
`): استفاده از بج‌های رنگی Shields.io برای ایجاد حس محصولات متن‌باز سطح یک سیلیکون‌ولی. + * کال‌اوت قرمز (`
`): هرگز مقادیر واقعی کلیدهای اختصاصی را داخل مثال‌های `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 (`
`):** استفاده از فایل `CONTRIBUTING.md` برای ایجاد حس یک پروژه اوپن‌سورس بالغ و آماده همکاری تیمی. +10. **باکس هشدار Quera (`
`):** هرگز کلیدهای معتبر را در بخش تنظیمات فایل‌های محیطی README نگذارید؛ همیشه از مقادیر مثل `your_key_here` استفاده کنید. +11. **باکس رضایت‌بخش Quera (`
`):** ثبت دکمه Commit و باز کردن صفحه اصلی مخزن پورتفولیو در گیت‌هاب و تحسین نظم و زیبایی آن. +12. **جمع‌بندی فصل سیزدهم و پرش به فصل پانزدهم:** پایان کامل فاز نگهداری؛ یادآوری گذر از پروژه ۲ (فصل ۱۴) و پرتاب به سوی فصل جذاب پانزدهم: تکامل محصول با AI (بازنویسی کدها، ایجنت‌های خودکار، PWA و اپ موبایل/دسکتاپ). + +--- + +## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer) +- [ ] ارکان شش‌گانه یک `README.md` حرفه‌ای به همراه نمونه کدهای Markdown تشریح گردند. +- [ ] نحوه ترسیم فلوچارت‌های سیستمی با فرمت Mermaid آموزش داده شود. +- [ ] مفهوم کتابچه‌های راهنمای عملیاتی (Runbooks) با سناریوهای پورتفولیو تبیین شود. +- [ ] پرامپت تولید خودکار مستندات جامع با ایجنت در متن درس لحاظ گردد.