# مشخصات درس‌نامه: تبدیل وب‌سایت به وب‌اپلیکیشن پیش‌رونده (PWA) با قابلیت نصب و کارکرد آفلاین
- **شناسه در سیلابس:** `L15.10`
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
- **پیش‌نیازهای مستقیم:** `L15.9` (استخراج بینش محصول با هوش مصنوعی)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** فناوری وب‌اپلیکیشن پیش‌رونده (Progressive Web App - PWA) را به عنوان پلی میان دنیای وب و اپلیکیشن‌های بومی بشناسد و بداند چگونه می‌توان بدون نیاز به عبور از هفت‌خوان کافه‌بازار یا اپ‌استور، سایت را قابل نصب کرد.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** سه ستون اصلی PWA شامل: فایل مانیفست وب (`manifest.json`)، سرویس‌ورکر (Service Worker) و استراتژی‌های کش حافظه موقت (Cache-First در برابر Network-First) را ارزیابی کند.
- [ ] **به‌کار ببندد (Apply):** افزونه استاندارد Next.js PWA را در پروژه پورتفولیو نصب کرده و آیکون‌ها، رنگ پوسته، و حالت تمام‌صفحه بدون نوار آدرس (`display: standalone`) را پیکربندی نماید.
- [ ] **ایجاد کند (Create):** یک سناریوی کارکرد آفلاین طراحی کند که در صورت قطع شدن کامل اینترنت، پروژه‌های پورتفولیو همچنان با سرعت بالا از روی کش باز شوند و صفحه آفلاین شکیل نمایش داده شود.

---

## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)

### آنچه باید پوشش داده شود (In-Scope):
1. **جادوی PWA: نصب مستقیم از مرورگر با یک کلیک:**
   * نمایش پیام «افزودن به صفحه اصلی» (Add to Home Screen) در اندروید، آیفون، ویندوز و مک.
   * باز شدن سایت شبیه یک اپلیکیشن کاملاً بومی بدون نوار آدرس زشت مرورگر.
2. **کالبدشکافی ستون اول: فایل مانیفست وب (`app/manifest.ts`):**
   * تعریف مشخصات هویتی: `name`, `short_name`, `theme_color`, `background_color`.
   * تعیین آیکون‌های استاندارد ۱۹۲x۱۹۲ و ۵۱۲x۵۱۲ با قابلیت تطبیق‌پذیری ماسک (Maskable Icons).
   * حالت نمایش تمام‌صفحه: `display: 'standalone'`.
3. **کالبدشکافی ستون دوم: سرویس‌ورکر (Service Worker):**
   * مامور نامرئی پشت صحنه که میان مرورگر و شبکه اینترنت می‌نشیند و درخواست‌ها را مدیریت می‌کند.
   * استراتژی‌های کش‌گذاری:
     - برای عکس‌ها، فونت‌ها و استایل‌ها: استراتژی Cache-First (اول کش، اگر نبود دانلود).
     - برای داده‌های داینامیک پروژه‌ها: استراتژی Stale-While-Revalidate (نمایش سریع دیتای قبلی کش و همزمان آپدیت از اینترنت).
4. **پیاده‌سازی در Next.js مدرن:**
   * استفاده از پکیج‌های استاندارد PWA نظیر `@ducanh2912/next-pwa`.
   * ساخت صفحه آفلاین اختصاصی `app/offline/page.tsx`.
5. **آزمایش امتیاز PWA در لایت‌هاوس:**
   * اجرای ممیزی Lighthouse در Chrome DevTools و سبز شدن نشانگر قابلیت نصب.
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): نحوه ذخیره‌سازی فایل‌های PWA در حافظه کش مرورگر (Cache Storage API) و تفاوت آن با localStorage.
   * کال‌اوت سبز (`<details class="green">`): دیدن آیکون زیبای پورتفولیو در کنار سایر برنامه‌های گوشی در منوی اصلی اندروید و آیفون.
   * کال‌اوت قرمز (`<details class="red">`): هرگز درخواست‌های دیتابیسی دارای جهش (POST/DELETE) را در سرویس‌ورکر کش نکنید!

### آنچه نباید وارد آن شویم (Out-of-Scope):
- نوتیفیکیشن‌های پس‌زمینه وب‌پوش پیچیده با سرورهای VAPID اختصاصی.
- ساخت کدهای اختصاصی جاوا/کاتلین اندروید (در درس بعدی با Capacitor و Expo پوشش داده می‌شود).

---

## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Progressive Web App (PWA) | وب‌اپلیکیشن پیش‌رونده | سایتی با قابلیت‌های ارتقایافته نظیر نصب روی هوم‌اسکرین، اجرای آفلاین و ظاهر بومی |
| Web App Manifest | مانیفست وب‌اپلیکیشن | سند پیکربندی استانداردی که نحوه نمایش، نام، آیکون‌ها و رنگ‌های برنامه را برای سیستم‌عامل مشخص می‌کند |
| Service Worker | سرویس‌ورکر / کارگر خدمت‌رسان | اسکریپت پس‌زمینه‌ای که درخواست‌های شبکه را مهار کرده و مدیریت حافظه کش آفلاین را بر عهده دارد |
| Standalone Display | نمایش مستقل تمام‌صفحه | حالتی از اجرای وب‌اپلیکیشن که تمام نوارها و دکمه‌های مرورگر حذف شده و حس اپلیکیشن نیتیو می‌دهد |
| Stale-While-Revalidate | استراتژی تحویل فوری و اعتبارسنجی مجدد | شیوه کش‌گذاری که ابتدا دیتای موجود در حافظه را فوراً نشان می‌دهد و سپس در پس‌زمینه آخرین تغییرات را بارگذاری می‌کند |
| Maskable Icons | آیکون‌های تطبیق‌پذیر | تصاویری با حاشیه امن که توسط اندروید به اشکال مربع گرد، دایره یا لوزی به درستی برش می‌خورند |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** گوشی موبایل هوشمند با آیکون درخشان پورتفولیو روی هوم‌اسکرین در کنار اپلیکیشن‌های معروف و بنر تایید «نصب با موفقیت انجام شد».
2. **تفاوت تجربه وب معمولی با PWA در موبایل:** `images/standard-web-vs-pwa-mobile.png`
   * **موضوع:** اینفوگرافیک مقایسه‌ای: مرورگر شلوغ با نوار آدرس و تب‌ها در برابر اپلیکیشن PWA کاملاً تمیز، تمام‌صفحه و با تم رنگی اختصاصی.
