docs: add comprehensive README

Covers all features, quick start (Docker + manual), architecture, API overview, roles, env vars, and technical decisions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-12 10:30:38 +03:00
parent f4eee2af3f
commit 074ee5687b
1 changed files with 285 additions and 0 deletions
@@ -0,0 +1,285 @@
 # 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`.
 ---
 ## Лицензия
 Частный проект. Все права защищены.