mnemo_cards/mnemo_cards_web_v2

mnemo_cards_web_v2

Flutter web приложение для изучения языков с использованием yx_scope и yx_state.

🌐 Важно: Этот проект предназначен ТОЛЬКО для web платформы и работает на удаленном сервере.

📖 Содержание

• Описание
• Быстрый старт
• Архитектура
• Функциональность
• Технологии
• Структура проекта
• Разработка
• Тестирование
• Деплой
• Дополнительная документация

🎯 Описание

mnemo_cards_web_v2 — это современное веб-приложение для изучения иностранных языков, портированное с мобильной версии. Приложение использует карточки (flashcards), мини-игры и систему достижений для эффективного запоминания слов и фраз.

Ключевые особенности:

• 🎮 Интерактивные игры для запоминания слов
• 📊 Детальная статистика прогресса
• 🎴 Система карточек с озвучкой
• 🌓 Светлая и темная тема
• 🔐 Авторизация через Google и Telegram
• 👤 Гостевой режим
• 💰 Система покупок и подписок
• 🏆 Достижения и задания
• 💬 Встроенный чат

⚡ Быстрый старт

Требования

• Flutter SDK 3.9.2+
• Dart SDK 3.9.2+
• Chrome (для запуска в режиме разработки)
• Backend сервер (см. mnemo_cards_backend)

Установка

# 1. Установите зависимости
flutter pub get

# 2. Сгенерируйте код (freezed, json_serializable)
flutter pub run build_runner build --delete-conflicting-outputs

# 3. Запустите приложение в Chrome
flutter run -d chrome

Полная инструкция: QUICK_START.md

🏗️ Архитектура

Приложение построено на базе Clean Architecture с использованием yx_scope для Dependency Injection и yx_state для управления состоянием.

Скоупы (Dependency Injection)

🌐 AppScope

Корневой скоуп, живет все время работы приложения:

• Router (GoRouter) — навигация и роутинг
• Analytics (FirebaseAnalytics) — аналитика событий
• Auth (AuthService) — авторизация через Google/Telegram
• Storage (SharedPreferences) — локальное хранилище

👤 UserScope

Пользовательский скоуп, создается при запуске (для гостя или авторизованного пользователя):

• Packs — управление темами и карточками
• Games — игровая логика
• Statistics — статистика прогресса
• Profile — профиль пользователя
• Purchases — покупки и подписки
• Tasks — система заданий
• Favorites — избранные карточки
• Chat — чат-модуль

💡 Примечание: UserScope создается сразу при запуске и НЕ удаляется при logout, только меняется состояние.

State Management (yx_state)

Все состояние приложения управляется через State Managers:

State Manager	Назначение
ThemeStateManager	Управление темой (светлая/темная)
UserStateManager	Состояние пользователя (гость/авторизован)
PacksStateManager	Загрузка и управление темами/карточками
GamesStateManager	Состояние активных игр
StatisticsStateManager	Статистика и прогресс
ProfileStateManager	Данные профиля
PurchaseStateManager	Покупки и подписки
TasksStateManager	Задания пользователя
FavoritesStateManager	Избранные карточки

✨ Функциональность

Реализовано ✅

• 🔐 Авторизация через Google и Telegram
• 👤 Гостевой режим с ограниченным функционалом
• 📚 Просмотр и изучение тем (паков)
• 🎮 Мини-игры для запоминания:
  • Сопоставление (Match)
  • Ввод букв (Input Letters)
  • Выбор ответа (Multiple Choice)
  • Матрица слов (Matrix)
• 🎴 Карточки с перелистыванием (Card Flipper)
• 🔊 Озвучка карточек (Text-to-Speech)
• 📊 Детальная статистика:
  • График прогресса
  • Статистика по словам
  • Достижения
  • История изучения
• 🌓 Переключение темы (светлая/темная)
• 💰 Система покупок и подписок
• 🏆 Система заданий и достижений
• 💬 Встроенный чат
• 📱 Адаптивный дизайн

В разработке 🚧

• 📈 Расширенная аналитика
• 🔄 Синхронизация между устройствами
• 🎯 Персонализированные рекомендации
• 🗣️ Дополнительные типы игр

🛠 Технологии

Core

• Flutter 3.9.2+ — UI фреймворк
• Dart 3.9.2+ — язык программирования

Architecture & State Management

• yx_scope (1.1.2) — Dependency Injection
• yx_state (1.0.0) — State Management
• go_router (14.2.0) — Роутинг и навигация

