AIS Hack - Backend Documentation

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

Инструкция по запуску

Предварительные требования

• Node.js: Версия 16 или выше
• npm или yarn

Установка

cd backend
npm install

Запуск

# Режим разработки (с автоматической перезагрузкой)
npm run dev

# Обычный запуск
npm start

для использования ИИ нужен ключ Gemini в backend/.env

GEMINI_API-KEY="APIKEY'

API Документация (Schedule)

1. Создание записи в расписании

• Маршрут: POST /api/schedule
• Описание: Создает новый урок. Включает автоматическую проверку на конфликты (занят ли класс, учитель или кабинет).
• Тело запроса (JSON):

  {
    "type": "lecture",
    "subject": "Физика",
    "teacherId": 10,
    "className": "9A",
    "roomNumber": "205",
    "startTime": "2023-10-27T10:00:00Z",
    "endTime": "2023-10-27T10:45:00Z"
  }

• Возвращает: Объект созданной записи с присвоенным id.

2. Получение расписания класса

• Маршрут: GET /api/schedule/class/:className
• Описание: Возвращает список активных занятий для класса на указанную дату.
• Query-параметры: date (ISO дата или YYYY-MM-DD).
• Возвращает: Массив объектов расписания, отсортированный по времени.

3. Получение расписания учителя

• Маршрут: GET /api/schedule/teacher/:teacherId
• Описание: Возвращает список активных занятий для учителя на указанную дату.
• Query-параметры: date (ISO дата или YYYY-MM-DD).
• Возвращает: Массив объектов расписания.

4. Массовая замена учителя

• Маршрут: POST /api/schedule/replace-teacher
• Описание: Заменяет одного учителя на другого во всех записях в указанном диапазоне дат.
• Тело запроса (JSON):

  {
    "oldTeacherId": 10,
    "newTeacherId": 11,
    "fromDate": "2023-10-27T00:00:00Z",
    "toDate": "2023-10-31T23:59:59Z"
  }

• Возвращает: { "success": true }.

5. Отмена (деактивация) занятия

• Маршрут: DELETE /api/schedule/:entryId
• Описание: Помечает занятие как неактивное (is_active = 0).
• Возвращает: { "success": true }.

6. Свободные окна учителя

• Маршрут: GET /api/schedule/teacher/:teacherId/free-slots
• Описание: Вычисляет свободные промежутки времени учителя в учебный день (с 08:00 до 17:00).
• Query-параметры:
  • date: Дата поиска.
  • slotDuration: Длительность слота в минутах (по умолчанию 45).
• Возвращает: Массив объектов { start, end }.

---

Структура Базы Данных (Схема)

Система использует SQLite для хранения данных. Основные таблицы:

Предметы и Оценки

• subjects: Справочник учебных дисциплин.
• period_info: Настройки формул расчета и типов баллов для периодов.
• schedule_entries: Календарь занятий. Поле type определяет характер урока (regular, sor, soch).
• student_grades: Связующая таблица для учета посещаемости (attendance) по каждому уроку.
• marks: Таблица всех полученных баллов.
  • mark_type принимает значения: formattedScore (текущая), sor (СОР), soch (СОЧ).

Схема связей

erDiagram
    subjects ||--o{ schedule_entries : contains
    subjects ||--|| period_info : has
    schedule_entries ||--o| student_grades : status
    schedule_entries ||--o{ marks : results

Loading

---

Технологический стек

• Runtime: Node.js
• Database: SQLite (better-sqlite3)
• Logging: Winston / Custom Logger

Структура сервиса

Все операции с базой данных и бизнес-проверки сосредоточены в backend/src/services/scheduleService.js.

• Проверка конфликтов осуществляется перед каждой вставкой.
• Поддерживается "мягкое" удаление записей через поле is_active.