Skip to content

DVDemon/frieren

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
backend
backend
 
 
bot
bot
 
 
docker
docker
 
 
frontend
frontend
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

Frieren - Система управления образовательным процессом МАИ

📋 Описание проекта

Frieren - комплексная система управления образовательным процессом для Московского авиационного института (МАИ). Система предназначена для автоматизации процессов обучения, включая регистрацию студентов, управление лекциями, отслеживание посещаемости, проверку домашних заданий, управление экзаменационными оценками и аналитику успеваемости.

Ключевые возможности

  • ✅ Управление студентами и преподавателями - Полноценная система управления пользователями
  • ✅ Регистрация на лекции через QR-код - Автоматическая регистрация посещаемости
  • ✅ Презентации лекций - Загрузка и скачивание презентаций лекций (PDF/PPTX) с хранением в БД
  • ✅ Система домашних заданий - Выдача, отправка и проверка домашних заданий с вариантами
  • ✅ Экзаменационные оценки - Управление оценками за экзамены с загрузкой PDF-файлов работ
  • ✅ AI-анализ кода - Автоматическая проверка на AI-генерацию с помощью OpenAI
  • ✅ Аналитика и отчеты - Статистика посещаемости и успеваемости
  • ✅ Интеграция с Google Sheets - Синхронизация данных с Google Таблицами
  • ✅ Telegram бот - Удобный интерфейс для студентов и преподавателей
  • ✅ Веб-интерфейс - Современный UI для преподавателей на Next.js

Компоненты системы

Проект состоит из трех основных компонентов:

  • Backend API (FastAPI) - RESTful API для управления данными
  • Frontend (Next.js) - веб-интерфейс для преподавателей
  • Telegram Bot (aiogram) - бот для взаимодействия со студентами и преподавателями

Дополнительные компоненты:

  • N8N - Автоматизация бизнес-процессов через workflows
  • RabbitMQ - Асинхронная обработка событий через очереди
  • PostgreSQL - Реляционная база данных

📑 Содержание

  1. Описание проекта
  2. Архитектура системы
  3. Бизнес-процессы
  4. Статистика проекта
  5. Технические особенности
  6. Структура проекта
  7. API Endpoints
  8. Безопасность
  9. Развертывание и настройка
  10. Тестирование
  11. Разработка
  12. Troubleshooting

🏗️ Архитектура системы

Общая архитектура

Система построена по микросервисной архитектуре с разделением на следующие компоненты:

┌─────────────────┐
│   Telegram Bot  │ (aiogram, Python)
│   (bot/)        │
└────────┬────────┘
         │ HTTP/Webhook
         │
┌────────▼────────┐      ┌──────────────┐
│   Backend API   │◄─────┤  PostgreSQL  │
│   (backend/)    │      │   Database   │
└────────┬────────┘      └──────────────┘
         │ HTTP/REST
         │
┌────────▼────────┐      ┌──────────────┐
│   Frontend      │      │     N8N      │
│   (frontend/)   │      │  Workflows   │
└─────────────────┘      └──────┬───────┘
                                │
                         ┌──────▼───────┐
                         │   RabbitMQ   │
                         │   (Queues)   │
                         └──────┬───────┘
                                │
                         ┌──────▼───────┐
                         │  N8N Trigger │
                         │  (Consumer)  │
                         └──────────────┘

Компоненты системы

1. Backend API (backend/)

  • Технологии: FastAPI, SQLAlchemy, PostgreSQL
  • Назначение: Предоставление RESTful API для всех операций с данными
  • Основные модули:
    • routers/ - API endpoints для различных сущностей
    • models.py - Типизированные модели данных (TypedDict)
    • database.py - Модели SQLAlchemy и подключение к БД
    • service.py - Основное приложение FastAPI

2. Frontend (frontend/)

  • Технологии: Next.js 14, React 18, TypeScript, Tailwind CSS
  • Назначение: Веб-интерфейс для преподавателей и администраторов
  • Архитектура: App Router (Next.js 14), Server-Side Rendering
  • Основные страницы:
    • / - Главная страница с общей статистикой
    • /students - Управление студентами (просмотр, редактирование, удаление)
    • /teachers - Управление преподавателями
    • /lectures - Управление лекциями (создание, редактирование, генерация QR-кодов, время начала, загрузка/скачивание презентаций)
    • /attendance - Просмотр посещаемости студентов
    • /attendance-chart - График посещаемости
    • /homework - Управление домашними заданиями
    • /homework-review - Проверка домашних заданий (табличное представление)
    • /homework-review-chat/[studentId] - Чат для оценки работ студента (новое представление)
    • /homework-stats - Статистика по домашним заданиям
    • /homework-variants - Управление вариантами домашних заданий
    • /pending-reviews - Список работ, ожидающих проверки
    • /student-variants/[id] - Варианты домашних заданий конкретного студента
    • /exam-grades - Управление экзаменационными оценками (с загрузкой PDF-файлов)
  • Компоненты:
    • QR-код генератор для лекций
    • Загрузка и скачивание презентаций лекций (PDF/PPTX)
    • Экспорт/импорт данных (JSON, Google Sheets)
    • Поиск студентов
    • Информация о вместимости лекций
    • Кнопки удаления с подтверждением
    • Чат-интерфейс для оценки работ студентов
    • Автоматическое определение просроченных работ (сравнение с deadline)

3. Telegram Bot (bot/)

  • Технологии: aiogram 3.x, aiohttp, OpenCV, dlib
  • Назначение: Интерактивный интерфейс для студентов и преподавателей
  • Основные функции для студентов:
    • Регистрация в системе
    • Check-in на лекции через QR-код
    • Отправка домашних заданий
    • Получение расписания лекций (с временем начала)
    • Получение материалов лекций (включая скачивание презентаций PDF/PPTX)
    • Проверка вместимости лекций
    • Получение информации о домашних заданиях
    • Получение информации об успеваемости
    • Автоматическое получение уведомлений об оценках в Telegram
  • Основные функции для преподавателей:
    • Проверка домашних заданий
    • Подсчет студентов на лекции (через анализ фотографии)
    • Обновление вместимости лекций
  • Особенности UX:
    • Автоматический возврат к главному меню после завершения каждого сценария
    • FSM (Finite State Machine) для управления диалогами
    • Информативные сообщения об ошибках
    • Отображение времени начала лекций во всех сценариях
    • Автоматическое обновление chat_id при любом взаимодействии с ботом (через middleware)
  • Middleware:
    • Автоматическое обновление chat_id студента при любом сообщении
    • Работает асинхронно, не блокируя обработку сообщений
    • Поддерживает формат @username и user_{id}
    • Автоматическое обновление chat_id при любом взаимодействии с ботом (через middleware)
  • Middleware:
    • Автоматическое обновление chat_id студента при любом сообщении
    • Работает асинхронно, не блокируя обработку сообщений
    • Поддерживает формат @username и user_{id}

4. N8N Workflows (n8n_workflows/)

  • Назначение: Автоматизация бизнес-процессов
  • Workflows (автоматически импортируются при первом запуске):
    • CheckIn.json - Обработка регистрации на лекции (валидация времени, отправка в RabbitMQ)
    • Homework Submission.json - Обработка отправки домашних заданий с AI-анализом через OpenAI
    • Update Student Info Google Sheet.json - Синхронизация данных студентов с Google Sheets (потребление из RabbitMQ)
    • Update Student Info.json - Обновление информации о студентах
    • Import rating from Google.json - Импорт оценок из Google Sheets (по расписанию)

5. RabbitMQ

  • Назначение: Асинхронная обработка событий через очереди сообщений
  • Очереди:
    • checkin - Очередь для событий регистрации на лекции
  • Использование:
    • Producer: N8N workflow отправляет события check-in в очередь
    • Consumer: N8N workflow слушает очередь и обновляет Google Sheets
  • Преимущества: Разделение синхронных и асинхронных операций, надежность обработки, масштабируемость

