pyisu/README.md

Auth Learning App

Полнофункциональное SPA приложение для обучения с системой авторизации, избранными курсами и отслеживанием прогресса

📋 О проекте

Auth Learning App - это современное веб-приложение для управления обучающими курсами, построенное на микросервисной архитектуре. Приложение предоставляет полный цикл работы с курсами: от регистрации пользователей до отслеживания прогресса обучения.

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

• 🔐 Безопасная аутентификация с JWT токенами
• 📚 Каталог курсов с фильтрацией по уровням сложности
• ⭐ Система избранных курсов для сохранения интересных материалов
• 📊 Отслеживание прогресса с визуализацией выполнения
• 🐳 Полная контейнеризация с Docker Compose
• 📱 Адаптивный SPA интерфейс на чистом JavaScript

🏗️ Архитектура и стек технологий

Бэкенд (FastAPI 3.11+)

• FastAPI - высокопроизводительный веб-фреймворк с автоматической документацией
• SQLAlchemy ORM + Alembic для работы с базой данных и миграциями
• PostgreSQL 15 - реляционная база данных
• JWT аутентификация с access/refresh токенами
• Pydantic для валидации данных
• Bcrypt для безопасного хеширования паролей

Фронтенд (Vanilla JavaScript SPA)

• Чистый JavaScript без фреймворков
• SPA архитектура с History API роутингом
• Компонентный подход с модулями ES6
• LocalStorage для сохранения сессии
• Адаптивный дизайн с современным CSS (Flexbox/Grid)

Инфраструктура

• Docker + Docker Compose - контейнеризация и оркестрация
• Nginx - веб-сервер для фронтенда и прокси к API
• PostgreSQL с volume для сохранения данных

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

auth-learning-app/
├── backend/                      # FastAPI приложение
│   ├── app/                     # Основной код приложения
│   │   ├── models.py           # Модели базы данных
│   │   ├── schemas.py          # Pydantic схемы
│   │   ├── crud.py             # CRUD операции
│   │   ├── routes/             # API endpoints
│   │   │   ├── auth.py        # Аутентификация
│   │   │   ├── courses.py     # Курсы
│   │   │   ├── favorites.py   # Избранные курсы
│   │   │   ├── progress.py    # Прогресс обучения
│   │   │   └── stats.py       # Статистика
│   │   └── main.py            # Точка входа
│   ├── requirements.txt        # Python зависимости
│   └── Dockerfile             # Контейнеризация Python
├── frontend/                   # JavaScript SPA
│   ├── public/index.html      # Единственный HTML файл
│   ├── src/                   # Исходный код SPA
│   │   ├── main.js           # Точка входа
│   │   ├── router.js         # Маршрутизация SPA
│   │   ├── api/              # API клиенты
│   │   ├── components/       # UI компоненты
│   │   ├── views/            # Страницы приложения
│   │   └── utils/            # Вспомогательные функции
│   ├── css/                  # Стили
│   ├── Dockerfile           # Контейнеризация Nginx
│   └── nginx.conf           # Конфигурация Nginx
├── nginx/                    # Конфигурация Nginx
├── docker-compose.yml       # Оркестрация контейнеров
├── .env.example             # Пример переменных окружения
├── docker-cleanup.sh        # Скрипт очистки Docker
└── README.md               # Эта документация

🚀 Быстрый старт

Требования

• Docker 20.10+
• Docker Compose 2.0+
• Git (для клонирования репозитория)

Установка и запуск

1. Клонируйте репозиторий (если нужно)

   git clone <repository-url>
   cd auth-learning-app
   

2. Настройте переменные окружения

   cp .env.example .env
   # Отредактируйте .env при необходимости
   

3. Запустите приложение

   docker-compose up --build
   

4. Приложение будет доступно по адресам:

   • 🌐 Frontend: http://localhost
   • 📚 API Documentation: http://localhost:8000/docs
   • 📖 ReDoc Documentation: http://localhost:8000/redoc
   • 🗄️ PostgreSQL: localhost:5432

Тестовые учетные данные

• Email: test@example.com
• Password: Test1234

📚 Функционал

Аутентификация и регистрация

• ✅ Регистрация новых пользователей с валидацией email
• ✅ Вход в систему с JWT токенами
• ✅ Защищенные маршруты с проверкой авторизации
• ✅ Выход из системы с инвалидацией токенов

Управление курсами

• ✅ Просмотр каталога курсов
• ✅ Фильтрация по уровню сложности (beginner/intermediate/advanced)
• ✅ Поиск и детальный просмотр курсов
• ✅ Карточки курсов с полной информацией

Избранные курсы

• ✅ Добавление курсов в избранное
• ✅ Удаление курсов из избранного
• ✅ Отдельная страница "My Favorites"
• ✅ Визуальная индикация в карточках курсов

Отслеживание прогресса

