LearnSpace

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

Стек: Node.js · Express · SQLite (node:sqlite DatabaseSync) · Vanilla JS · Canvas API · SSE · WebRTC

---

Содержание

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

---

Возможности

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

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

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

• Карандаш со сглаживанием Catmull-Rom
• Маркер (highlighter) с настраиваемой прозрачностью
• Лазерная указка (без сохранения)
• Ластик
• Connector (линии со стрелками)
• Стикеры с редактированием текста
• Текстовые блоки (inline editing)
• Вставка изображений (drag & drop + URL)
• Таблицы (интерактивные)
• LaTeX-формулы (KaTeX) с визуальным редактором и категориями символов
• Система координат с построением графиков функций (встроенный парсер выражений)
• Числовая ось для неравенств (точки, интервалы)
• Циркуль с трёхфазной state machine

Фигуры (11): прямоугольник, скруглённый прямоугольник, эллипс, линия, стрелка, треугольник, ромб, шестиугольник, звезда, облако, коннектор

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

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

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

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

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

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

Планиметрия (геометрические построения)

• Середина отрезка, биссектриса, высота, описанная/вписанная окружность
• Касательная, параллельный перенос, симметрия
• Правильный n-угольник, параллелограмм, средняя линия треугольника
• Метки параллельности, прямых углов, одинаковых отрезков
• Дуги углов, засечки рёбер

Стереометрия 3D

• Куб, прямоугольный параллелепипед, тетраэдр, октаэдр, пирамида, призма
• Усечённая пирамида, правильные многогранники, конус, цилиндр, сфера
• Скрещивающиеся прямые, производные точки 3D, длины рёбер
• Вращение мышью, deep-link на конкретную фигуру (openSim('stereo:cube') / ?stereofig=)

Темы доски (4)

• Chalkboard — зелёный фон, меловая текстура
• Blackboard — тёмно-синий, диагональная текстура
• Corkboard — пробковый, волокна
• Whiteboard — светло-серый, маркерная доска

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

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

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

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

---

Учебники (Textbooks)

Интерактивные параграф-по-параграфу учебники с прогрессом чтения.

Доступный контент (18 учебников)

Предмет	Классы
Химия	7, 8, 9
Физика	7, 8, 9, 10, 11
Алгебра	7, 8, 9, 10, 11
Геометрия	7, 8, 9, 10, 11

Функции:

• Параграф-по-параграф навигация с прогресс-баром и last_para (последнее место)
• Задания на чтение: учитель назначает конкретные §, система проверяет выполнение
• Кнопка «В лабораторию» — ссылки на связанные симуляции (lab_sim_links)
• Чип «Связано с программой» (курикулумная привязка)
• Хабы глав: агрегированный прогресс по всем главам учебника
• Закладки с заметками и цветами
• Просмотр прогресса учеников класса (teacher view)
• Прогресс хранится в textbook_progress (JSON массив прочитанных §)

Контент-движок Химии 7 и 8:

• 26 параграфов (Химия 7), 52 параграфа (Химия 8) с интерактивными виджетами
• Canvas-анимации (реакции, осадки, горение, электролиз, индикаторы)
• 3D-модели молекул (ball-and-stick, VSEPR-геометрия)
• Интегрированные задания и лабораторные работы
• Карты связей понятий, глоссарий в финалах глав

---

Виртуальная лаборатория (40 симуляций)

Canvas-движок без внешних зависимостей (по аналогу three.js — всё сделано вручную).

Физика (14): projectile, waves, hydrostatics, race, dynamics, isoprocess, pendulum, opticsbench, radioactive, collision, heatengine, circuit, emfield, logic

Химия (14): titration, bohratom, qualanalysis, crystal, molphys, orbitals, organic, periodic, solutions, stoichiometry, chemsandbox, chemistry, equilibrium, electrolysis

Математика (9): graph, triangle, quadratic, normaldist, geometry (планиметрия), stereo (стереометрия 3D), probability, graphtransform, trigcircle

Биология (2): celldivision, photosynthesis

Игры (1): angrybirds

Lab Content Engine (LabRegistry):

• Все симуляции зарегистрированы в window.LabRegistry через data-driven манифест
• Каталог в БД (lab_sims): включение/отключение отдельных симуляций, featured, теги
• Ленивая загрузка кода симуляций (Phase 3)
• Связь симуляций с параграфами учебников (lab_sim_links)
• Deep-link ?sim=<id> открывает конкретную симуляцию
• Курикулумная привязка: subject/grade/topics в манифесте
• Управление в админке: включение симуляций, редактор связей с учебниками

