# LearnSpace **Образовательная платформа с интерактивной онлайн-доской, системой тестирования, управлением классами и элементами геймификации.** Стек: Node.js · Express · SQLite · Vanilla JS · Canvas API · SSE · WebRTC --- ## Содержание - [Возможности](#возможности) - [Быстрый старт](#быстрый-старт) - [Ручная установка](#ручная-установка) - [Переменные окружения](#переменные-окружения) - [Архитектура](#архитектура) - [API](#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 ```bash 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: ```bash docker compose exec app npm run seed ``` --- ## Ручная установка **Требования:** Node.js 18+ ```bash # 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 ` | Группа | Базовый путь | Назначение | |--------|-------------|-----------| | 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`. --- ## Лицензия Частный проект. Все права защищены.