LearnSpace

Образовательная платформа с интерактивной онлайн-доской, системой тестирования, управлением классами и элементами геймификации.

Стек: Node.js · Express · SQLite · Vanilla JS · Canvas API · SSE · WebRTC

---

Содержание

• Возможности
• Быстрый старт
• Ручная установка
• Переменные окружения
• Архитектура
• API
• Роли пользователей

---

Возможности

Онлайн-урок (Classroom)

Полнофункциональная интерактивная доска с синхронизацией в реальном времени через SSE.

Инструменты рисования

• Карандаш со сглаживанием Catmull-Rom
• Маркер (highlighter) с настраиваемой прозрачностью
• Лазерная указка (без сохранения)
• Ластик
• 11 фигур: прямоугольник, скруглённый прямоугольник, эллипс, линия, стрелка, треугольник, ромб, шестиугольник, звезда, облако, коннектор
• Стикеры с редактированием
• Текстовые блоки
• Вставка изображений
• Таблицы
• LaTeX-формулы (KaTeX) с визуальным редактором и категориями символов
• Система координат с построением графиков функций (встроенный парсер)
• Числовая ось для неравенств (точки, интервалы)
• Циркуль с анимацией

Инструмент выделения

• Перемещение и изменение размера всех объектов
• Вращение объектов (handle над объектом)
• Lasso multi-select (резиновая рамка)
• Shift+click для добавления к выделению
• Copy / Paste с автосмещением
• Snap-гайды при выравнивании объектов

Навигация по холсту

• Zoom: колесо мыши к курсору, Ctrl++/-/0, кнопки в тулбаре
• Pan: зажатый пробел + перетаскивание
• Minimap (192×108) в правом нижнем углу при zoom > 1 — клик/drag для прыжка по холсту

Инструменты измерения

• Линейка: поворот (drag ↺), изменение длины (drag ↔), панель свойств (угол, длина)
• Транспортир: поворот, изменение радиуса, панель свойств
• Авто-измерения геометрических фигур (длины, углы, площадь)

Страницы и шаблоны

• Неограниченное количество страниц на сессию
• Боковая панель с миниатюрами страниц
• Шаблоны: чистая страница, сетка, линейки, точки, координатные оси
• Экспорт страницы в PNG

Коммуникация

• Чат с реакциями и закреплёнными сообщениями
• Загрузка файлов в чат
• Поднятие руки учеником
• WebRTC аудио/видео
• Трансляция экрана учителя
• Курсор учителя виден ученикам в реальном времени
• Выдача прав рисования отдельным ученикам
• Личные заметки по уроку (per user)

Учебные материалы

• Банк вопросов с уровнями сложности и тематиками
• Конструктор тестов с перемешиванием вопросов
• Многошаговые уроки с блоками: текст, медиа, формулы, код, викторина
• Курсы с прогрессом прохождения
• Карточки (flashcards) со spaced repetition
• Граф знаний — визуализация связей между темами
• Интерактивные лабораторные работы (30+ симуляций): физика, химия, биология, математика

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

• Создание классов, добавление учеников
• Задания с дедлайнами, отслеживание сдачи
• Журнал оценок
• Объявления и лента активности (Google Classroom-стиль)
• Шаблоны заданий для переиспользования
• Live-викторины в реальном времени
• Аналитика успеваемости

Специализированный контент

• Биохимия: интерактивные молекулы, реакции, метаболические пути, электрофорез
• Красная книга: виды, биомы, экосистемы, пищевые сети, популяционные данные, квесты

Геймификация

• Опыт (XP) и уровни
• Система достижений
• Стрики (серии дней)
• Ежедневные цели и задачи
• Виртуальный питомец
• Магазин с внутренней валютой
• Коллекционирование предметов

Администрирование

• Управление пользователями и ролями
• Гранулярные разрешения (RBAC)
• Feature flags (глобальные и per-class)
• Журнал аудита
• Кабинет родителя

---

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

Требования: Docker, Docker Compose

git clone https://git.dolgolyov-family.by/maxim.dolgolyov/Learn_System.git
cd Learn_System
cp backend/.env.example .env
# Отредактировать .env — задать JWT_SECRET и CLIENT_ORIGIN
docker compose up -d

Платформа будет доступна на http://localhost:3000.

Первый пользователь с ролью admin создаётся через seed:

docker compose exec app npm run seed

---

Ручная установка

Требования: Node.js 18+

# 1. Клонировать и установить зависимости
git clone https://git.dolgolyov-family.by/maxim.dolgolyov/Learn_System.git
cd Learn_System/backend
npm install