• ✅ Отслеживание прогресса по каждому курсу
• ✅ Визуализация с помощью прогресс-бара
• ✅ Автоматический расчет процента выполнения
• ✅ Страница "My Progress" с обзором всех курсов
• ✅ Возможность обновления прогресса

Статистика

• ✅ Общая статистика системы
• ✅ Количество пользователей и курсов
• ✅ Самый популярный курс

🔧 API Endpoints

Аутентификация

• POST /api/auth/register - Регистрация нового пользователя
• POST /api/auth/login - Вход в систему
• POST /api/auth/logout - Выход из системы
• GET /api/auth/me - Получение информации о текущем пользователе

Курсы

• GET /api/courses - Получение списка курсов (с фильтрацией по level)
• GET /api/courses/{id} - Получение детальной информации о курсе

Избранные курсы

• GET /api/favorites/ - Получение списка избранных курсов
• POST /api/favorites/ - Добавление курса в избранное
• DELETE /api/favorites/{course_id} - Удаление курса из избранного

Прогресс обучения

• GET /api/progress/ - Получение всего прогресса пользователя
• GET /api/progress/{course_id} - Получение прогресса по конкретному курсу
• POST /api/progress/{course_id} - Обновление прогресса по курсу
• DELETE /api/progress/{course_id} - Удаление записи прогресса

Статистика

• GET /api/stats - Получение общей статистики системы

🐳 Docker Cleanup

Для управления Docker ресурсами проекта используйте скрипт docker-cleanup.sh:

Уровни очистки:

1. Мягкая очистка (контейнеры и сети проекта):

   ./docker-cleanup.sh --soft
   

2. Средняя очистка (контейнеры, сети и образы без тегов) - рекомендуется:

   ./docker-cleanup.sh --medium
   

3. Полная очистка (контейнеры, сети, образы, volumes и build cache) - удаляет БД!:

   ./docker-cleanup.sh --all
   

Ручная очистка:

# Остановить и удалить контейнеры проекта
docker-compose down

# Удалить все неиспользуемые образы
docker image prune -a

# Удалить все неиспользуемые volumes (ВНИМАНИЕ: удалит данные БД!)
docker volume prune

# Очистить build cache
docker builder prune

🛠️ Разработка

Запуск в режиме разработки

1. Запустите только базу данных:

   docker-compose up postgres -d
   

2. Запустите бэкенд локально:

   cd backend
   pip install -r requirements.txt
   python -m app.main
   

3. Запустите фронтенд локально:

   cd frontend
   # Используйте live-server или любой другой HTTP сервер
   python -m http.server 8080
   

Миграции базы данных

Приложение использует автоматическое создание таблиц через SQLAlchemy. Для продвинутых сценариев миграций:

# Создать новую миграцию
docker-compose exec backend alembic revision --autogenerate -m "description"

# Применить миграции
docker-compose exec backend alembic upgrade head

# Откатить миграцию
docker-compose exec backend alembic downgrade -1

📈 Возможные улучшения

Ближайшие планы:

1. Уведомления - система уведомлений о новых курсах и достижениях
2. Комментарии к курсам - возможность обсуждения материалов
3. Рейтинги курсов - система оценок и отзывов
4. Административная панель - управление курсами и пользователями

Технические улучшения:

1. Кэширование - Redis для кэширования частых запросов
2. Фоновые задачи - Celery для обработки асинхронных задач
3. Мониторинг - Prometheus + Grafana для мониторинга
4. Логирование - централизованная система логов

Безопасность:

1. Rate limiting - ограничение частоты запросов
2. Двухфакторная аутентификация
3. Роли пользователей - администратор, модератор, студент
4. HTTPS в продакшене

🐛 Поиск и устранение неисправностей

Распространенные проблемы:

1. Порт уже используется:

   # Найдите процесс, использующий порт
   sudo lsof -i :80
   sudo lsof -i :8000
   sudo lsof -i :5432
   
   # Остановите процесс или измените порты в docker-compose.yml
   

2. Проблемы с базой данных:

   # Проверьте статус PostgreSQL
   docker-compose logs postgres
   
   # Пересоздайте volume (удалит данные!)
   docker-compose down -v
   docker-compose up -d
   

3. Проблемы с зависимостями:

   # Пересоберите образы
   docker-compose build --no-cache
   docker-compose up -d
   

Логи:

# Просмотр логов всех сервисов
docker-compose logs -f

# Просмотр логов конкретного сервиса
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres

📄 Лицензия

Этот проект создан для образовательных целей. Используйте его как основу для своих проектов или для изучения современных веб-технологий.

🤝 Вклад в проект

Если вы хотите внести свой вклад:

1. Форкните репозиторий
2. Создайте ветку для своей функции (git checkout -b feature/amazing-feature)
3. Зафиксируйте изменения (git commit -m 'Add amazing feature')
4. Запушьте ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

---

Сделано с ❤️ для обучения современным веб-технологиям