6. База данных (PostgreSQL)

  • Схема: 8 основных таблиц
  • Особенности: Мягкое удаление, связи между сущностями, индексы

7. Инфраструктура (Docker)

  • Контейнеры: Backend, Frontend, Bot, PostgreSQL, N8N, RabbitMQ
  • Оркестрация: Docker Compose
  • Сеть: Bridge network (frieren_network) для изоляции сервисов
  • Volumes:
    • postgres_data - Данные PostgreSQL
    • n8n_data - Данные N8N workflows
  • Особенности:
    • Health checks для PostgreSQL
    • Автоматическая инициализация RabbitMQ с очередями
    • Volume для hot reload frontend при разработке
    • Отдельные docker-compose.yml файлы для каждого компонента

🔄 Бизнес-процессы

1. Регистрация студента

Студент → Telegram Bot → Ввод данных (ФИО, GitHub, группа)
    ↓
Backend API → Создание записи в БД
    ↓
Автоматическое назначение вариантов ДЗ
    ↓
Уведомление студента о назначенных вариантах

Summary: Процесс регистрации нового студента в системе. Студент вводит свои данные через Telegram-бота, система создает запись в базе данных и автоматически назначает варианты домашних заданий. Процесс синхронный, выполняется в реальном времени.

2. Check-in на лекцию

Студент → Telegram Bot → Сканирование QR-кода
    ↓
Извлечение секретного кода из QR (OpenCV)
    ↓
N8N Workflow → Валидация времени (8:50-9:15 МСК)
    ↓
Backend API → Поиск лекции по секретному коду
    ↓
Проверка вместимости лекции
    ↓
Создание записи посещаемости в БД
    ↓
Отправка сообщения в RabbitMQ (очередь "checkin")
    ↓
N8N Workflow (RabbitMQ Trigger) → Обновление Google Sheets
    ↓
Уведомление студента о результате (Telegram)

Использование RabbitMQ: После успешного создания записи посещаемости, событие отправляется в очередь checkin в RabbitMQ. Это позволяет асинхронно обработать обновление Google Sheets без блокировки основного процесса регистрации. Отдельный N8N workflow слушает очередь через RabbitMQ Trigger и обновляет данные в Google Sheets.

Summary: Процесс регистрации студента на лекцию через сканирование QR-кода. Включает валидацию времени, проверку вместимости и создание записи посещаемости. Использует RabbitMQ для асинхронного обновления Google Sheets, что обеспечивает быстрый отклик пользователю и надежную обработку данных в фоне.

3. Отправка домашнего задания

Студент → Telegram Bot → Ввод номера ДЗ и ссылки на GitHub
    ↓
N8N Workflow (Webhook) → Получение данных
    ↓
Поиск студента в БД по Telegram
    ↓
AI-анализ кода (OpenAI GPT-4) → Определение процента AI-генерации
    ↓
Создание записи homework_review в БД
    ↓
Уведомление студента и преподавателя (Telegram)

Summary: Процесс отправки домашнего задания студентом. Студент указывает номер задания и ссылку на GitHub-репозиторий. Система автоматически анализирует код на предмет AI-генерации с помощью OpenAI GPT-4 и создает запись для последующей проверки преподавателем. Процесс выполняется через N8N workflow для обеспечения надежности и возможности расширения функциональности.

4. Проверка домашнего задания

Вариант 1: Табличное представление

Преподаватель → Frontend (/homework-review) → Просмотр списка работ
    ↓
Выбор работы → Скачивание проекта из GitHub
    ↓
Проверка кода → Выставление оценки (0-100 баллов)
    ↓
Добавление комментариев
    ↓
Обновление записи homework_review в БД
    ↓
Автоматическое установление review_date
    ↓
Уведомление студента в Telegram (если есть chat_id)

Вариант 2: Чат-интерфейс

Преподаватель → Sidebar → "Чат со студентом" → Выбор студента
    ↓
Frontend (/homework-review-chat/[studentId]) → Отображение истории отправок
    ↓
Просмотр каждой отправки:
    - Номер задания и вариант
    - Ссылка на GitHub репозиторий
    - Ссылка на пример варианта
    - AI-score (процент AI-генерации)
    - Статус отправки (в срок / просрочено)
    - Комментарий студента
    ↓
Выставление оценки и комментария преподавателя
    ↓
Обновление записи homework_review в БД
    ↓
Автоматическое установление review_date
    ↓
Уведомление студента в Telegram (если есть chat_id)

Summary: Процесс проверки домашнего задания преподавателем. Доступны два представления:

  1. Табличное представление - классический список всех работ с фильтрацией и сортировкой
  2. Чат-интерфейс - интерактивный чат с историей отправок конкретного студента, отображающий все работы в хронологическом порядке с визуальным разделением сообщений студента и ответов преподавателя

При сохранении оценки автоматически устанавливается review_date, и если у студента есть chat_id, он получает уведомление в Telegram с оценкой и комментарием преподавателя.

5. Подсчет студентов на лекции

Преподаватель → Telegram Bot → Загрузка фото аудитории
    ↓
Обработка изображения (OpenCV + dlib)
    ↓
Подсчет лиц на фотографии (детекция лиц)
    ↓
Ввод номера лекции и максимальной вместимости
    ↓
Backend API → Обновление capacity лекции
    ↓
Отображение статистики (текущее/максимальное количество)

Summary: Процесс автоматического подсчета студентов на лекции с помощью компьютерного зрения. Преподаватель загружает фотографию аудитории, система использует библиотеки OpenCV и dlib для детекции лиц и подсчета количества студентов. Результат используется для обновления максимальной вместимости лекции и отображения статистики заполненности.

6. Управление вариантами домашних заданий

Преподаватель → Frontend → Создание домашнего задания
    ↓
Указание количества вариантов
    ↓
Массовое назначение вариантов студентам
    ↓
Автоматическое распределение (случайное)
    ↓
Сохранение в student_homework_variants

Summary: Процесс управления вариантами домашних заданий. Преподаватель создает домашнее задание и указывает количество вариантов. Система автоматически распределяет варианты между студентами случайным образом и сохраняет связи в базе данных. Это обеспечивает справедливое распределение вариантов и упрощает управление большим количеством студентов.

7. Управление экзаменационными оценками

Преподаватель → Frontend → Просмотр списка студентов
    ↓
Выбор студента → Ввод данных экзамена (дата, оценка, вариант)
    ↓
Опциональная загрузка PDF/PNG/JPG файла работы
    ↓
Создание записи exam_grade в БД
    ↓
Отображение оценок с возможностью редактирования
    ↓
Скачивание файлов работ при необходимости

Summary: Процесс управления экзаменационными оценками. Преподаватель может создавать, просматривать и редактировать оценки за экзамены для каждого студента. Система поддерживает загрузку и хранение PDF/PNG/JPG файлов экзаменационных работ в базе данных (BLOB). Все оценки связаны со студентами и могут быть экспортированы в Google Sheets вместе с другой информацией о студентах.

8. Управление презентациями лекций

Преподаватель → Frontend → Выбор лекции
    ↓
Загрузка файла презентации (PDF/PPTX, до 50MB)
    ↓
Backend API → Сохранение в presentation_blob (BLOB)
    ↓
Отображение статуса наличия презентации
    ↓
Студент → Telegram Bot → Запрос материалов лекции
    ↓
Backend API → Скачивание презентации
    ↓
Отправка файла студенту через Telegram