Оптическая скамья (opticsbench) — режим «Конструктор»:

• 2D-трассировщик лучей (линза, зеркало, преломление)
• Характеристические лучи предмета, дисперсия, ПВО
• Алиасы deep-link: thinlens, mirrors, refraction

---

Биохимия (5 страниц)

Интерактивный модуль без тяжёлых зависимостей (только Canvas).

Молекулярный редактор (biochem.html):

• 2D и настоящая 3D-геометрия по VSEPR (ОЭПВО)
• Тумблер δ± — тепловая карта частичных зарядов (синий δ+/красный δ−), стрелка диполя
• Гибридизация, форма молекулы, валентный угол в панели свойств
• Импорт SMILES (учебное подмножество), экспорт PNG/JSON
• Химический движок BIO (window.BIO, dual-export browser+Node): analyze, partialCharges, dipole, polarity, functionalGroups, balance, vsepr, render3D, parseSmiles, valency
• Расширенная валидация валентности: подсказки («Углерод (C): занято 5 связей, максимум 4 — убери 1»)

Серверный химический слой (services/chem.js):

• Переиспользует то же ядро biochem-core.js (без дублирования) через dual-export
• POST /api/biochem/analyze → {formula, mass, dbe, geometry, polarity, dipole, charges, groups, massFractions, valency}
• /validate переведён на ядро (единые подсказки валентности на клиенте и сервере)
• LS.biochemAnalyze(atoms, bonds) в api.js

Библиотека (biochem-library.html): 105+ молекул, 2D/3D-превью, сравнение

Реакции (biochem-reactions.html): 27 реакций, BIO.balance (Гаусс+НОК), энергодиаграмма (canvas: реагенты→продукты, стрелка ΔH, экзо/эндо), коэффициенты

Метаболические пути (biochem-pathways.html): пути из БД (bio_pathways), прогресс Learn-режима, награда XP

Свойства (biochem-properties.html): сравнение молекул, столбчатый график молярных масс, экспорт CSV

---

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

• Создание классов, добавление учеников
• Задания с дедлайнами и прикреплёнными файлами
• Отслеживание сдачи: статусы new/reviewed/accepted/revision
• Текстовые задания с прикреплением файлов учеником
• Журнал оценок
• Объявления и лента активности (Google Classroom-стиль)
• Шаблоны заданий для переиспользования
• Live-викторины в реальном времени (SSE)
• Аналитика успеваемости
• Назначение ученикам без класса (teacherStudents)
• Назначение чтения конкретных § учебника как домашнего задания

---

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

• Банк вопросов с уровнями сложности, тематиками, поддержкой HTML/KaTeX
• Конструктор тестов с перемешиванием вопросов
• Многошаговые уроки с блоками: текст, медиа, формулы, код, викторина
• Курсы с прогрессом прохождения
• Карточки (flashcards) со spaced repetition
• Граф знаний — визуализация связей между темами
• Сборники ЦТ/ЦЭ: физика 2019–2024, математика 2021–2024 (300+ вопросов)
• Экзаменационные тесты (exam9): 80 вариантов по математике 9 класса

---

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

Биохимия — см. раздел выше

Красная книга (4 страницы):

• Виды, биомы, экосистемы, пищевые сети
• Популяционные данные, квесты

Коллекции: коллекционирование предметов с галереей

Galaxy Map (/sitemap): интерактивная Canvas-карта всех модулей платформы с feature flag фильтрацией

---

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

• Опыт (XP) и уровни (8 уровней эволюции, визуальная модель с VSEPR-геометрией)
• 38+ достижений в 6 группах (onboarding, streak, lab, exam, biochem, leaderboard)
• Стрики (серии дней)
• Ежедневные цели (easy/medium/hard тиры) с кольцом прогресса
• Виртуальный питомец: эволюция по уровням, 6 цветов, аксессуары (шляпа, очки, корона), радужный ошейник при streak ≥ 7, автономное настроение
• Магазин с внутренней валютой (монеты), фоны для питомца
• Коллекционирование предметов

Панель администратора геймификации:

• Статистика: суммарный XP, монеты, средний уровень, достижения, покупки
• Топ-10 по XP, последние начисления XP с читаемыми подписями
• Начисление XP/монет: select с полным списком пользователей + фильтр, пресеты (0/+10/+25/+50/+100/+250), пресеты причин, fix: 0 XP не начисляется
• Сброс прогресса пользователя

---

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

