Learn_System/README.md

# 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=<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

```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 <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 категориях — см. раздел «Виртуальная лаборатория».

---

## Лицензия

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