Summary: Процесс управления презентациями лекций. Преподаватель может загружать презентации лекций (PDF/PPTX) через веб-интерфейс. Файлы хранятся в базе данных в поле presentation_blob (BLOB, до 50MB). Студенты могут скачивать презентации через Telegram бота, запрашивая материалы лекции. Система автоматически определяет формат файла и отправляет его с правильным MIME-типом.

📊 Статистика проекта

Объем кода

  • Общее количество строк кода: ~16,245 строк
  • Python файлы: 20 файлов (~6,764 строк)
  • TypeScript/TSX файлы: 45 файлов (~9,481 строк)
  • Основные компоненты:
    • Backend: ~6,764 строк (Python)
    • Frontend: ~9,481 строк (TypeScript/TSX)
    • Bot: ~1,590 строк (Python)

Используемые библиотеки и технологии

Backend (Python)

  • fastapi - Веб-фреймворк для создания API
  • sqlalchemy - ORM для работы с базой данных
  • psycopg2-binary - PostgreSQL драйвер
  • pydantic - Валидация данных
  • uvicorn - ASGI сервер
  • openai - Интеграция с OpenAI API для AI-анализа
  • gspread - Работа с Google Sheets
  • oauth2client - OAuth для Google API
  • requests - HTTP клиент

Frontend (TypeScript/JavaScript)

  • next (14.0.0) - React фреймворк с App Router
  • react (18.x) - UI библиотека
  • react-dom (18.x) - React DOM рендеринг
  • typescript (5.x) - Типизация
  • tailwindcss (3.3.0) - CSS фреймворк для стилизации
  • lucide-react - Библиотека иконок
  • qrcode - Генерация QR-кодов для лекций
  • autoprefixer - Автоматическое добавление префиксов CSS
  • postcss - Обработка CSS

Bot (Python)

  • aiogram (>=3.0.0) - Telegram Bot API фреймворк
  • aiohttp (>=3.8.0) - Асинхронный HTTP клиент
  • Pillow (>=9.0.0) - Обработка изображений
  • qrcode (>=7.3.0) - Генерация и обработка QR-кодов
  • opencv-python (>=4.5.0) - Компьютерное зрение
  • dlib (>=19.24.0) - Детекция лиц
  • numpy (>=1.21.0) - Численные вычисления
  • python-dotenv (>=0.19.0) - Управление переменными окружения

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

  • PostgreSQL 15 - Реляционная база данных
  • Docker - Контейнеризация приложений
  • Docker Compose - Оркестрация контейнеров
  • N8N - Автоматизация workflows и интеграций
  • RabbitMQ 3-management - Очереди сообщений с веб-интерфейсом управления
  • wrk - Инструмент для нагрузочного тестирования (в load_test/)

Структура базы данных

Таблицы:

  1. students - Студенты (8 полей: id, year, full_name, telegram, github, group_number, chat_id, is_deleted)
  2. teachers - Преподаватели (4 поля: id, full_name, telegram, is_deleted)
  3. teacher_groups - Связь преподавателей с группами (3 поля: id, teacher_id, group_number)
  4. lectures - Лекции (9 полей: id, number, topic, date, start_time, secret_code, max_student, github_example, presentation_blob)
  5. attendance - Посещаемость (4 поля: id, student_id, lecture_id, present)
  6. homework - Домашние задания (7 полей: id, number, due_date, short_description, example_link, assigned_date, variants_count)
  7. homework_review - Проверка домашних заданий (10 полей: id, number, send_date, review_date, url, result, comments, student_id, local_directory, ai_percentage)
    • review_date автоматически устанавливается при сохранении оценки (result)
    • При сохранении оценки отправляется уведомление в Telegram студенту (если есть chat_id)
  8. student_homework_variants - Варианты ДЗ для студентов (4 поля: id, student_id, homework_id, variant_number)
  9. exam_grades - Экзаменационные оценки (6 полей: id, date, grade, variant_number, student_id, pdf_blob)

Всего: 9 таблиц, ~54 поля

Примечания:

  • Поле start_time в таблице lectures хранит время начала лекции в формате HH:MM (например, "09:00").
  • Поле presentation_blob в таблице lectures хранит презентации лекций в формате PDF/PPTX (BLOB, до 50MB).

🔧 Технические особенности

Backend

  1. Типизация данных

    • Использование TypedDict для строгой типизации
    • Валидация через Pydantic
    • Автоматическая генерация OpenAPI документации

  2. Управление соединениями с БД

    • Connection pooling (pool_size=1000)
    • LIFO стратегия для пула
    • Автоматический reconnect (pool_pre_ping)
    • Таймауты для предотвращения зависаний

  3. Обработка ошибок

    • Детальное логирование 422 ошибок
    • Graceful error handling
    • Валидация на уровне API и БД

  4. CORS и безопасность

    • Настройка CORS для фронтенда
    • Middleware для логирования запросов
    • Таймауты для длительных операций (15 минут)

Frontend

  1. Архитектура

    • Server-side rendering (SSR) через Next.js
    • Client-side routing
    • Компонентный подход

  2. API интеграция

    • Централизованный API клиент
    • Таймауты запросов (15 минут)
    • Обработка ошибок

  3. UI/UX

    • Адаптивный дизайн (Tailwind CSS)
    • Современный интерфейс
    • Интуитивная навигация

Bot

  1. FSM (Finite State Machine)

    • Управление состояниями диалогов
    • Разделение логики по состояниям
    • Очистка состояний после завершения

  2. Обработка изображений

    • Поддержка фото и файлов
    • Детекция QR-кодов (OpenCV)
    • Подсчет лиц (dlib)
    • Обработка различных форматов

  3. Интеграция с API

    • Асинхронные HTTP запросы
    • Обработка таймаутов
    • Retry логика

N8N Workflows

  1. Автоматизация процессов

    • Webhook триггеры
    • Валидация данных
    • Интеграция с OpenAI для AI-анализа
    • Обработка ошибок

  2. Интеграции

    • Google Sheets
    • Telegram уведомления
    • HTTP API вызовы
    • RabbitMQ (отправка и получение сообщений)

RabbitMQ

  1. Асинхронная обработка

    • Очередь checkin для событий регистрации на лекции
    • Durable очереди для надежности
    • Разделение синхронных и асинхронных операций

  2. Интеграция с N8N

    • Producer: N8N workflow отправляет события в очередь после успешного check-in
    • Consumer: N8N workflow слушает очередь через RabbitMQ Trigger
    • Обеспечивает надежную обработку обновлений Google Sheets в фоне

  3. Преимущества

    • Неблокирующая обработка длительных операций
    • Гарантия доставки сообщений
    • Возможность масштабирования обработчиков
    • Разделение ответственности между компонентами

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