• Управление пользователями и ролями (student, teacher, admin, free_student)
• Гранулярные разрешения (RBAC) — per-role и per-user
• Feature flags: включение/отключение модулей (biochem, textbooks, flashcards, board, live_quiz, exam9)
• Управление симуляциями: каталог в БД, включение/отключение, редактор связей с учебниками
• Доступ к контенту (allowlist): учебники и экзамены по классам и ученикам (content_access)
• Журнал аудита (admin_audit_log)
• System Health: реальное время метрики (CPU, RAM, event loop lag), HTTP-статистика запросов, тренды (canvas-графики), журнал последних ошибок
• Кабинет родителя с аналитикой по ученику
• Аватары с crop/zoom — ученик загружает, учитель/админ модерирует
• Панель «Обзор» (командный центр): KPI 24ч, лента завершений, триаж событий, распределение по предметам
• KaTeX рендеринг в секции «Вопросы»
• Глобальный поиск (command palette): пользователи, тесты, классы

---

Дашборд (Главная)

Для ученика:

• Карточка «Продолжить/Начать чтение» с обложкой учебника (цветная, по теме)
• Карточка «Лаборатория дня» с превью симуляции на фоне блока + deep-link
• Карточка питомца с реальными данными из /api/pet (имя, модель, цвет, уровень XP, настроение)
• Активность (тепловая карта / streak-календарь), слабые темы, задания

Для администратора:

• Командный центр: pulse KPIs с count-up анимацией, attention inbox, лента завершений, health-плитки контента, топ/антирейтинг дня

Шапка (dash-header): увеличенная (76px), аватарка 46px, Unbounded 1.15rem, кольца ученика 48px, чипы администратора крупные

---

Профиль и настройки

• Звуковая система (12 звуков на Web Audio API): достижения, уровень, XP, монеты, тесты, доска
• Настройки предпочтений на сервере (dashboard widget visibility, whiteboard defaults)
• Вкладка звука и настроек в профиле

---

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

Требования: 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 22+

git clone https://git.dolgolyov-family.by/maxim.dolgolyov/Learn_System.git
cd Learn_System/backend
npm install

cp .env.example .env
# Отредактировать .env

npm run migrate   # применить все миграции (47 SQL-файлов)
npm run seed      # опционально — тестовые данные

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, 40 route groups
│   │   ├── config.js
│   │   ├── sse.js                  # Server-Sent Events broadcast
│   │   ├── controllers/            # 40+ контроллеров
│   │   │   ├── gamification/       # _shared, service, admin, achievements (split)
│   │   │   ├── classroom/          # 7 domain-файлов (split)
│   │   │   └── biochemController.js
│   │   ├── routes/                 # 40 файлов маршрутов
│   │   ├── services/
│   │   │   ├── chem.js             # Серверный химический движок (dual-export с BIO)
│   │   │   └── contentAccess.js    # Allowlist учебников и экзаменов
│   │   ├── middleware/             # auth, RBAC, rate limit, validate
│   │   ├── db/
│   │   │   ├── migrations-runner.js # Версионированный runner (47 миграций)
│   │   │   ├── db.js               # node:sqlite DatabaseSync singleton
│   │   │   └── migrations/         # SQL-файлы схемы (000–046)
│   │   └── utils/                  # audit, sanitize, healthMonitor
│   └── package.json
├── frontend/
│   ├── *.html                      # 60 страниц
│   ├── css/ls.css                  # Общая дизайн-система
│   └── js/
│       ├── whiteboard.js           # Движок доски (~3500+ строк)
│       ├── classroom-rtc.js        # WebRTC модуль
│       ├── biochem-core.js         # Химическое ядро BIO (dual-export)
│       ├── pet-sprite.js           # Рендерер питомца (dual-export, shared)
│       ├── lab-previews.js         # SVG-превью симуляций для дашборда
│       ├── labs/                   # 40 симуляций + LabRegistry
│       │   ├── _registry.js        # LabRegistry — единый реестр
│       │   ├── _register-all.js    # Data-driven регистрация всех симуляций
│       │   ├── lab-glue.js         # Каталог SIMS, THEORY, preview SVG
│       │   ├── lab-init.js         # openSim dispatcher
│       │   └── *.js                # 34 движка симуляций
│       └── admin/                  # Секции admin.html
│           ├── admin.js            # Оркестратор + роутер
│           ├── router.js           # Hash-based router
│           └── sections/           # overview, users, sessions, gam, ...
├── js/
│   ├── api.js                      # window.LS.* — 200+ клиентских методов
│   ├── sidebar.js                  # Сайдбар с nav-avatar
│   └── mobile.js                   # Мобильная адаптация
├── plans/                          # Планы фич (BIOCHEM_UPGRADE, STEREO_3D, ...)
├── docs/                           # Руководства и планы
├── 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-поток на пользователя
• События: stroke_batch, stroke_preview, stroke_deleted, page_changed, chat_message, cursor_move, hand_raised, screen_share и др.

