vibe-coding-college-specs/chapters/15-product-evolution/09-lesson-progressive-web-apps-pwa/spec.md

مشخصات درس‌نامه: تبدیل وب‌سایت به وب‌اپلیکیشن پیش‌رونده (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):

       npm install @ducanh2912/next-pwa
       

     • macOS (Terminal):

       npm install @ducanh2912/next-pwa
       

     • Linux (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 با پکیج‌های مدرن آموزش داده شود.
• استراتژی‌های کش‌گذاری آفلاین و صفحه فال‌بک آفلاین لحاظ گردد.
• دستورات نصب پکیج در تب‌های چندسکویی ویندوز، مک و لینوکس گنجانده شود.