frieren/
├── backend/                      # Backend API (FastAPI)
│   ├── src/
│   │   ├── routers/             # API endpoints
│   │   │   ├── attendance.py    # Посещаемость
│   │   │   ├── config.py        # Конфигурация
│   │   │   ├── export.py        # Экспорт данных
│   │   │   ├── google_sheet.py  # Интеграция с Google Sheets
│   │   │   ├── homework.py      # Домашние задания
│   │   │   ├── homework_review.py # Проверка ДЗ
│   │   │   ├── import_all.py    # Импорт данных
│   │   │   ├── lectures.py      # Лекции
│   │   │   ├── students.py      # Студенты
│   │   │   ├── student_homework_variants.py # Варианты ДЗ
│   │   │   ├── teachers.py      # Преподаватели
│   │   │   └── utils.py         # Утилиты
│   │   ├── models.py            # Типизированные модели (TypedDict)
│   │   ├── database.py          # SQLAlchemy модели и подключение
│   │   └── service.py           # FastAPI приложение
│   ├── requirements/
│   │   └── requirement.txt      # Python зависимости
│   ├── Dockerfile               # Docker образ backend
│   ├── docker-compose.yml       # Docker Compose для backend
│   ├── env.example              # Пример переменных окружения
│   └── README.md                # Документация backend
│
├── frontend/                    # Frontend (Next.js 14)
│   ├── src/
│   │   ├── app/                 # Страницы и роутинг (App Router)
│   │   │   ├── api/config/      # API route для конфигурации
│   │   │   ├── attendance/      # Страница посещаемости
│   │   │   ├── attendance-chart/# График посещаемости
│   │   │   ├── homework/        # Управление ДЗ
│   │   │   ├── homework-review/# Проверка ДЗ
│   │   │   ├── homework-stats/  # Статистика ДЗ
│   │   │   ├── homework-variants/# Варианты ДЗ
│   │   │   ├── lectures/       # Управление лекциями
│   │   │   ├── pending-reviews/ # Ожидающие проверки
│   │   │   ├── students/        # Управление студентами
│   │   │   ├── student-variants/# Варианты студента
│   │   │   ├── teachers/        # Управление преподавателями
│   │   │   ├── layout.tsx       # Основной layout
│   │   │   └── page.tsx         # Главная страница
│   │   ├── components/          # React компоненты
│   │   │   ├── BackendInfo.tsx  # Информация о backend
│   │   │   ├── DeleteLectureButton.tsx
│   │   │   ├── DeleteReviewButton.tsx
│   │   │   ├── ExportButton.tsx
│   │   │   ├── GoogleSheetExportButton.tsx
│   │   │   ├── GoogleSheetImportButton.tsx
│   │   │   ├── ImportButton.tsx
│   │   │   ├── LectureCapacityInfo.tsx
│   │   │   ├── QRCode.tsx       # Генерация QR-кодов
│   │   │   ├── Sidebar.tsx      # Боковая панель
│   │   │   ├── StudentAttendanceExportButton.tsx
│   │   │   ├── StudentExportButton.tsx
│   │   │   └── StudentSearch.tsx
│   │   ├── lib/
│   │   │   └── api.ts           # API клиент
│   │   ├── types/
│   │   │   └── index.ts        # TypeScript типы
│   │   └── config.js           # Конфигурация
│   ├── Dockerfile              # Docker образ frontend
│   ├── docker-compose.yml      # Docker Compose для frontend
│   ├── env.example             # Пример переменных окружения
│   ├── next.config.js          # Конфигурация Next.js
│   ├── package.json            # Node.js зависимости
│   ├── tailwind.config.js      # Конфигурация Tailwind CSS
│   ├── TESTING.md              # Документация по тестированию
│   └── README-Docker.md        # Документация по Docker
│
├── bot/                         # Telegram Bot (aiogram 3.x)
│   ├── app.py                  # Основной файл бота
│   ├── requirements/
│   │   └── requirements.txt    # Python зависимости
│   ├── Dockerfile              # Docker образ bot
│   ├── docker-compose.yml      # Docker Compose для bot
│   ├── env.example             # Пример переменных окружения
│   ├── check_bot_processes.sh  # Скрипт проверки процессов
│   └── stop_all_bots.sh        # Скрипт остановки ботов
│
├── docker/                      # Docker конфигурация (основная)
│   ├── docker-compose.yml      # Основной Docker Compose (production)
│   ├── docker-compose-dev.yml   # Docker Compose для разработки (локальная сборка)
│   ├── rabbitmq-definitions.json # Конфигурация RabbitMQ
│   ├── rabbitmq-init.sh        # Скрипт инициализации RabbitMQ
│   ├── n8n-import-workflows.sh # Скрипт импорта N8N workflows
│   ├── n8n_workflows/          # N8N workflows (для автоматического импорта)
│   │   ├── CheckIn.json
│   │   ├── Homework Submission.json
│   │   ├── Import rating from Google.json
│   │   ├── Update Student Info Google Sheet.json
│   │   └── Update Student Info.json
│   └── resources/               # Ресурсы (PDF лекций)
│       ├── lection_01.pdf
│       ├── lection_02.pdf
│       └── ...
│
├── n8n_workflows/               # N8N workflows (для автоматического импорта)
│   ├── CheckIn.json            # Обработка регистрации на лекции
│   ├── Homework Submission.json # Обработка отправки домашних заданий
│   ├── Update Student Info Google Sheet.json # Синхронизация с Google Sheets
│   ├── Update Student Info.json # Обновление информации о студентах
│   └── Import rating from Google.json # Импорт оценок из Google Sheets
│
├── load_test/                   # Нагрузочное тестирование
│   ├── load_test.sh            # Скрипт нагрузочного тестирования
│   └── script.lua              # Lua скрипт для wrk
│
└── README.md                    # Этот файл

🎯 Основные API Endpoints

Студенты

  • GET /api/students/ - Получить всех студентов (исключая удаленных)
  • POST /api/students/ - Создать студента
  • PUT /api/students/{id} - Обновить студента
  • DELETE /api/students/{id} - Удалить студента (мягкое удаление)
  • GET /api/students/by-telegram/{telegram} - Найти по Telegram
  • PUT /api/students/by-telegram/{telegram}/chat-id - Обновить chat_id студента (query параметр)
  • PUT /api/students/by-telegram/{telegram}/chat-id-body - Обновить chat_id студента (body параметр, используется ботом)
  • GET /api/students/stats - Статистика по студентам (баллы, посещаемость, AI-процент)

Лекции

  • GET /api/lectures/ - Получить все лекции (включая время начала и наличие презентации)
  • POST /api/lectures/ - Создать лекцию (с опциональным временем начала)
  • PUT /api/lectures/{id} - Обновить лекцию (включая время начала)
  • DELETE /api/lectures/{id} - Удалить лекцию
  • GET /api/lectures/{lecture_id} - Получить лекцию по ID
  • GET /api/lectures/by-secret-code/{code} - Найти по секретному коду (включая время начала)
  • GET /api/lectures/capacity/{lecture_number} - Проверить вместимость (включая время начала)
  • PUT /api/lectures/capacity/{lecture_number} - Обновить вместимость лекции
  • GET /api/lectures/{lecture_id}/presentation - Скачать презентацию лекции (PDF/PPTX)
  • GET /api/lectures/by-number/{lecture_number}/presentation - Скачать презентацию по номеру лекции
  • POST /api/lectures/{lecture_id}/presentation - Загрузить презентацию лекции (PDF/PPTX, до 50MB)
  • PUT /api/lectures/{lecture_id}/presentation - Обновить презентацию лекции (PDF/PPTX, до 50MB)

Посещаемость

  • GET /api/attendance/ - Получить все записи
  • POST /api/attendance/ - Записать посещаемость
  • PUT /api/attendance/{id} - Обновить запись

Домашние задания

  • GET /api/homework/ - Получить все задания
  • POST /api/homework/ - Создать задание
  • PUT /api/homework/{id} - Обновить задание

Проверка домашних заданий

  • GET /api/homework_review/ - Получить все проверки
  • GET /api/homework_review/pending - Получить ожидающие проверки
  • GET /api/homework_review/pending-by-teacher/{teacher_id} - Проверки для преподавателя
  • GET /api/homework_review/by-telegram/{telegram} - Получить проверки студента по Telegram
  • GET /api/homework_review/by-student/{student_id} - Получить все проверки студента по ID (для чата)
  • POST /api/homework_review/ - Создать проверку
  • PUT /api/homework_review/{id} - Обновить проверку (автоматически устанавливает review_date при сохранении оценки, отправляет уведомление в Telegram если у студента есть chat_id)
  • DELETE /api/homework_review/{id} - Удалить проверку
  • POST /api/homework_review/{id}/download - Скачать проект из GitHub
  • POST /api/homework_review/{id}/check-ai - Проверить код на AI-генерацию через OpenAI

