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