Dmitry
889784e11f
Some checks are pending
Backend CI / test (push) Waiting to run
Backend CI / build (push) Blocked by required conditions
Web App CI / test (push) Waiting to run
Web App CI / build (push) Blocked by required conditions
Deploy Admin Panel / Deploy Admin Panel (push) Waiting to run
Deploy Admin Panel / Admin Panel Verification (push) Blocked by required conditions
Deploy Mnemo Cards / Deploy Backend (push) Waiting to run
Deploy Mnemo Cards / Deploy Web App (push) Blocked by required conditions
Deploy Mnemo Cards / Final Verification (push) Blocked by required conditions
449 lines
18 KiB
Markdown
449 lines
18 KiB
Markdown
# mnemo_cards_web_v2
|
||
|
||
Flutter web приложение для изучения языков с использованием **yx_scope** и **yx_state**.
|
||
|
||
[](pubspec.yaml)
|
||
[](https://flutter.dev)
|
||
[](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>
|