Преподаватели

  • GET /api/teachers/ - Получить всех преподавателей (исключая удаленных)
  • POST /api/teachers/ - Создать преподавателя
  • PUT /api/teachers/{id} - Обновить преподавателя
  • DELETE /api/teachers/{id} - Удалить преподавателя (мягкое удаление)
  • GET /api/teachers/by-telegram/{telegram} - Найти по Telegram
  • GET /api/teachers/by-group/{group} - Найти по группе
  • GET /api/teachers/groups - Получить все связи преподавателей с группами
  • GET /api/teachers/{id}/groups - Получить группы преподавателя
  • POST /api/teachers/groups - Создать связь преподавателя с группой
  • PUT /api/teachers/groups/{id} - Обновить связь преподавателя с группой
  • DELETE /api/teachers/groups/{id} - Удалить связь преподавателя с группой
  • GET /api/teachers/{id}/stats - Статистика преподавателя (количество проверенных работ)

Варианты домашних заданий

  • GET /api/student-homework-variants/ - Получить все варианты
  • GET /api/student-homework-variants/student/{student_id} - Варианты студента
  • GET /api/student-homework-variants/homework/{homework_id} - Варианты для домашнего задания
  • GET /api/student-homework-variants/student/{student_id}/homework/{homework_id} - Вариант конкретного студента для конкретного ДЗ
  • POST /api/student-homework-variants/ - Создать вариант
  • POST /api/student-homework-variants/bulk - Массовое создание вариантов
  • PUT /api/student-homework-variants/bulk/{student_id} - Массовое обновление вариантов студента
  • PUT /api/student-homework-variants/{id} - Обновить вариант
  • DELETE /api/student-homework-variants/{id} - Удалить вариант

Экзаменационные оценки

  • GET /api/exam_grades/ - Получить все экзаменационные оценки
  • GET /api/exam_grades/{exam_grade_id} - Получить оценку по ID
  • GET /api/exam_grades/by-student/{student_id} - Получить оценки студента
  • POST /api/exam_grades/ - Создать оценку (JSON, без файла)
  • POST /api/exam_grades/with-pdf - Создать оценку с файлом (PDF, PNG, JPG, JPEG)
  • PUT /api/exam_grades/{exam_grade_id} - Обновить оценку (JSON)
  • PUT /api/exam_grades/{exam_grade_id}/pdf - Обновить файл работы (PDF, PNG, JPG, JPEG)
  • GET /api/exam_grades/{exam_grade_id}/pdf - Скачать файл работы
  • DELETE /api/exam_grades/{exam_grade_id} - Удалить оценку

Экспорт/Импорт

  • GET /api/export/all - Экспорт всех данных в JSON
  • POST /api/import/all - Импорт всех данных из JSON
  • GET /api/google-sheet/all - Экспорт всех данных в Google Sheets
  • POST /api/google-sheet/export-student-attendance - Экспорт посещаемости студентов в Google Sheets
  • POST /api/google-sheet/export-student - Экспорт данных студента в Google Sheets
  • POST /api/google-sheet/export-review - Экспорт проверок домашних заданий в Google Sheets
  • POST /api/google-sheet/import-ratings - Импорт оценок из Google Sheets

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

  • GET /api/config - Получить конфигурацию системы

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

  1. Мягкое удаление - Записи не удаляются физически, помечаются флагом is_deleted
  2. Валидация времени - Check-in возможен только в определенное время (8:50-9:15 МСК)
  3. Проверка прав доступа - Разделение функций для студентов и преподавателей
  4. Таймауты - Защита от зависаний и долгих запросов (15 минут для длительных операций)
  5. Логирование - Детальное логирование всех операций и ошибок
  6. CORS настройки - Настроены для безопасного взаимодействия frontend и backend
  7. Валидация данных - Pydantic валидация на уровне API
  8. Секретные коды - Использование секретных кодов для доступа к лекциям через QR
  9. Connection pooling - Защита от перегрузки базы данных (pool_size=1000)
  10. Health checks - Мониторинг состояния сервисов через Docker health checks

🚀 Развертывание и настройка

Требования

  • Docker 20.10+
  • Docker Compose 2.0+
  • Минимум 4GB RAM
  • Минимум 10GB свободного места на диске

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

  1. Клонируйте репозиторий:

    git clone <repository_url>
cd frieren

  2. Создайте и настройте .env файл:

    cd docker
cp .env.example .env
# Отредактируйте .env и настройте необходимые переменные
# Обязательно установите BOT_TOKEN!
nano .env  # или используйте любой редактор

  3. Запустите все сервисы:

    docker-compose up -d

  4. Проверьте статус:

    docker-compose ps
docker-compose logs -f

Важно: Перед первым запуском обязательно настройте BOT_TOKEN в файле .env!

Структура docker-compose.yml

Основной файл конфигурации находится в docker/docker-compose.yml и включает следующие сервисы:

Примечание: В production режиме используются готовые Docker образы (ddzuba/frieren_*:arm64). Для разработки с локальной сборкой используйте docker-compose-dev.yml.

1. Frontend

  • Контейнер: frieren-frontend
  • Образ: ddzuba/frieren_frontend:arm64 (готовый образ) или локальная сборка (в dev режиме)
  • Порт: 3000:3000
  • Переменные окружения:
    • BACKEND_URL=http://frieren-backend:8000
    • NODE_ENV=production
  • Volumes: ../frontend/src:/app/src (для hot reload)
  • Сеть: frieren_network

2. Backend

  • Контейнер: frieren-backend
  • Образ: ddzuba/frieren_backend:arm64 (готовый образ) или локальная сборка (в dev режиме)
  • Порт: 8000:8000
  • Переменные окружения:
    • DB_USER=frieren
    • DB_PASSWORD=frieren
    • DB_HOST=frieren_db
    • DB_PORT=5432
    • DB_NAME=frieren_db
    • GOOGLE_SHEET_ID - ID Google Таблицы (опционально, для экспорта/импорта данных)
  • Volumes: ./google:/app/google (файл credentials.json для Google Sheets API)
  • Зависимости: postgres (ждет готовности БД)
  • Сеть: frieren_network

3. Bot

  • Контейнер: frieren-bot
  • Образ: ddzuba/frieren_bot:arm64 (готовый образ) или локальная сборка (в dev режиме)
  • Переменные окружения:
    • BOT_TOKEN - токен Telegram бота (требует настройки)
    • API_BASE_URL=http://frieren-backend:8000/api
    • N8N_BASE_URL=http://frieren-n8n:5678
  • Volumes: ./resources:/app/resources (PDF лекций)
  • Сеть: frieren_network

4. PostgreSQL

  • Контейнер: frieren_db
  • Образ: postgres:15
  • Платформа: linux/arm64 (для Apple Silicon)
  • Порт: 5432 (внутренний)
  • Переменные окружения:
    • POSTGRES_USER=frieren
    • POSTGRES_PASSWORD=frieren
    • POSTGRES_DB=frieren_db
  • Volumes: postgres_data:/var/lib/postgresql/data
  • Health check: Проверка готовности каждые 5 секунд
  • Сеть: frieren_network

5. RabbitMQ

  • Контейнер: frieren_rabbitmq
  • Образ: rabbitmq:3-management
  • Порт: 15672:15672 (Management UI)
  • Конфигурация: rabbitmq-definitions.json (автоматическое создание очереди checkin)
  • Volumes: ./rabbitmq-definitions.json:/etc/rabbitmq/definitions.json:ro
  • Сеть: frieren_network

6. N8N

  • Контейнер: frieren-n8n
  • Образ: n8nio/n8n:latest
  • Порт: 5678:5678
  • Аутентификация: Basic Auth (admin / admin123)
  • База данных: Использует PostgreSQL (frieren_db)
    • База: n8n
    • Схема: n8n_schema
  • Volumes:
    • n8n_data:/home/node/.n8n (workflows и настройки)
    • /var/folders:/var/folders/ (временные файлы)
  • Зависимости: postgres (с условием service_healthy)
  • Сеть: frieren_network

