338 lines
15 KiB
Markdown
338 lines
15 KiB
Markdown
# Auth Learning App
|
||
|
||
<div align="center">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
**Полнофункциональное SPA приложение для обучения с системой авторизации, избранными курсами и отслеживанием прогресса**
|
||
|
||
</div>
|
||
|
||
## 📋 О проекте
|
||
|
||
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. **Клонируйте репозиторий (если нужно)**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd auth-learning-app
|
||
```
|
||
|
||
2. **Настройте переменные окружения**
|
||
```bash
|
||
cp .env.example .env
|
||
# Отредактируйте .env при необходимости
|
||
```
|
||
|
||
3. **Запустите приложение**
|
||
```bash
|
||
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. **Мягкая очистка** (контейнеры и сети проекта):
|
||
```bash
|
||
./docker-cleanup.sh --soft
|
||
```
|
||
|
||
2. **Средняя очистка** (контейнеры, сети и образы без тегов) - **рекомендуется**:
|
||
```bash
|
||
./docker-cleanup.sh --medium
|
||
```
|
||
|
||
3. **Полная очистка** (контейнеры, сети, образы, volumes и build cache) - **удаляет БД!**:
|
||
```bash
|
||
./docker-cleanup.sh --all
|
||
```
|
||
|
||
### Ручная очистка:
|
||
|
||
```bash
|
||
# Остановить и удалить контейнеры проекта
|
||
docker-compose down
|
||
|
||
# Удалить все неиспользуемые образы
|
||
docker image prune -a
|
||
|
||
# Удалить все неиспользуемые volumes (ВНИМАНИЕ: удалит данные БД!)
|
||
docker volume prune
|
||
|
||
# Очистить build cache
|
||
docker builder prune
|
||
```
|
||
|
||
## 🛠️ Разработка
|
||
|
||
### Запуск в режиме разработки
|
||
|
||
1. **Запустите только базу данных:**
|
||
```bash
|
||
docker-compose up postgres -d
|
||
```
|
||
|
||
2. **Запустите бэкенд локально:**
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
python -m app.main
|
||
```
|
||
|
||
3. **Запустите фронтенд локально:**
|
||
```bash
|
||
cd frontend
|
||
# Используйте live-server или любой другой HTTP сервер
|
||
python -m http.server 8080
|
||
```
|
||
|
||
### Миграции базы данных
|
||
|
||
Приложение использует автоматическое создание таблиц через SQLAlchemy. Для продвинутых сценариев миграций:
|
||
|
||
```bash
|
||
# Создать новую миграцию
|
||
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. **Порт уже используется:**
|
||
```bash
|
||
# Найдите процесс, использующий порт
|
||
sudo lsof -i :80
|
||
sudo lsof -i :8000
|
||
sudo lsof -i :5432
|
||
|
||
# Остановите процесс или измените порты в docker-compose.yml
|
||
```
|
||
|
||
2. **Проблемы с базой данных:**
|
||
```bash
|
||
# Проверьте статус PostgreSQL
|
||
docker-compose logs postgres
|
||
|
||
# Пересоздайте volume (удалит данные!)
|
||
docker-compose down -v
|
||
docker-compose up -d
|
||
```
|
||
|
||
3. **Проблемы с зависимостями:**
|
||
```bash
|
||
# Пересоберите образы
|
||
docker-compose build --no-cache
|
||
docker-compose up -d
|
||
```
|
||
|
||
### Логи:
|
||
|
||
```bash
|
||
# Просмотр логов всех сервисов
|
||
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
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**Сделано с ❤️ для обучения современным веб-технологиям**
|
||
|
||
</div> |