mnemo_cards/mnemo_cards_web_v2/DEV_SETUP.md

🚀 Быстрый старт для разработки

Предварительные требования

• ✅ Flutter SDK установлен
• ✅ Dart SDK установлен
• ✅ Chrome браузер

📋 Пошаговая инструкция

1️⃣ Запустите Backend

Откройте первый терминал и запустите backend сервер:

cd /Users/dmitry/StudioProjects/mnemo_cards/mnemo_cards_backend
./run_dev.sh

Вы должны увидеть:

Starting Mnemo Cards Backend in development mode...
Backend will be available at http://localhost:8000

Server listening on http://0.0.0.0:8000

✅ Backend работает на http://localhost:8000

2️⃣ Запустите Frontend

Откройте второй терминал и запустите web приложение:

cd /Users/dmitry/StudioProjects/mnemo_cards/mnemo_cards_web_v2
flutter run -d chrome

Flutter автоматически откроет Chrome и приложение будет доступно на случайном порту.

3️⃣ Проверка работы

1. Приложение должно загрузиться без CORS ошибок
2. Откройте DevTools (F12) → Network
3. Проверьте запросы к backend (должны быть успешными)
4. Пройдите авторизацию через Google

🔧 Если возникли проблемы

CORS Error

Если вы видите CORS ошибку в консоли:

Access to XMLHttpRequest at 'http://localhost:8000/...' from origin '...' has been blocked by CORS policy

Решение:

1. Убедитесь что backend запущен
2. Перезапустите backend (может потребоваться после изменений)
3. Очистите кэш браузера (Ctrl+Shift+Delete)
4. Перезагрузите страницу (Ctrl+R)

Подробнее см. CORS_FIX.md

Connection Refused

Если запросы не проходят:

# Проверьте что backend работает
curl http://localhost:8000/games

Должен вернуть JSON с играми.

Backend не запускается

# Убедитесь что порт 8000 свободен
lsof -ti:8000

# Если порт занят, убейте процесс
kill -9 $(lsof -ti:8000)

# Или используйте другой порт
cd mnemo_cards_backend
dart run lib/main.dart -a 0.0.0.0 -p 8001 --isar isar --workdir $(pwd)

И обновите ApiConfig.baseUrl на http://localhost:8001

📝 Конфигурация

API URL

Конфигурация находится в lib/domain/config/api_config.dart:

static String get baseUrl => const String.fromEnvironment(
  'API_BASE_URL',
  defaultValue: 'http://localhost:8000', // Для разработки
);

Для production используйте environment variable:

flutter run -d chrome --dart-define=API_BASE_URL=https://your-domain.com

Telegram Bot Deep Link

Для работы веб-инициированного входа через Telegram можно переопределить имя бота:

flutter run -d chrome \
  --dart-define=API_BASE_URL=http://localhost:8000 \
  --dart-define=TELEGRAM_BOT_USERNAME=mnemo_cards_bot

По умолчанию используется mnemo_cards_bot.
Deep-link генерируется через https://t.me/<username>?start=login_<code>.

CORS настройки

CORS настроен в mnemo_cards_backend/lib/api/mnemo_shelf.dart:

final corsConfig = {
  'Access-Control-Allow-Origin': '*',  // Для разработки - разрешены все origins
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS',
  'Access-Control-Allow-Headers': '...',
};

⚠️ Для production замените '*' на конкретный домен!

🏗️ Структура проекта

mnemo_cards_web_v2/
├── lib/
│   ├── di/              # Dependency Injection (yx_scope)
│   ├── domain/          # Business logic, services, state
│   ├── presentation/    # UI, pages, widgets
│   └── main.dart        # Entry point
├── test/                # Unit & integration tests
├── web/                 # Web-specific files
└── pubspec.yaml         # Dependencies

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

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

flutter test

Запуск конкретного теста:

flutter test test/domain/services/http_repository_test.dart

🔍 Отладка

Flutter DevTools

flutter run -d chrome --observatory-port=9999

Затем откройте: http://localhost:9999/

Backend логи

Backend выводит все запросы в консоль:

[app] GET /games
[app] POST /user/create

Network Inspector

1. Откройте DevTools (F12)
2. Вкладка Network
3. Фильтр: XHR
4. Смотрите Headers и Response для каждого запроса

📚 Дополнительные ресурсы

• CORS_FIX.md - Подробное решение CORS проблем
• API_INTEGRATION_TEMP.md - Документация по API
• PLAN.md - План разработки и архитектура

🎯 Горячие клавиши

• r - Hot reload (без перезапуска)
• R - Hot restart (полный перезапуск)
• h - Помощь
• q - Выход

---

Удачной разработки! 🚀