Настройка перед запуском

1. Настройка переменных окружения через .env файл

Все переменные окружения централизованы в файле .env в директории docker/. Это обеспечивает безопасность и удобство управления конфигурацией.

Создание .env файла:

cd docker
cp .env.example .env

Редактирование .env файла:

Откройте docker/.env и настройте необходимые переменные:

# ============================================
# Telegram Bot Configuration
# ============================================
BOT_TOKEN=your_telegram_bot_token_here  # ⚠️ ОБЯЗАТЕЛЬНО измените!

# ============================================
# PostgreSQL Database Configuration
# ============================================
POSTGRES_USER=frieren
POSTGRES_PASSWORD=frieren  # ⚠️ Измените для production!
POSTGRES_DB=frieren_db

# Backend Database Connection
DB_USER=frieren
DB_PASSWORD=frieren  # ⚠️ Измените для production!
DB_HOST=frieren_db
DB_PORT=5432
DB_NAME=frieren_db

# ============================================
# N8N Configuration
# ============================================
# N8N User Credentials (for Basic Auth and first user creation)
N8N_USER=your_email@example.com  # ⚠️ Измените!
N8N_PASSWORD=your_secure_password  # ⚠️ Измените!
N8N_FIRST_NAME=Admin
N8N_LAST_NAME=User

# N8N Database Configuration
N8N_DATABASE_HOST=frieren_db
N8N_DATABASE_PORT=5432
N8N_DATABASE_NAME=n8n
N8N_DATABASE_USER=frieren
N8N_DATABASE_PASSWORD=frieren  # Должен совпадать с POSTGRES_PASSWORD
N8N_DATABASE_SCHEMA=n8n_schema

# ============================================
# RabbitMQ Configuration
# ============================================
RABBITMQ_DEFAULT_USER=guest
RABBITMQ_DEFAULT_PASS=guest  # ⚠️ Измените для production!

# ============================================
# Frontend Configuration
# ============================================
BACKEND_URL=http://frieren-backend:8000
NODE_ENV=production

# ============================================
# Google Sheets Integration
# ============================================
# ID Google Таблицы для экспорта/импорта данных
# Получить можно из URL таблицы: https://docs.google.com/spreadsheets/d/{GOOGLE_SHEET_ID}/edit
# Пример: если URL таблицы https://docs.google.com/spreadsheets/d/1a2b3c4d5e6f7g8h9i0j/edit
# то GOOGLE_SHEET_ID=1a2b3c4d5e6f7g8h9i0j
# ⚠️ Опционально: требуется только для работы с Google Sheets (экспорт/импорт данных)
GOOGLE_SHEET_ID=your_google_sheet_id_here

Важно:

  • Файл .env не коммитится в git (добавлен в .gitignore)
  • Файл .env.example содержит шаблон с примерами значений
  • Все переменные имеют значения по умолчанию в docker-compose.yml, поэтому система будет работать даже без .env
  • Для production обязательно измените все пароли и секретные ключи!

Структура переменных:

Категория Переменные Обязательность
Telegram Bot BOT_TOKEN ✅ Обязательно
PostgreSQL POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB ⚠️ Рекомендуется изменить
Backend DB DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, DB_NAME ⚠️ Рекомендуется изменить
N8N N8N_USER, N8N_PASSWORD, N8N_FIRST_NAME, N8N_LAST_NAME ⚠️ Рекомендуется изменить
N8N Database N8N_DATABASE_* ⚠️ Рекомендуется изменить
RabbitMQ RABBITMQ_DEFAULT_USER, RABBITMQ_DEFAULT_PASS ⚠️ Рекомендуется изменить
Frontend BACKEND_URL, NODE_ENV Опционально
Google Sheets GOOGLE_SHEET_ID ⚠️ Опционально (требуется для экспорта/импорта в Google Sheets)

2. Настройка Google Sheets интеграции

Для работы с Google Sheets необходимо:

  1. Создать Google Cloud проект и Service Account:

    • Перейдите в Google Cloud Console
    • Создайте новый проект или выберите существующий
    • Включите Google Sheets API и Google Drive API
    • Создайте Service Account и скачайте JSON ключ
    • Сохраните файл как docker/google/credentials.json

  2. Создать Google Таблицу:

    • Создайте новую Google Таблицу или используйте существующую
    • Скопируйте ID таблицы из URL: 
      https://docs.google.com/spreadsheets/d/{GOOGLE_SHEET_ID}/edit
      Например, если URL: https://docs.google.com/spreadsheets/d/1a2b3c4d5e6f7g8h9i0j/edit то GOOGLE_SHEET_ID=1a2b3c4d5e6f7g8h9i0j

  3. Предоставить доступ Service Account к таблице:

    • Откройте Google Таблицу
    • Нажмите "Настройки доступа" (Share)
    • Добавьте email Service Account (находится в credentials.json, поле client_email) с правами редактора

  4. Настроить переменную окружения:

    • Добавьте GOOGLE_SHEET_ID в файл docker/.env: 
      GOOGLE_SHEET_ID=your_google_sheet_id_here

Примечание:

  • Без GOOGLE_SHEET_ID система будет работать, но функции экспорта/импорта в Google Sheets будут недоступны
  • Файл credentials.json должен находиться в docker/google/credentials.json
  • Убедитесь, что Service Account имеет доступ к таблице

3. Настройка RabbitMQ

Очередь checkin создается автоматически при запуске через rabbitmq-definitions.json и init-контейнер rabbitmq-init.

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

  • Очередь создается автоматически при первом запуске
  • Использует учетные данные из .env: RABBITMQ_DEFAULT_USER и RABBITMQ_DEFAULT_PASS
  • По умолчанию: guest / guest (⚠️ измените для production!)

Проверка очереди:

# Через Management UI
open http://localhost:15672
# Логин: guest / guest (или ваши учетные данные из .env)

# Через командную строку
docker-compose exec rabbitmq rabbitmqctl list_queues

4. Настройка N8N

N8N автоматически настраивается при первом запуске:

  • Первый пользователь создается автоматически через переменные из .env
  • Workflows импортируются автоматически из n8n_workflows/
  • Импорт происходит только один раз (проверяется существование workflow перед импортом)

Переменные окружения для N8N (в .env):

  • N8N_USER - email/username для входа в N8N
  • N8N_PASSWORD - пароль для входа в N8N
  • N8N_FIRST_NAME - имя первого пользователя
  • N8N_LAST_NAME - фамилия первого пользователя

Если N8N уже был настроен ранее:

# Для чистого старта удалите volume:
cd docker
docker-compose down
docker volume rm docker_n8n_data
docker-compose up -d

Workflows, которые импортируются автоматически:

  • CheckIn.json - Обработка регистрации на лекции (валидация времени, отправка в RabbitMQ)
  • Homework Submission.json - Обработка отправки домашних заданий с AI-анализом
  • Update Student Info Google Sheet.json - Синхронизация данных студентов с Google Sheets
  • Update Student Info.json - Обновление информации о студентах
  • Import rating from Google.json - Импорт оценок из Google Sheets (по расписанию)

Проверка импорта workflows:

# Проверьте логи init-контейнера
docker-compose logs n8n-init

# Ожидаемый вывод:
# ✓ Workflow 'CheckIn' imported successfully (HTTP 201)
# ✓ Workflow 'Homework Submission' imported successfully (HTTP 201)
# ✓ Workflow 'Update Student Info Google Sheet' imported successfully (HTTP 201)

5. Запуск системы

Production режим (использует готовые Docker образы):

cd docker

# Убедитесь, что .env файл создан
ls -la .env

