# 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 <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`.

---

## Лицензия

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