База данных

• SQLite через node:sqlite (DatabaseSync, встроенный в Node.js 22+)
• Версионированные миграции (47 SQL-файлов, 000–046)
• 106 таблиц
• Транзакционная запись батчей штрихов

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

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

Химическое ядро (BIO)

• frontend/js/biochem-core.js — dual-export: window.BIO в браузере, module.exports в Node
• backend/src/services/chem.js — переиспользует ядро без дублирования
• VSEPR-геометрия, частичные заряды, дипольный момент, баланс уравнений (Гаусс+НОК)

Доступ к контенту (content_access)

• allowlist учебников и экзаменов по классам и конкретным ученикам
• services/contentAccess.js: canAccessTextbook, filterTextbooks, allowedRefs
• /api/access — admin CRUD

Lab Content Engine (LabRegistry)

• Все симуляции: data-driven манифесты в LabRegistry
• Ленивая загрузка через LabLoader.ensure(simId)
• Каталог в БД (lab_sims): включение, featured, теги, привязка к учебникам

Shared модули (pet-sprite.js, lab-previews.js)

• pet-sprite.js — канонический рендерер питомца, используется и на /pet, и на дашборде
• lab-previews.js — SVG-превью 6 симуляций для карточки «Лаборатория дня»

---

API

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

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

Группа	Путь	Назначение
Auth	/auth	Регистрация, вход, профиль, аватар
Classroom	/classroom	Онлайн-урок, доска, чат, WebRTC
Classes	/classes	Управление классами
Assignments	/assignments	Задания и сдача работ
Submissions	/submissions	Сдача работ, статусы, оценки
Questions	/questions	Банк вопросов
Sessions	/sessions	Тестовые сессии
Courses	/courses	Теоретические курсы
Lessons	/lessons	Уроки с блоками контента
Textbooks	/textbooks	Учебники, прогресс, закладки
Lab	/lab	Симуляции: каталог, управление
Biochem	/biochem	Молекулы, реакции, пути, analyze, validate
Gamification	/gamification	XP, уровни, ачивки, стрики, admin
Pet	/pet	Питомец, действия, магазин фонов
Shop	/shop	Виртуальный магазин
Live	/live	Live-викторины
Analytics	/analytics	Статистика
Admin	/admin	Управление платформой, overview
Access	/access	Allowlist контента
Exam9	/exam9	Экзаменационные тесты
Files	/files	Загрузка и хранение файлов
Notifications	/notifications	Уведомления
Permissions	/permissions	RBAC правила
Search	/search	Глобальный поиск
Preferences	/preferences	Пользовательские настройки
Parent	/parent	Кабинет родителя
Red Book	/red-book	Красная книга
Collection	/collection	Коллекции предметов
Games	/games	Игры (виселица, кроссворд)
Knowledge Map	/knowledge-map	Граф знаний
Flashcards	/flashcards	Флэшкарты
Templates	/templates	Шаблоны заданий
Teacher Students	/teacher-students	Ученики учителя без класса

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

---

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

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

Разрешения настраиваются гранулярно через /api/permissions (per-role и per-user).

---

Feature Flags

Управляются через app_settings и API /api/admin (только admin).

Флаг	Назначение	По умолчанию
feature_biochem_enabled	Модуль биохимии	вкл
feature_textbooks_enabled	Модуль учебников	вкл
feature_flashcards_enabled	Флэшкарты	вкл
feature_board_enabled	Доска (board)	вкл
feature_live_quiz_enabled	Live-викторины	выкл
feature_exam9_enabled	Экзаменационные тесты	вкл
sim_module_disabled	Весь модуль симуляций	выкл
sim_disabled_ids	JSON-массив отключённых симуляций	[]

---

Контент

Учебники

Предмет	Классы	Статус
Химия	7, 8, 9	Полный курс с виджетами и анимациями
Физика	7, 8, 9, 10, 11	Структура + контент
Алгебра	7, 8, 9, 10, 11	Структура + контент
Геометрия	7, 8, 9, 10, 11	Структура + контент

Сборники ЦТ/ЦЭ

Сборник	Вопросов
Физика 2019–2024	150+
Математика 2021–2024	150+
Экзамен-9 (математика)	80 вариантов

Симуляции

40 симуляций в 5 категориях — см. раздел «Виртуальная лаборатория».

---

Лицензия

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