# Если файла нет, создайте его из примера
cp .env.example .env
# Отредактируйте .env и настройте необходимые переменные

# Запуск всех сервисов (использует готовые образы ddzuba/frieren_*:arm64)
docker-compose up -d

Development режим (локальная сборка образов):

cd docker

# Запуск с локальной сборкой образов
docker-compose -f docker-compose-dev.yml up -d --build

Важно перед первым запуском:

  1. ✅ Создайте .env файл из .env.example
  2. ✅ Настройте BOT_TOKEN (обязательно!)
  3. ✅ Измените пароли для production (рекомендуется)
  4. ✅ Проверьте все переменные окружения

5. Проверка статуса

# Статус всех контейнеров
docker-compose ps

# Логи всех сервисов
docker-compose logs -f

# Логи конкретного сервиса
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f bot
docker-compose logs -f postgres
docker-compose logs -f n8n
docker-compose logs -f rabbitmq

Доступные сервисы после запуска

Сервис URL Учетные данные
Frontend http://localhost:3000 -
Backend API http://localhost:8000 -
API Docs (Swagger) http://localhost:8000/docs -
API Docs (ReDoc) http://localhost:8000/redoc -
N8N http://localhost:5678 Из .env: N8N_USER / N8N_PASSWORD
RabbitMQ Management http://localhost:15672 Из .env: RABBITMQ_DEFAULT_USER / RABBITMQ_DEFAULT_PASS
PostgreSQL localhost:5432 Из .env: POSTGRES_USER / POSTGRES_PASSWORD

Примечание: Учетные данные берутся из файла .env. По умолчанию используются значения из .env.example.

Управление контейнерами

# Запуск всех сервисов (production)
docker-compose up -d

# Запуск всех сервисов (development, с локальной сборкой)
docker-compose -f docker-compose-dev.yml up -d --build

# Остановка всех сервисов
docker-compose down

# Остановка с удалением volumes (⚠️ удалит данные БД!)
docker-compose down -v

# Пересборка образов (production)
docker-compose up -d --build

# Перезапуск конкретного сервиса
docker-compose restart backend
docker-compose restart frontend
docker-compose restart bot

# Остановка конкретного сервиса
docker-compose stop backend

# Запуск конкретного сервиса
docker-compose start backend

Работа с данными

PostgreSQL

# Подключение к БД
docker-compose exec postgres psql -U frieren -d frieren_db

# Резервное копирование
docker-compose exec postgres pg_dump -U frieren frieren_db > backup.sql

# Восстановление из backup
docker-compose exec -T postgres psql -U frieren frieren_db < backup.sql

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

Проект использует SQL миграции для обновления схемы базы данных. Миграции находятся в backend/src/migrations/.

Применение миграции для добавления поля presentation_blob:

# Через docker-compose (рекомендуется)
cd docker
docker-compose exec postgres psql -U frieren -d frieren_db -f /app/src/migrations/add_presentation_blob_to_lectures.sql

# Или через docker exec
docker exec -i frieren_db psql -U frieren -d frieren_db < backend/src/migrations/add_presentation_blob_to_lectures.sql

Откат миграции:

docker-compose exec postgres psql -U frieren -d frieren_db -f /app/src/migrations/rollback_presentation_blob.sql

Примечание: Миграции идемпотентны - их можно запускать несколько раз безопасно. Подробная документация по миграциям находится в backend/src/migrations/README.md.

Volumes

# Просмотр volumes
docker volume ls | grep frieren

# Удаление volumes (⚠️ удалит все данные!)
docker-compose down -v

Настройка для production

1. Изменение паролей и секретов

Обязательно измените все пароли и секреты в .env файле:

cd docker
cp .env.example .env
nano .env  # или используйте любой редактор

Критически важные переменные для production:

  1. Telegram Bot:

    BOT_TOKEN=your_production_bot_token_here

  2. PostgreSQL:

    POSTGRES_PASSWORD=strong_random_password_here
DB_PASSWORD=strong_random_password_here  # Должен совпадать с POSTGRES_PASSWORD

  3. N8N:

    N8N_USER=your_production_email@example.com
N8N_PASSWORD=strong_random_password_here
N8N_DATABASE_PASSWORD=strong_random_password_here  # Должен совпадать с POSTGRES_PASSWORD

  4. RabbitMQ:

    RABBITMQ_DEFAULT_USER=admin  # Не используйте 'guest' в production!
RABBITMQ_DEFAULT_PASS=strong_random_password_here

Генерация безопасных паролей:

# Linux/Mac
openssl rand -base64 32

# Или используйте онлайн генераторы паролей

После изменения .env:

docker-compose down
docker-compose up -d

2. Настройка сети

По умолчанию используется bridge network frieren_network. Для production рассмотрите:

  • Использование внешней сети
  • Настройку firewall правил
  • Использование reverse proxy (nginx/traefik)

3. Настройка ресурсов

Добавьте ограничения ресурсов в docker-compose.yml:

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

4. Логирование

Настройте ротацию логов:

services:
  backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Проверка работоспособности

# Backend API
curl http://localhost:8000/api/students/

# Frontend
curl http://localhost:3000

# Проверка health check PostgreSQL
docker-compose exec postgres pg_isready -U frieren -d frieren_db

# Проверка RabbitMQ
curl -u guest:guest http://localhost:15672/api/overview

# Проверка очередей RabbitMQ
docker-compose exec rabbitmq rabbitmqctl list_queues

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

Нагрузочное тестирование

Проект включает инструменты для нагрузочного тестирования в директории load_test/:

cd load_test
./load_test.sh

Используется wrk для нагрузочного тестирования API endpoints.

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

Подробная документация по тестированию frontend находится в frontend/TESTING.md.

Основные проверки:

  • Проверка переменных окружения
  • Проверка API rewrites
  • Проверка конфигурации
  • Визуальная проверка компонентов

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

Backend API включает автоматическую документацию:

Все endpoints можно протестировать через Swagger UI.

Проверка интеграций

  1. Telegram Bot:

    • Отправьте /start боту
    • Проверьте регистрацию студента
    • Проверьте check-in на лекцию

  2. N8N Workflows:

    • Импортируйте workflows из n8n_workflows/
    • Проверьте работу webhook триггеров
    • Проверьте интеграцию с RabbitMQ

  3. Google Sheets:

    • Настройте credentials для Google Sheets API
    • Проверьте экспорт/импорт данных

🔧 Разработка

Локальная разработка

Backend

cd backend
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

pip install -r requirements/requirement.txt
uvicorn src.service:app --reload --host 0.0.0.0 --port 8000

Frontend

cd frontend
npm install
npm run dev

Bot

cd bot
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

pip install -r requirements/requirements.txt
python app.py

Hot Reload

При разработке с Docker Compose, volumes настроены для hot reload:

  • Frontend: ../frontend/src:/app/src (настроено в обоих docker-compose файлах)
  • Backend: можно добавить volume для автоматической перезагрузки

Использование docker-compose-dev.yml для разработки:

cd docker
# Используйте docker-compose-dev.yml для локальной разработки с пересборкой образов
docker-compose -f docker-compose-dev.yml up -d --build

Отладка

Просмотр логов

# Все сервисы
docker-compose logs -f

# Конкретный сервис
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f bot

Вход в контейнер

docker-compose exec backend bash
docker-compose exec frontend sh
docker-compose exec bot bash

Проверка переменных окружения

# Проверка переменных из .env
docker-compose exec frontend env | grep BACKEND
docker-compose exec backend env | grep DB
docker-compose exec bot env | grep BOT
docker-compose exec n8n env | grep N8N
docker-compose exec rabbitmq env | grep RABBITMQ

# Проверка содержимого .env файла (без секретов)
cd docker
grep -v "PASSWORD\|TOKEN" .env

