mnemo_cards/mnemo_cards_web_v2/README.md

# mnemo_cards_web_v2

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

[![Version](https://img.shields.io/badge/version-1.0.12+13-blue.svg)](pubspec.yaml)
[![Flutter](https://img.shields.io/badge/Flutter-3.9.2+-02569B?logo=flutter)](https://flutter.dev)
[![Platform](https://img.shields.io/badge/platform-Web-orange.svg)](https://flutter.dev/web)

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

## 📖 Содержание

- [Описание](#-описание)
- [Быстрый старт](#-быстрый-старт)
- [Архитектура](#️-архитектура)
- [Функциональность](#-функциональность)
- [Технологии](#-технологии)
- [Структура проекта](#-структура-проекта)
- [Разработка](#-разработка)
- [Тестирование](#-тестирование)
- [Деплой](#-деплой)
- [Дополнительная документация](#-дополнительная-документация)

## 🎯 Описание

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

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

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

### Требования
- Flutter SDK 3.9.2+
- Dart SDK 3.9.2+
- Chrome (для запуска в режиме разработки)
- Backend сервер (см. [mnemo_cards_backend](../mnemo_cards_backend))

### Установка

```bash
# 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](./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` и т.д.:

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

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

### Работа с Firebase

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

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

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

### Линтинг

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

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

### Отладка

```bash
# Запуск с 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.

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

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

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

```bash
# Все тесты
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](.cursor/rules/write-tests.mdc)

## 🚀 Деплой

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

```bash
# Из корня проекта 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

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

```bash
# 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](./deploy/README.md)

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

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

### Backend
- [mnemo_cards_backend/README.md](../mnemo_cards_backend/README.md) — Backend документация
- `open_api.yaml` — API спецификация

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

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

- [Flutter Documentation](https://docs.flutter.dev/)
- [yx_scope Documentation](packages/yx/city-services-pub/yx_scope/README.md)
- [yx_state Documentation](packages/yx/city-services-pub/yx_state/README.md)
- [GoRouter Documentation](https://pub.dev/packages/go_router)
- [Freezed Documentation](https://pub.dev/packages/freezed)

## 📄 Лицензия

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

## 👨‍💻 Автор

Dmitry - [mnemo-cards.online](https://mnemo-cards.online)

---

<div align="center">
  
**mnemo_cards_web_v2** | Made with ❤️ using Flutter

</div>