Skip to content

DESIGN.md

Latest commit

 

History

History
304 lines (260 loc) · 10.6 KB

DESIGN.md

File metadata and controls

304 lines (260 loc) · 10.6 KB
Raw

🐍 پایتون‌باز — طراحی کامل پروژه (نسخه آرکید)

🔗 بازی آنلاین

هدف

بازی یادگیری پایتون با رابط وب فارسی و حالت آرکید. کاربر با چالش‌های تعاملی پایتون یاد میگیره، ایکس‌پی کسب میکنه، لِوِل بالا میره، و از مکانیک‌های بازی مثل استریک روزانه، ماموریت، انرژی و فروشگاه لذت میبره.

فناوری

  • HTML + CSS + JavaScript (Vanilla)
  • SPA Router (hash-based)
  • View-based architecture
  • localStorage با versioning برای ذخیره پیشرفت
  • مهاجرت خودکار داده‌های قدیمی
  • GitHub Pages برای هاست رایگان
  • GitHub Actions برای دیپلوی خودکار

📊 ساختار فایل‌ها

python-game-lab/
├── index.html              # صفحه اصلی (SPA entry)
├── css/
│   ├── tokens.css          # توکن‌های طراحی (رنگ‌ها، فاصله‌ها و...)
│   ├── base.css            # استایل‌های پایه/ریست
│   ├── arcade.css          # تم آرکید و سیستم‌های گیمیفیکیشن
│   ├── components.css      # کامپوننت‌های قابل استفاده مجدد
│   └── pages.css           # استایل‌های اختصاصی صفحات
├── js/
│   ├── app.js              # ورودی اصلی SPA + روترا
│   ├── router.js           # مسیریاب هش‌بیس
│   ├── state.js            # مدیریت وضعیت سراسری (versioned)
│   ├── migration.js        # مهاجرت داده‌های قدیمی
│   ├── views/
│   │   ├── home.js         # صفحه خانه/داشبورد
│   │   ├── map.js          # نقشه فصل‌ها
│   │   ├── lesson.js       # صفحه آموزش
│   │   ├── exercises.js    # صفحه تمرین‌ها
│   │   ├── challenges.js   # صفحه چالش‌ها
│   │   ├── result.js       # صفحه نتیجه/امتیاز
│   │   ├── profile.js      # صفحه پروفایل
│   │   └── settings.js     # صفحه تنظیمات
│   ├── systems/
│   │   ├── xp.js           # سیستم XP و لِوِل
│   │   ├── streak.js       # پیگیری استریک روزانه
│   │   ├── energy.js       # سیستم انرژی
│   │   ├── quests.js       # ماموریت‌های روزانه
│   │   ├── shop.js         # فروشگاه بازی
│   │   └── sound.js        # صدا و افکت‌ها (Web Audio API)
│   ├── utils.js            # توابع کمکی
│   ├── glossary.js         # واژه‌نامه پایتون (۳۷ کلمه)
│   └── search.js           # جستجوی فصل
├── data/
│   ├── chapter_1.json      # فصل ۱: متغیرها
│   ├── chapter_2.json      # فصل ۲: عملگرها
│   ├── ...                 # (۲۳ فصل)
│   └── chapter_23.json     # فصل ۲۳: تست‌نویسی
├── .github/
│   └── workflows/
│       └── deploy.yml      # دیپلوی GitHub Pages
├── .nojekyll               # غیرفعال کردن Jekyll
├── DESIGN.md               # همین فایل
└── README.md

🏗️ معماری SPA

مسیریابی (Router)

مسیریابی هش‌بیس با الگوهای زیر:

  • #/home — صفحه خانه
  • #/map — نقشه فصل‌ها
  • #/lesson/:id — صفحه آموزش فصل
  • #/exercises/:id — صفحه تمرین فصل
  • #/challenges/:id — صفحه چالش فصل
  • #/result/:id — صفحه نتیجه
  • #/profile — پروفایل کاربر
  • #/settings — تنظیمات

الگوی View