📚 Дополнительная документация

  • Backend: backend/README.md - Подробная документация по модели данных и API
  • Backend Migrations: backend/src/migrations/README.md - Документация по миграциям базы данных
  • Frontend Docker: frontend/README-Docker.md - Документация по развертыванию frontend
  • Frontend Testing: frontend/TESTING.md - Документация по тестированию
  • N8N Workflows: docker/n8n-workflows/README-homework-submission.md - Документация по workflows

🐛 Troubleshooting

Проблемы с подключением к базе данных

  1. Проверьте, что PostgreSQL контейнер запущен:

    docker-compose ps postgres

  2. Проверьте логи PostgreSQL:

    docker-compose logs postgres

  3. Проверьте переменные окружения:

    docker-compose exec backend env | grep DB

Проблемы с Frontend

  1. Проверьте переменную BACKEND_URL:

    docker-compose exec frontend env | grep BACKEND

  2. Проверьте логи frontend:

    docker-compose logs frontend

  3. Проверьте консоль браузера (F12) на наличие ошибок

Проблемы с Bot

  1. Проверьте BOT_TOKEN в .env:

    cd docker
grep BOT_TOKEN .env

# Или проверьте в контейнере
docker-compose exec bot env | grep BOT_TOKEN

  2. Убедитесь, что BOT_TOKEN установлен:

    # Если переменная пустая, добавьте её в .env
echo "BOT_TOKEN=your_token_here" >> docker/.env
docker-compose restart bot

  3. Проверьте подключение к API:

    docker-compose logs bot

  4. Убедитесь, что backend доступен из контейнера bot

Проблемы с N8N

  1. Проверьте учетные данные в .env:

    cd docker
grep N8N_USER .env
grep N8N_PASSWORD .env

  2. Проверьте доступность N8N:

    curl http://localhost:5678

  3. Проверьте логи:

    docker-compose logs n8n
docker-compose logs n8n-init  # Логи импорта workflows

  4. Убедитесь, что workflows импортированы:

    # Проверьте логи init-контейнера
docker-compose logs n8n-init | grep "imported successfully"

  5. Если workflows не импортируются:

    # Удалите volume и пересоздайте пользователя
docker-compose down
docker volume rm docker_n8n_data
docker-compose up -d

Проблемы с RabbitMQ

  1. Проверьте учетные данные в .env:

    cd docker
grep RABBITMQ .env

  2. Проверьте статус RabbitMQ:

    docker-compose ps rabbitmq

  3. Проверьте логи init-контейнера (создание очереди):

    docker-compose logs rabbitmq-init

  4. Проверьте Management UI: http://localhost:15672

    • Используйте учетные данные из .env: RABBITMQ_DEFAULT_USER / RABBITMQ_DEFAULT_PASS

  5. Проверьте очереди:

    docker-compose exec rabbitmq rabbitmqctl list_queues

  6. Если очередь не создана:

    # Перезапустите init-контейнер
docker-compose restart rabbitmq-init
docker-compose logs -f rabbitmq-init

Проблемы с Google Sheets интеграцией

  1. Проверьте переменную GOOGLE_SHEET_ID в .env:

    cd docker
grep GOOGLE_SHEET_ID .env

# Или проверьте в контейнере
docker-compose exec backend env | grep GOOGLE_SHEET_ID

  2. Убедитесь, что файл credentials.json существует:

    ls -la docker/google/credentials.json

  3. Проверьте, что Service Account имеет доступ к таблице:

    • Откройте Google Таблицу
    • Проверьте настройки доступа (Share)
    • Убедитесь, что email из credentials.json (поле client_email) добавлен с правами редактора

  4. Проверьте логи backend на наличие ошибок Google Sheets API:

    docker-compose logs backend | grep -i "google\|sheet\|gspread"

  5. Проверьте, что Google Sheets API и Google Drive API включены в Google Cloud Console:

    • Перейдите в Google Cloud Console
    • Выберите ваш проект
    • Перейдите в "APIs & Services" > "Library"
    • Убедитесь, что Google Sheets API и Google Drive API включены

  6. Если экспорт/импорт не работает:

    • Убедитесь, что GOOGLE_SHEET_ID установлен корректно (ID из URL таблицы)
    • Проверьте формат ID (должен быть строкой без пробелов)
    • Убедитесь, что таблица существует и доступна

📝 Лицензия

Проект разработан для внутреннего использования в МАИ.

👥 Авторы

Разработано для Московского авиационного института (МАИ).

📅 История изменений

Версия 1.4 (2025)

  • ✅ Добавлена функциональность управления презентациями лекций
  • ✅ Добавлено поле presentation_blob в таблицу lectures для хранения презентаций (PDF/PPTX, до 50MB)
  • ✅ Реализованы API endpoints для загрузки/скачивания презентаций лекций
  • ✅ Добавлена поддержка загрузки и скачивания презентаций в frontend
  • ✅ Интеграция скачивания презентаций в Telegram бот
  • ✅ Автоматическое определение формата файла (PDF/PPTX) при скачивании
  • ✅ Обновлена документация: добавлена информация о функциональности презентаций

Версия 1.3 (2025)

  • ✅ Добавлена функциональность управления экзаменационными оценками (exam_grades)
  • ✅ Добавлена таблица exam_grades в базу данных (6 полей, включая хранение PDF-файлов)
  • ✅ Реализованы API endpoints для работы с экзаменационными оценками (CRUD + загрузка/скачивание файлов)
  • ✅ Добавлена страница /exam-grades в frontend для управления оценками
  • ✅ Поддержка загрузки и скачивания PDF/PNG/JPG файлов экзаменационных работ
  • ✅ Интеграция exam_grades в экспорт/импорт данных и Google Sheets
  • ✅ Обновлена документация: добавлена информация о новой функциональности

Версия 1.2 (2025)

  • ✅ Добавлено поле start_time (время начала) для лекций
  • ✅ Обновлены все API endpoints лекций для поддержки времени начала
  • ✅ Обновлен frontend: добавлено отображение и редактирование времени начала лекций
  • ✅ Обновлен Telegram бот: добавлено отображение времени начала лекций во всех сценариях
  • ✅ Улучшен UX бота: все сценарии автоматически возвращают главное меню после завершения
  • ✅ Расширены N8N workflows: добавлены Update Student Info.json и Import rating from Google.json
  • ✅ Расширены API endpoints: добавлены новые endpoints для преподавателей и вариантов ДЗ
  • ✅ Обновлена документация: добавлены описания всех функций бота и API endpoints

Версия 1.1 (2025)

  • ✅ Централизована конфигурация через .env файл
  • ✅ Добавлен .env.example как шаблон конфигурации
  • ✅ Автоматическое создание первого пользователя N8N
  • ✅ Автоматический импорт N8N workflows с проверкой дубликатов
  • ✅ Автоматическое создание очереди RabbitMQ при первом запуске
  • ✅ Улучшена документация по развертыванию и настройке
  • ✅ Добавлены инструкции по использованию переменных окружения

Версия 1.0 (2024)

  • ✅ Реализована базовая функциональность управления студентами
  • ✅ Добавлена система регистрации на лекции через QR-код
  • ✅ Реализована система проверки домашних заданий
  • ✅ Добавлена интеграция с OpenAI для анализа кода
  • ✅ Реализована интеграция с Google Sheets
  • ✅ Добавлена система вариантов домашних заданий
  • ✅ Реализован веб-интерфейс для преподавателей
  • ✅ Добавлен Telegram бот для студентов и преподавателей
  • ✅ Настроена инфраструктура с Docker Compose
  • ✅ Добавлена интеграция с N8N и RabbitMQ

Последнее обновление: 2025

About

No description, website, or topics provided.

Resources

Readme

License

View license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages