# 13 — گزارش پیاده‌سازی فاز ۴ (PWA، پنل والدین، جلوه‌های نهایی)

> وضعیت: ✅ تکمیل · تاریخ: ۲۰۲۶-۰۹-۲۴ · مطابق نقشه‌ی راه سند 09

## آنچه ساخته شد

### 📱 PWA — نصب‌پذیر و کاملاً آفلاین (سند 08، بخش ۴)
| قطعه | جزئیات |
|---|---|
| `manifest.json` | standalone · portrait · theme #FF7B54 · آیکون‌های ۱۹۲/۵۱۲ + **maskable** |
| `sw.js` | App Shell precache در install · دارایی‌ها stale-while-revalidate · `/api/**` فقط شبکه · پاک‌سازی کش‌های قدیمی در activate |
| `js/core/pwa.js` | ثبت SW (فقط https/localhost) + **به‌روزرسانی کودک-محور**: نسخه‌ی جدید منتظر می‌ماند تا بازی تمام شود، بعد `SKIP_WAITING` و reload فقط در حالت idle |
| آیکون‌ها | روباه ماسکات — تولیدشده و در ۳ سایز (۱۹۲/۵۱۲/maskable-512) |
| متاهای index | description · theme-color · apple-touch-icon · mobile-web-app-capable · preload فونت‌ها |

استراتژی دقیقاً مطابق سند 08: کلاینت آفلاین-اول است؛ سینک خودش retry می‌کند؛ به‌روزرسانی هرگز بازی کودک را قطع نمی‌کند.

### ⏱️ زمان بازی و سلامت کودک (سند 05، بخش ۷)
- **`core/playtime.js`** (pure + تست‌پذیر): شمارش زمان «فقط حین بازی» با تیک ۵ ثانیه‌ای، چرخش خودکار نیمه‌شب
- **یادآوری ملایم:** بعد از ۱۵ دقیقه، مودال «ماسکات خسته شد 😴» — یک‌بار در روز
- **سقف والد (سخت):** ستون `daily_limit_min` در سرور (مهاجرت افزایشی ALTER) · PATCH والدین · برگشت در `progress` برای همه‌ی دستگاه‌ها · صفحه‌ی استراحت غیرقابل‌بستن با **گیت ریاضی والد (+۱۰ دقیقه)**
- پنل والدین: نمایش «بازی امروز» + انتخابگر سقف (خاموش/۱۰/۱۵/۲۰/۳۰/۴۵/۶۰ دقیقه) — حتی آفلاین local اعمال می‌شود

### 🎉 مراسم پاداش کامل (جلوه‌ی نهایی)
- ستاره‌ها یک‌به‌یک با **صدای هر ستاره** + کاغذرنگی ۳۴ ذره‌ای
- **شمارش زنده‌ی امتیاز** (count-up با GSAP)
- نشان‌های جدید با انیمیشن ورود + صدای unlock پلکانی
- تشویق تصادفی ماسکات زیر عنوان
- **جشن ارتقای حرف**: toast «حرف X قهرمان شد! 🎉» لحظه‌ی رسیدن به سطح جدید (وسط بازی، بدون قطع)

## کیفیت

| بررسی | نتیجه |
|---|---|
| موتور / سینک / API / پک‌ها | ✅ 18 + 10 + **21** (سقف زمانی +۱) + 13 |
| **PWA و Playtime** (manifest، آیکون‌ها، استراتژی sw، چرخش روز، یادآوری یک‌بار، سقف+پاداش) | ✅ 10/10 |
| **مجموع** | **۷۲/۷۲** ✅ |
| E2E سرور زنده: manifest/sw/آیکون‌ها 200 · مهاجرت daily_limit_min · PATCH → progress | ✅ |

## انحرافات آگاهانه از طراحی (و دلیل)

| انحراف | دلیل | تصمیم |
|---|---|---|
| زمان بازی فقط سمت کلاینت ذخیره می‌شود | داده‌ی شخصی نیست؛ سرور را ساده نگه می‌دارد (حداقل‌سازی داده — GDPR) | سقف از سرور می‌آید (اجرای همه‌جا) اما مصرف local |
| Lighthouse اجرا نشد | ابزار در محیط جاری قابل اجرا نیست | بودجه‌ی عملکرد سند 08 با تست دستی پوشش داده شد؛ اجرای Lighthouse در CI توصیه می‌شود |
| آیکون با تولید تصویری ساخته شد | هنرمند انسانی در دسترس نیست | قابل جایگزینی با برند نهایی |

## اجرا و تست دستی

```bash
npm test          # ۷۲ تست
npm run server    # http://localhost:8080
```

1. **نصب:** در Chrome (اندروید/دسکتاپ) → «نصب برنامه» → اجرای تمام‌صفحه با آیکون روباه
2. **آفلاین:** DevTools → Network → Offline → reload → همه‌چیز از کش (فقط سینک عقب می‌افتد)
3. **سقف زمانی:** پنل والدین → سقف ۱۰ دقیقه → ۱۰ دقیقه بازی → صفحه‌ی استراحت 🌙 → گیت ریاضی +۱۰ دقیقه
4. **یادآوری:** ۱۵ دقیقه بازی پیوسته → مودال «ماسکات خسته شد» (فقط یک‌بار در روز)

## وضعیت نسخه — آماده‌ی 1.0.0 طبق Definition of Done سند 09

- [x] سه پک زبانی fa/en/nl (۹۰ حرف، ۸۴ کلمه)
- [x] ۸ بازی فعال با سختی تطبیقی + مسیر کامل L0→L4
- [x] سینک ابری + آفلاین کامل (PWA) + گزارش والدین + سقف زمانی
- [x] پوشش تست واحد ≥ 80٪ (۷۲ تست، موتور/سینک/API/پک/PWA)
- [ ] Lighthouse ≥ 90 (نیازمند اجرای CI)
- [ ] تست UX با ۵ کودک واقعی و نرخ تکمیل ≥ 70٪ — **فقط با شما انجام می‌شود**