# 10 — گزارش پیاده‌سازی فاز ۱ (MVP فارسی)

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

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

### Core (هسته)
| ماژول | فایل | توضیح |
|---|---|---|
| EventBus | `js/core/eventBus.js` | pub/sub با سندباکس شنونده‌ها (ADR-04) |
| Router | `js/core/router.js` | hash router با پشتیبانی پارامتر و query (`game/:id?letter=`) |
| Store | `js/core/store.js` | Observable سبک؛ تک‌منبع حقیقت |
| i18n | `js/core/i18n.js` | `t()` + `tRandom()` + `num()` (ارقام فارسی) + تنظیم dir/lang از پک |
| PackLoader | `js/core/packLoader.js` | fetch + validate کامل (سند 03) + کش نسخه‌دار localStorage |
| AudioEngine | `js/core/audioEngine.js` | زنجیره‌ی fallback: فایل → TTS → بازخورد بصری/لمسی + سینتی‌سایزر WebAudio برای sfx |

### Engine (موتور — همگی pure و تست‌شده)
| ماژول | پوشش تست |
|---|---|
| MasteryTracker | سطوح L0→L2، عدم‌تنزل، Leitner ۵ جعبه‌ای، dueLetters، سافاری |
| LetterSelector | وزن‌دهی، قفل ایستگاه‌ها، تزریق خطاخیز، بدون‌تکرار |
| Adaptive | گذار ۲→۴→۶ گزینه بر اساس نرخ موفقیت، needsHelp |
| Scoring + checkBadges | کمبو، ستاره‌ها (دقت‌محور)، ۵ نوع نشان بدون تکرار |
| GameEngine + Registry | سندباکس try/catch، نقطه‌ی مرکزی `ctx.attempt`، مراسم پاداش |

### بازی‌ها (۳ بازی از ۸)
1. **🎈 حباب حروف** (`letterPop.js`) — ۸ دور، سختی تطبیقی ۲→۶ گزینه، راهنمایی pulse بعد از ۲ خطا
2. **🃏 جفت گنج** (`memoryMatch.js`) — ۴ جفت حرف↔کلمه، چرخش CSS 3D
3. **🦁 سافاری الفبا** (`alphabetSafari.js`) — کشف آزاد ۳۲ حرف، همه‌ی اشکال حرف + کلمه‌ی نمونه

### UI
- صفحات: خانه (ساخت دوست با آواتار/رنگ/نام مستعار — بدون رمز)، نقشه‌ی ماجراجویی مارپیچ ۳۲ ایستگاهی با قفل/L1، اتاق جوایز
- کامپوننت‌ها: ماسکات روباهی SVG، مودال bottom-sheet، مراسم پاداش (کاغذرنگی + star-reveal)، توست، تنظیمات والدین
- AnimationService با **۱۰ انیمیشن** واژگانی (intro-card, success-pop, gentle-shake, hint-pulse, bubble-pop, mascot-cheer, float, star-reveal, confetti-burst, screen-out/in) — تنها نقطه‌ی تماس با GSAP
- تم پاستلی + فونت وزیرمتن local + CSS Logical Properties (آزادِ RTL/LTR)

## کیفیت

- ✅ **۱۸/۱۸ تست واحد** موتور (`node tests/engine.test.js`) — بدون مرورگر
- ✅ گراف import هر **۳۱ ماژول** سالم
- ✅ پک فارسی از **validate واقعی** عبور کرد: ۳۲ حرف، ۳۲ کلمه، ۵ نشان
- ✅ شبیه‌سازی جلسه‌ی کامل موتور: امتیاز/ستاره/قفل ایستگاه/سختی همه درست
- ✅ GSAP 3.12.5 و Bootstrap 5.3.3 و فونت — **همه local، صفر CDN** (آفلاین کامل)
- حجم client بدون vendor: ~۳۲۴KB (بودجه‌ی سند 08 رعایت شد)

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

| انحراف | دلیل | برنامه |
|---|---|---|
| sfx با WebAudio ساخته می‌شود نه فایل | فایل ضبط‌شده هنوز موجود نیست | فاز ۳: فایل‌های MP3/OGG جایگزین می‌شوند؛ API ثابت می‌ماند |
| صدای حروف = TTS (نه فایل) | `pack.media.audioAvailable=false` → موتور مستقیم TTS می‌رود | فاز ۳: فایل‌ها + true کردن فلگ |
| تصویر کلمات = emoji | سریع، سبک، جذاب برای کودک | فاز ۳: SVG اختصاصی هنرمند |
| `resetAll` یک reload دارد | عملیات مخرب؛ تمیزترین راه | فاز ۴: پنل والدین بدون reload |

## اجرا

```bash
node tests/engine.test.js                          # تست واحد موتور
python3 -m http.server 8080 --directory client     # اجرای اپ (یا: npm run dev)
# سپس: http://localhost:8080
```

## معیار پذیرش فاز (طبق سند 09)

- [x] هسته‌ی Core و Engine کامل
- [x] پک فارسی کامل (۳۲ حرف)
- [x] ۳ بازی فعال
- [x] AudioEngine + AnimationService (۵+ انیمیشن)
- [x] پیشرفت local (localStorage) با SyncQueue آماده‌ی فاز ۲
- [ ] **تست UX با کودک واقعی ۴–۶ ساله** ← نیازمند شما! این آیتم با هیچ ابزاری جایگزین نمی‌شود.