# 2. Конфигурация
cp .env.example .env
# Отредактировать .env

# 3. Миграции и начальные данные
npm run migrate
npm run seed        # опционально — тестовые вопросы и пользователи

# 4. Запуск
npm start           # production
npm run dev         # development (nodemon)

Сервер запустится на http://localhost:3000.
Фронтенд раздаётся Express-ом из папки frontend/.

---

Переменные окружения

Файл: backend/.env (шаблон: backend/.env.example)

Переменная	Описание	По умолчанию
PORT	Порт сервера	3000
JWT_SECRET	Секрет для подписи токенов	обязательно
JWT_EXPIRES_IN	Срок жизни токена	7d
CLIENT_ORIGIN	CORS — адрес фронтенда	http://localhost:3000
DB_PATH	Путь к файлу БД	./backend/data/learnspace.db
UPLOADS_DIR	Папка для загруженных файлов	./backend/uploads
NODE_ENV	Окружение (production/development)	development

---

Архитектура

Learn_System/
├── backend/
│   ├── src/
│   │   ├── server.js          # Express app, 28 route groups
│   │   ├── config.js
│   │   ├── sse.js             # Server-Sent Events broadcast
│   │   ├── controllers/       # 30 контроллеров
│   │   ├── routes/            # 28 файлов маршрутов
│   │   ├── middleware/        # auth, RBAC, rate limit, validate
│   │   ├── db/
│   │   │   ├── migrate.js     # Auto-migration при старте (76 таблиц)
│   │   │   ├── db.js          # better-sqlite3 singleton
│   │   │   └── migrations/    # SQL-файлы схемы
│   │   └── utils/
│   └── package.json
├── frontend/
│   ├── *.html                 # 43 страницы
│   ├── css/ls.css             # Общая дизайн-система
│   └── js/
│       ├── whiteboard.js      # Движок доски (~3200 строк)
│       ├── classroom-rtc.js   # WebRTC модуль
│       └── labs/              # 30+ физических симуляций
├── js/
│   ├── api.js                 # window.LS.* — клиентское API
│   └── mobile.js              # Мобильная адаптация
├── docker-compose.yml
└── Dockerfile

Ключевые технические решения

Синхронизация доски

• Штрихи сохраняются батчами через POST /api/classroom/:id/strokes
• Загрузка с ?since_seq=N — клиент получает только новые штрихи
• Live-превью через POST /stroke-preview → SSE stroke_preview событие
• Двухслойный canvas: статический слой (_strokes) + динамический (_selection/guides/laser)

Real-time (SSE)

• Один SSE-поток на пользователя: GET /api/classroom/:id/events
• События: stroke_batch, stroke_preview, stroke_deleted, page_changed, chat_message, cursor_move, hand_raised, screen_share, и др.
• Compression отключён для SSE-потоков

База данных

• SQLite через better-sqlite3 (синхронный API)
• Автоматические миграции при каждом старте сервера
• 76 таблиц, транзакционная запись батчей штрихов

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

• JWT Bearer token
• Роли: admin, teacher, student, free_student
• RBAC middleware с кешированием разрешений
• Rate limiting: 6000 req/min для classroom, 600 req/min для остальных

---

API

Базовый URL: http://localhost:3000/api

Аутентификация: Authorization: Bearer <token>

Группа	Базовый путь	Назначение
Auth	/auth	Регистрация, вход, профиль
Classroom	/classroom	Онлайн-урок, доска, чат, WebRTC
Classes	/classes	Управление классами
Assignments	/assignments	Задания и сдача работ
Questions	/questions	Банк вопросов
Sessions	/sessions	Тестовые сессии
Courses	/courses	Теоретические курсы
Lessons	/lessons	Уроки с блоками контента
Gamification	/gamification	XP, ачивки, стрики
Files	/files	Загрузка и хранение файлов
Live	/live	Live-викторины
Analytics	/analytics	Статистика
Admin	/admin	Управление платформой

Полная документация по endpoint'ам — в backend/src/routes/.

---

Роли пользователей

Роль	Доступ
admin	Полный доступ ко всему, включая панель администратора
teacher	Создание классов, уроков, заданий, проведение онлайн-уроков
student	Прохождение тестов, участие в уроках, доступ к материалам
free_student	Ограниченный доступ (настраивается feature flags)

Разрешения настраиваются гранулярно через /api/permissions.

---

Лицензия

Частный проект. Все права защищены.