Backend Integration

• dio (5.3.3) — HTTP клиент
• Custom API client для backend

Firebase

• firebase_core (3.3.0) — Core Firebase
• firebase_auth (5.3.1) — Авторизация
• firebase_analytics (11.2.1) — Аналитика
• firebase_crashlytics (4.0.4) — Отчеты о сбоях
• firebase_remote_config (5.4.7) — Удаленная конфигурация

Code Generation

• freezed (3.2.3) — Immutable классы и unions
• json_serializable (6.8.0) — JSON сериализация
• build_runner (2.4.13) — Генерация кода

UI & UX

• flutter_screenutil (5.9.0) — Адаптивная верстка
• cached_network_image (3.4.1) — Кэширование изображений
• shimmer (3.0.0) — Skeleton loading
• auto_size_text (3.0.0) — Автоматический размер текста
• fl_chart (0.68.0) — Графики и диаграммы
• audioplayers (6.1.0) — Воспроизведение аудио

Additional

• shared_preferences (2.2.3) — Локальное хранилище
• google_sign_in (6.2.1) — Google авторизация
• telegram_web_app (0.3.3) — Telegram Web App API
• url_launcher (6.2.6) — Открытие ссылок
• package_info_plus (8.0.0) — Информация о пакете

Common Packages

• mnemo_cards_common — Общие модели и утилиты
• mnemo_cards_frontend_common — Общий функционал для фронтенда
• mnemo_cards_chat — Чат-модуль
• payloads_shared, bridge_core, game_tests — Игровые модули

📁 Структура проекта

mnemo_cards_web_v2/
│
├── lib/
│   ├── main.dart                      # Точка входа приложения
│   ├── app.dart                       # Главный виджет приложения
│   ├── firebase_options.dart          # Firebase конфигурация
│   │
│   ├── di/                            # Dependency Injection (yx_scope)
│   │   ├── app_scope/                 # Корневой скоуп
│   │   │   ├── app_scope.dart
│   │   │   ├── app_scope_container.dart
│   │   │   ├── app_scope_holder.dart
│   │   │   └── modules/               # Модули AppScope
│   │   │       ├── analytics_module.dart
│   │   │       ├── auth_module.dart
│   │   │       ├── router_module.dart
│   │   │       └── storage_module.dart
│   │   │
│   │   └── user_scope/                # Пользовательский скоуп
│   │       ├── user_scope.dart
│   │       ├── user_scope_container.dart
│   │       ├── user_scope_holder.dart
│   │       └── modules/               # Модули UserScope
│   │           ├── packs_module.dart
│   │           ├── games_module.dart
│   │           ├── statistics_module.dart
│   │           ├── profile_module.dart
│   │           ├── purchase_module.dart
│   │           ├── tasks_module.dart
│   │           ├── favorites_module.dart
│   │           ├── chat_module.dart
│   │           └── ...
│   │
│   ├── domain/                        # Бизнес-логика
│   │   ├── services/                  # Сервисы
│   │   │   ├── api_service.dart
│   │   │   ├── auth_service.dart
│   │   │   ├── analytics_service.dart
│   │   │   └── ...
│   │   │
│   │   └── state/                     # State Managers
│   │       ├── theme_state_manager.dart
│   │       ├── user_state_manager.dart
│   │       ├── packs_state_manager.dart
│   │       ├── games_state_manager.dart
│   │       └── ...
│   │
│   ├── presentation/                  # UI слой
│   │   ├── router/                    # Роутинг
│   │   │   └── app_router.dart
│   │   │
│   │   ├── theme/                     # Темы оформления
│   │   │   ├── app_theme.dart
│   │   │   └── app_colors.dart
│   │   │
│   │   ├── pages/                     # Страницы приложения
│   │   │   ├── auth/                  # Авторизация
│   │   │   ├── home/                  # Главная (темы)
│   │   │   ├── games/                 # Список игр
│   │   │   ├── game/                  # Игровая страница
│   │   │   ├── pack_details/          # Детали темы
│   │   │   ├── statistics/            # Статистика
│   │   │   ├── profile/               # Профиль
│   │   │   ├── purchase/              # Покупки
│   │   │   ├── tasks/                 # Задания
│   │   │   └── test/                  # Тестирование
│   │   │
│   │   └── widgets/                   # Переиспользуемые виджеты
│   │       ├── main_shell.dart        # Основной shell с навигацией
│   │       ├── pack_card.dart         # Карточка темы
│   │       ├── game_card.dart         # Карточка игры
│   │       ├── card_flipper/          # Flipper карточек
│   │       ├── game/                  # Игровые виджеты
│   │       ├── loading/               # Shimmer загрузки
│   │       └── ...
│   │
│   └── utils/                         # Утилиты
│       ├── responsive.dart
│       ├── color_extension.dart
│       └── ...
│
├── test/                              # Тесты
│   ├── unit/                          # Unit тесты
│   ├── widget/                        # Widget тесты
│   └── integration/                   # Интеграционные тесты
│
├── web/                               # Web-специфичные файлы
│   ├── index.html
│   ├── manifest.json
│   └── icons/
│
├── deploy/                            # Конфигурация деплоя
│   ├── nginx.conf
│   └── README.md
│
├── icons/                             # Иконки приложения
├── fonts/                             # Шрифты (Nunito)
│
├── pubspec.yaml                       # Зависимости
├── analysis_options.yaml              # Lint правила
├── README.md                          # Этот файл
├── QUICK_START.md                     # Быстрый старт
├── project_config.md                  # Конфигурация проекта
└── open_api.yaml                      # API спецификация

🔧 Разработка

Генерация кода

При изменении классов с аннотациями @freezed, @JsonSerializable и т.д.:

# Одноразовая генерация
flutter pub run build_runner build --delete-conflicting-outputs

# Автоматическая генерация при изменениях
flutter pub run build_runner watch --delete-conflicting-outputs

Работа с Firebase

# 1. Установите Firebase CLI
npm install -g firebase-tools

# 2. Авторизуйтесь
firebase login

# 3. Настройте проект
flutterfire configure

Линтинг

# Анализ кода
flutter analyze

# Исправление форматирования
dart format lib/ test/ -l 80

Отладка

# Запуск с hot reload
flutter run -d chrome

# Запуск с DevTools
flutter run -d chrome --observatory-port=8888

# Запуск с verbose логированием
flutter run -d chrome -v

API Integration

API сервера описано в open_api.yaml. Backend должен быть запущен локально или доступен по URL.

# Локальный backend
cd ../mnemo_cards_backend
./run_dev.sh

🧪 Тестирование

Запуск тестов

# Все тесты
flutter test

# Unit тесты
flutter test test/unit/

# Widget тесты
flutter test test/widget/

# С покрытием
flutter test --coverage

# Конкретный тест
flutter test test/unit/domain/state/theme_state_manager_test.dart

Правила тестирования

• ✅ Используйте yx_state и yx_scope в тестах
• ✅ Следуйте Clean Architecture
• ✅ Модулизируйте код и разбивайте на файлы
• ✅ Пишите unit-тесты для всех функциональностей
• ✅ Используйте mocktail для мокирования

См. также: .cursor/rules/write-tests.mdc

🚀 Деплой

Автоматический деплой

# Из корня проекта mnemo_cards_web_v2
./deploy.sh

Скрипт деплоя:

1. ✅ Собирает Flutter web app с оптимизацией -O4
2. ✅ Загружает на сервер 147.45.152.129
3. ✅ Настраивает Nginx для домена mnemo-cards.online
4. ✅ Настраивает SSL сертификаты (Let's Encrypt)
5. ✅ Настраивает firewall

Ручной деплой

# 1. Соберите приложение
flutter build web -O4 --release

# 2. Загрузите на сервер
rsync -avz --delete build/web/ user@server:/var/www/mnemo-cards/

# 3. Настройте Nginx (см. deploy/nginx.conf)

Подробнее: deploy/README.md

📚 Дополнительная документация

Внутренняя документация

• QUICK_START.md — Быстрый старт за 2 команды
• project_config.md — Конфигурация проекта
• deploy/README.md — Инструкция по деплою

Backend

• mnemo_cards_backend/README.md — Backend документация
• open_api.yaml — API спецификация

Правила разработки

• .cursor/rules/write-tests.mdc — Правила написания тестов
• .cursor/rules/mnemo-cards-web.mdc — Правила разработки веб-приложения

🔗 Полезные ссылки

• Flutter Documentation
• yx_scope Documentation
• yx_state Documentation
• GoRouter Documentation
• Freezed Documentation

📄 Лицензия

Proprietary - все права защищены.

👨‍💻 Автор

Dmitry - mnemo-cards.online

---

mnemo_cards_web_v2 | Made with ❤️ using Flutter