# LearnSpace **Образовательная платформа с интерактивной онлайн-доской, системой тестирования, учебниками, виртуальной лабораторией и геймификацией.** Стек: Node.js · Express · SQLite (`node:sqlite` DatabaseSync) · Vanilla JS · Canvas API · SSE · WebRTC --- ## Содержание - [Возможности](#возможности) - [Быстрый старт](#быстрый-старт) - [Ручная установка](#ручная-установка) - [Переменные окружения](#переменные-окружения) - [Архитектура](#архитектура) - [API](#api) - [Роли пользователей](#роли-пользователей) - [Feature Flags](#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=` открывает конкретную симуляцию - Курикулумная привязка: 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 ```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 22+ ```bash 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 ` | Группа | Путь | Назначение | |--------|------|-----------| | 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 категориях — см. раздел «Виртуальная лаборатория». --- ## Лицензия Частный проект. Все права защищены.