Старт
This commit is contained in:
338
README.md
Normal file
338
README.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# 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>
|
||||
Reference in New Issue
Block a user