3. **جریان کار سرویس‌ورکر در حالت آنلاین و آفلاین:** `images/service-worker-interception-flow.png`
   * **موضوع:** دیاگرام معماری: مرورگر $\rightarrow$ سرویس‌ورکر $\rightarrow$ اگر نت وصل بود: دریافت از سرور + ذخیره در کش $\rightarrow$ اگر نت قطع بود: خواندن مستقیم از Cache Storage.
4. **صفحه خطای آفلاین شکیل پورتفولیو:** `images/offline-fallback-screen-preview.png`
   * **موضوع:** اسکرین‌شات از نمایش صفحه در حالت قطع اینترنت با پیام ملایم: «شما آفلاین هستید، اما می‌توانید پروژه‌های ذخیره‌شده قبلی را مرور کنید.»

---

## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)

1. **تیتر اصلی:** `# تبدیل وب‌سایت به وب‌اپلیکیشن پیش‌رونده (PWA) با قابلیت نصب و کارکرد آفلاین`
2. **مقدمه:** چرا وقتی می‌توانید با چند خط کانفیگ، سایت خود را مستقیماً بدون نیاز به گوگل‌پلی یا اپ‌استور روی گوشی کارفرمایان نصب کنید، این کار را نکنید؟
3. **جدول کاور درس**
4. **استعاره تبدیل بروشور کاغذی به یک نرم‌افزار دائمی:**
   * تفاوت سایتی که در تب‌های فراموش‌شده مرورگر گم می‌شود با اپلیکیشنی که روی صفحه اول گوشی جا خوش می‌کند.
5. **گام اول: ساخت سند مانیفست وب (`app/manifest.ts`):**
   * کدنویسی مشخصات هویتی، آیکون‌ها و رنگ تم در Next.js.
6. **گام دوم: نصب و پیکربندی Service Worker:**
   * نصب پکیج `@ducanh2912/next-pwa` در `next.config.js`.
   * تنظیم استراتژی‌های کش‌گذاری برای سرعت برق‌آسا.
7. **گام سوم: طراحی صفحه آفلاین اختصاصی (`app/offline/page.tsx`):**
   * احترام به کاربر در زمان قطعی شبکه و قطع امید نکردن از سایت.
8. **جعبه پرامپت طلایی: تبدیل پروژه به PWA کامل با ایجنت:**
   * پرامپت دقیق:
     > «من می‌خواهم پروژه پورتفولیو را به یک Progressive Web App کامل تبدیل کنم. لطفاً: ۱) فایل `app/manifest.ts` را با مشخصات برند، رنگ بنفش، و آیکون‌های استاندارد بساز، ۲) کانفیگ `@ducanh2912/next-pwa` را در `next.config.js` اضافه کن، و ۳) یک صفحه جذاب آفلاین در `app/offline/page.tsx` برای مواقع قطعی نت طراحی کن.»
9. **دستورات چندسکویی برای نصب پکیج PWA:**
   * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
     - Windows (PowerShell):
       ```powershell
       npm install @ducanh2912/next-pwa
       ```
     - macOS (Terminal):
       ```bash
       npm install @ducanh2912/next-pwa
       ```
     - Linux (Bash):
       ```bash
       npm install @ducanh2912/next-pwa
       ```
10. **باکس نکته Quera (`<details class="violet">`):** تولید خودکار آیکون‌های ماسکبل با ابزارهای آنلاین نظیر Maskable.app در کمتر از ۳۰ ثانیه.
11. **باکس هشدار Quera (`<details class="red">`):** سرویس‌ورکرها فقط و فقط روی پروتکل امن HTTPS و روی localhost کار می‌کنند؛ سایت بدون SSL هرگز PWA نخواهد شد.
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** کلیک روی دکمه Install در نوار آدرس کروم و باز شدن پورتفولیو در پنجره اختصاصی نرم‌افزار دسکتاپ و موبایل.
13. **جمع‌بندی درس‌نامه:** مجهز شدن سایت به قابلیت‌های PWA؛ ورود به ساخت فایل خروجی نصبی واقعی اپلیکیشن موبایل با Capacitor و Expo در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] ارکان سه‌گانه PWA (مانیفست، سرویس‌ورکر، HTTPS) به روشنی شرح داده شود.
- [ ] نحوه پیاده‌سازی گام‌به‌گام در فریم‌ورک Next.js با پکیج‌های مدرن آموزش داده شود.
- [ ] استراتژی‌های کش‌گذاری آفلاین و صفحه فال‌بک آفلاین لحاظ گردد.
- [ ] دستورات نصب پکیج در تب‌های چندسکویی ویندوز، مک و لینوکس گنجانده شود.