هر صفحه یک ماژول view مستقل (views/*.js) هست که:

  • init() — مقداردهی اولیه
  • render() — رندر کردن محتوا
  • destroy() — پاکسازی event listenerها

مدیریت وضعیت (State)

وضعیت سراسری در localStorage با versioning ذخیره میشه. هنگام آپگرید، migration.js داده‌های قدیمی رو به فرمت جدید مهاجرت میده.

🏅 سیستم‌های گیمیفیکیشن

۱. XP و لِوِل

- چالش درست = ۱۰۰ XP
- چالش اشتباه = ۱۰ XP (تخفیف)
- هر لِوِل = لِوِل قبلی × ۱۵۰ XP
- لِوِل ۱ = ۱۵۰ XP, لِوِل ۲ = ۳۰۰ XP, لِوِل ۳ = ۴۵۰ XP ...

۲. استریک روزانه (Daily Streak)

- هر روز ورود = +۱ استریک
- جایزه: لِوِل استریک × ۵۰ XP
- ریست: اگه یه روز وارد نشی

۳. سیستم انرژی

- حداکثر: ۵ انرژی
- بازیابی: ۱ انرژی هر ۳۰ دقیقه
- هزینه: ۱ انرژی برای هر چالش

۴. ماموریت‌های روزانه (Daily Quests)

- ۳ ماموریت روزانه
- مثال: "۳ چالش حل کن", "یه فصل کامل کن"
- جایزه: ۲۰۰ XP
- ریست: هر روز ساعت ۰۰:۰۰

۵. فروشگاه بازی

- آیتم‌های قابل خرید با XP
- اسکین پروفایل
- تایمر بونوس
- انرژی اضافی

💾 سیستم ذخیره‌سازی (localStorage)

{
  "version": 2,
  "username": "عرفان",
  "currentChapter": 3,
  "completedChapters": [1, 2],
  "chapters": {
    "1": {
      "completed": true,
      "score": 850,
      "challenges": {
        "predict_1": { "solved": true, "bestScore": 100, "attempts": 1 },
        "bug_hunter_1": { "solved": true, "bestScore": 100, "attempts": 1 },
        "fill_gap_1": { "solved": false, "bestScore": 0, "attempts": 0 }
      }
    }
  },
  "totalXP": 1570,
  "totalPlayTime": 3600,
  "lastPlayed": "2026-08-05T10:30:00",
  "gamification": {
    "level": 5,
    "xp": 750,
    "streak": { "current": 7, "best": 12, "lastDate": "2026-08-05" },
    "energy": { "current": 4, "max": 5, "lastRegen": "2026-08-05T10:30:00" },
    "dailyQuests": {
      "date": "2026-08-05",
      "quests": [...],
      "completed": 1
    },
    "shop": {
      "inventory": ["neon_frame", "double_xp"],
      "equipped": { "frame": "neon_frame" }
    }
  }
}

🎨 طراحی رابط کاربری

تم: تاریک 🌙

  • پس‌زمینه: #0f0f23 (سرمه‌ای تیره)
  • متن اصلی: #e0e0e0
  • رنگ اصلی: #00d4aa (سبز فیروزه‌ای)
  • رنگ خطا: #ff6b6b (قرمز)
  • رنگ موفقیت: #51cf66 (سبز)
  • کارت‌ها: #1a1a2e با shadow تیره

تم: آرکید 🕹️

  • رنگ اصلی آرکید: #ff6b9d (صورتی نئونی)
  • رنگ ثانویه: #c084fc (بنفش نئونی)
  • حاشیه‌های درخشان (glow effects)
  • انیمیشن‌های لِوِل آپ و XP

فونت: Vazirmatn (فارسی)

صفحات:

  1. صفحه خانه — داشبورد با آمار روزانه و میانبر
  2. نقشه فصل — نمایش گرافیکی فصل‌ها با قفل/باز
  3. صفحه آموزش — محتوای آموزشی فصل
  4. صفحه تمرین — تمرین‌های ساده
  5. صفحه چالش — چالش‌های اصلی
  6. صفحه نتیجه — امتیاز + پیشرفت + جوایز XP
  7. صفحه پروفایل — آمار کاربر + دستاورد‌ها + استریک
  8. صفحه تنظیمات — تم + صدا + اطلاعات

انیمیشن‌ها:

  • جواب درست: confetti + صدای تبریک
  • جواب غلط: shake animation
  • لِوِل آپ: انیمیشن درخشش
  • انتقال صفحه: fade in/out
  • پیشرفت: نوار لود روان
  • استریک: آتش انیمیشنی 🔥

📚 نوع چالش‌ها

۱. predict (پیش‌بینی خروجی)

کد نشون داده میشه، کاربر جواب رو تایپ میکنه

کد: x = 5; y = 3; print(x + y)
جواب: 8

۲. bug_hunter (شکارچی باگ)

کد با خطا نشون داده میشه، کاربر خط خطا رو مشخص میکنه

کد: num = 5
     if num = 5:
         print('پنج')
خطا: خط ۲ (باید == باشه نه =)

۳. fill_gap (پر کردن جای خالی)

کد ناقصه، کاربر قسمت خالی رو پر میکنه

کد: ___ = 10
     print(x)
جواب: x

۴. quiz (چندگزینه‌ای)

سوال + ۴ گزینه

سوال: type(3.14) چیه؟
گزینه‌ها: a) int  b) float  c) str  d) bool
جواب: b) float

۵. sort (مرتب کردن کد)

خطوط کد جابه‌جا شدن، کاربر مرتبشون میکنه (drag & drop)

lines: ["print(y)", "x = 5", "y = x * 2"]
مرتب: ["x = 5", "y = x * 2", "print(y)"]

🔐 جلوگیری از تقلب

۱. مقادیر تصادفی: هر بار عدد فرق کنه (x=5 یا x=7) ۲. ترتیب تصادفی: گزینه‌ها هر بار جابه‌جا بشن ۳. سؤالات متنوع: چند نسخه از هر سؤال ۴. بدون جواب در JSON: جواب‌ها در کد کمتر مشخص باشن

ولی واقعیت: هدف یادگیریه، نه امتحان. اوپن‌سورس = اعتماد.

🚀 نقشه راه

✅ فاز ۱ — MVP

  • طراحی کامل
  • index.html + style.css
  • app.js + progress.js + challenges.js
  • فصل ۱ تا ۵ با چالش‌ها
  • تست در مرورگر
  • انیمیشن‌ها و صداها
  • حالت موبایل
  • فصل‌های ۶ تا ۱۰
  • GitHub Pages deploy
  • ریسپانسیو کامل
  • فصل‌های پیشرفته

✅ فاز ۲ — آرکید

  • SPA Router (hash-based)
  • View pattern (home, map, lesson, exercises, challenges, result, profile, settings)
  • XP و لِوِل
  • استریک روزانه
  • سیستم انرژی
  • ماموریت‌های روزانه
  • فروشگاه بازی
  • پروفایل
  • تنظیمات
  • CSS مدولار (tokens, base, arcade, components, pages)
  • مدیریت وضعیت با versioning
  • مهاجرت داده‌های قدیمی

🔜 فاز ۳ — رشد

  • جدول امتیازات (leaderboard)
  • چالش‌های چندنفره
  • دستاورد‌های جدید
  • ترجمه انگلیسی کامل
  • PWA (قابل نصب روی موبایل)
  • حالت آفلاین