API.md

🔌 API Документация ШКЕД

Обзор

Полная документация API платформы SmartSchedule (ШКЕД) для управления расписанием занятий.

Базовый URL

Development: http://localhost:3000/api
Production: https://your-domain.com/api

Аутентификация

Все API endpoints требуют аутентификации через NextAuth.js сессии.

Заголовки

Запросы должны включать cookie с сессией:

Cookie: next-auth.session-token=<token>

Роли пользователей

• admin - Администратор
• student - Студент
• lector - Преподаватель
• mentor - Ментор/Научный руководитель
• assistant - Ассистент
• co_lecturer - Со-преподаватель
• education_office_head - Начальник учебного отдела
• department_admin - Администратор кафедры

Endpoints

Пользователи

GET /api/users

Получить список пользователей

Права: admin

Параметры запроса:

• role - Фильтр по роли
• groupId - Фильтр по группе
• search - Поиск по имени/email

POST /api/users

Создать пользователя

Права: admin

Тело запроса:

{
  "name": "Имя Фамилия",
  "email": "user@example.com",
  "password": "password123",
  "role": "student",
  "status": "ACTIVE"
}

Группы

GET /api/groups

Получить список групп

Права: все авторизованные

POST /api/groups

Создать группу

Права: admin

Тело запроса:

{
  "name": "Б05-123",
  "year": 2025
}

GET /api/groups/{id}

Получить детали группы

Права: все авторизованные

PATCH /api/groups/{id}

Обновить группу

Права: admin

DELETE /api/groups/{id}

Удалить группу

Права: admin

Предметы

GET /api/subjects

Получить список предметов

Права: все авторизованные

POST /api/subjects

Создать предмет

Права: admin

Тело запроса:

{
  "name": "Математический анализ",
  "description": "Описание предмета"
}

GET /api/subjects/{id}

Получить детали предмета

Права: все авторизованные

PATCH /api/subjects/{id}

Обновить предмет

Права: admin, lector

DELETE /api/subjects/{id}

Удалить предмет

Права: admin

Расписание

GET /api/schedules

Получить расписание

Права: все авторизованные

Параметры запроса:

• groupId - Фильтр по группе
• subjectId - Фильтр по предмету
• subgroupId - Фильтр по подгруппе
• startDate - Начало периода (ISO 8601)
• endDate - Конец периода (ISO 8601)

POST /api/schedules

Создать занятие

Права: admin

Тело запроса:

{
  "subjectId": "subject_id",
  "groupId": "group_id",
  "subgroupId": "subgroup_id",
  "date": "2025-11-05",
  "startTime": "10:00",
  "endTime": "11:30",
  "location": "Аудитория 305",
  "type": "LECTURE"
}

GET /api/schedules/{id}

Получить детали занятия

Права: все авторизованные

PATCH /api/schedules/{id}

Обновить занятие

Права: admin

DELETE /api/schedules/{id}

Удалить занятие

Права: admin

Подгруппы

См. SUBGROUPS_SYSTEM.md

GET /api/groups/{groupId}/subgroups

Получить подгруппы группы

Права: все авторизованные

Параметры запроса:

• subjectId - Фильтр по предмету

POST /api/groups/{groupId}/subgroups

Создать подгруппу

Права: admin

Тело запроса:

{
  "subjectId": "subject_id",
  "name": "Подгруппа 1",
  "number": 1,
  "description": "Описание"
}

GET /api/groups/{groupId}/subgroups/{subgroupId}

Получить детали подгруппы

Права: все авторизованные

PATCH /api/groups/{groupId}/subgroups/{subgroupId}

Обновить подгруппу

Права: admin

DELETE /api/groups/{groupId}/subgroups/{subgroupId}

Удалить подгруппу

Права: admin

POST /api/groups/{groupId}/subgroups/{subgroupId}/students

Добавить студентов в подгруппу

Права: admin

Тело запроса:

{
  "studentIds": ["user_id_1", "user_id_2"]
}

DELETE /api/groups/{groupId}/subgroups/{subgroupId}/students

Удалить студента из подгруппы

Права: admin

Параметры запроса:

• userId - ID студента

Посещаемость

См. ATTENDANCE_TRACKING.md

POST /api/schedules/{scheduleId}/attendance

Отметить посещаемость

Права: admin, lector, assistant

Тело запроса:

{
  "attendanceList": [
    {
      "userId": "user_id",
      "status": "PRESENT",
      "source": "MANUAL",
      "notes": "Примечание"
    }
  ]
}

GET /api/schedules/{scheduleId}/attendance

Получить посещаемость занятия

Права: admin, lector, student (своя)

GET /api/attendance/report

Сформировать отчет по посещаемости

Права: admin, lector, education_office_head, department_admin

Параметры запроса:

• groupId - Фильтр по группе
• subjectId - Фильтр по предмету
• userId - Фильтр по студенту
• startDate - Начало периода (ISO 8601)
• endDate - Конец периода (ISO 8601)

Экзамены

См. EXAM_MANAGEMENT.md

GET /api/exams

Получить список экзаменов

Права: все авторизованные

Параметры запроса:

• groupId - Фильтр по группе
• subjectId - Фильтр по предмету

POST /api/exams

Создать экзамен

Права: admin, lector

Тело запроса:

{
  "subjectId": "subject_id",
  "groupId": "group_id",
  "type": "EXAM",
  "format": "ORAL",
  "date": "2025-12-20T10:00:00Z",
  "location": "Аудитория 401"
}

GET /api/exams/{id}

Получить детали экзамена

Права: все авторизованные

PATCH /api/exams/{id}

Обновить экзамен

Права: admin, lector

DELETE /api/exams/{id}

Удалить экзамен

Права: admin

POST /api/exams/{examId}/results

Внести результат экзамена

Права: admin, lector

Тело запроса:

{
  "userId": "user_id",
  "grade": "5",
  "status": "PASSED",
  "notes": "Примечание"
}

GET /api/exams/{examId}/results

Получить ведомость экзамена

Права: admin, lector, student (свой результат)

Менторские встречи

См. MENTOR_MEETINGS.md

GET /api/mentor-meetings

Получить список встреч

Права: admin, mentor (свои), student (свои)

Параметры запроса:

• mentorId - Фильтр по ментору
• studentId - Фильтр по студенту
• status - Фильтр по статусу

POST /api/mentor-meetings

Создать встречу

Права: admin, mentor, student

Тело запроса:

{
  "mentorId": "mentor_id",
  "studentId": "student_id",
  "scheduledAt": "2025-11-15T14:00:00Z",
  "duration": 60,
  "agenda": "Обсуждение прогресса",
  "location": "Офис / Zoom",
  "meetingType": "VKR"
}

GET /api/mentor-meetings/{id}

Получить детали встречи

Права: admin, mentor, student (участники)

PATCH /api/mentor-meetings/{id}

Обновить встречу

Права: admin, mentor (свои)

DELETE /api/mentor-meetings/{id}

Отменить встречу

Права: admin, mentor, student (участники)

Форум

См. FORUM_SYSTEM.md

GET /api/forum/topics

Получить список тем

Права: все авторизованные

Параметры запроса:

• groupId - Фильтр по группе
• subjectId - Фильтр по предмету
• topicType - Фильтр по типу

POST /api/forum/topics

Создать тему

Права: все авторизованные

Тело запроса:

{
  "title": "Заголовок темы",
  "content": "Содержание (MDX)",
  "topicType": "QUESTION",
  "visibility": "SUBJECT",
  "groupId": "group_id",
  "subjectId": "subject_id"
}

GET /api/forum/topics/{id}

Получить детали темы

Права: все авторизованные (с учетом visibility)

PATCH /api/forum/topics/{id}

Обновить тему

Права: admin, автор, lector (модерация)

DELETE /api/forum/topics/{id}

Удалить тему

Права: admin, автор

GET /api/forum/topics/{topicId}/posts

Получить сообщения темы

Права: все авторизованные (с учетом visibility)

POST /api/forum/topics/{topicId}/posts

Создать сообщение

Права: все авторизованные (если тема не закрыта)

Тело запроса:

{
  "content": "Содержание сообщения (MDX)",
  "parentPostId": "parent_post_id"
}

GET /api/forum/posts/{id}

Получить детали сообщения

Права: все авторизованные

PATCH /api/forum/posts/{id}

Обновить сообщение

Права: admin, автор

DELETE /api/forum/posts/{id}

Удалить сообщение

Права: admin, автор

Документы и ресурсы

См. DOCUMENTS_RESOURCES.md

GET /api/subjects/{subjectId}/documents

Получить документы предмета

Права: все авторизованные

Параметры запроса:

• type - Фильтр по типу документа

POST /api/subjects/{subjectId}/documents

Загрузить документ

Права: admin, lector

Content-Type: multipart/form-data

Параметры формы:

• file - Файл
• type - Тип документа (RPD, ANNOTATION, etc.)
• description - Описание

GET /api/subjects/{subjectId}/documents/{docId}

Получить детали документа

Права: все авторизованные

PATCH /api/subjects/{subjectId}/documents/{docId}

Обновить документ

Права: admin, lector (загрузивший)

DELETE /api/subjects/{subjectId}/documents/{docId}

Удалить документ

Права: admin, lector (загрузивший)

GET /api/subjects/{subjectId}/resources

Получить внешние ресурсы предмета

Права: все авторизованные

Параметры запроса:

• type - Фильтр по типу ресурса

POST /api/subjects/{subjectId}/resources

Добавить внешний ресурс

Права: admin, lector

Тело запроса:

{
  "type": "ZOOM",
  "title": "Zoom встреча",
  "url": "https://zoom.us/j/123456789",
  "description": "Описание"
}

GET /api/schedules/{scheduleId}/resources

Получить ресурсы занятия

Права: все авторизованные

POST /api/schedules/{scheduleId}/resources

Добавить ресурс к занятию

Права: admin, lector

GET /api/resources/{id}

Получить детали ресурса

Права: все авторизованные

PATCH /api/resources/{id}

Обновить ресурс

Права: admin, lector (создатель)

DELETE /api/resources/{id}

Удалить ресурс

Права: admin, lector (создатель)

Учебный офис

GET /api/education-office/reports

Получить отчеты учебного офиса

Права: education_office_head

GET /api/education-office/schedule

Получить общее расписание

Права: education_office_head

Кафедра

GET /api/department/reports

Получить отчеты кафедры

Права: department_admin

GET /api/department/faculty

Получить список преподавателей кафедры

Права: department_admin

GET /api/department/subjects

Получить список предметов кафедры

Права: department_admin

Коды ответов

• 200 OK - Успешный запрос
• 201 Created - Ресурс создан
• 400 Bad Request - Некорректные данные
• 401 Unauthorized - Не авторизован
• 403 Forbidden - Нет доступа
• 404 Not Found - Ресурс не найден
• 500 Internal Server Error - Ошибка сервера

Формат ошибок

{
  "error": "Описание ошибки"
}

Пагинация (планируется)

В будущих версиях API будет поддерживать пагинацию:

GET /api/endpoint?page=1&limit=20

Ответ:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Лог активности

GET /api/activity-logs

Получить список логов активности с фильтрацией и пагинацией.

Права: admin

Параметры запроса:

• userId - Фильтр по ID пользователя
• action - Фильтр по типу действия (CREATE, UPDATE, DELETE, SETTINGS_CHANGE)
• entityType - Фильтр по типу сущности (User, Group, Subject, Schedule, Homework, BotSettings)
• startDate - Дата начала периода (YYYY-MM-DD)
• endDate - Дата окончания периода (YYYY-MM-DD)
• page - Номер страницы (по умолчанию 1)
• limit - Количество записей на странице (по умолчанию 50)

Пример запроса:

GET /api/activity-logs?action=UPDATE&entityType=User&startDate=2025-11-01&page=1&limit=50

Ответ:

{
  "logs": [
    {
      "id": "clx123...",
      "userId": "user456",
      "action": "UPDATE",
      "entityType": "User",
      "entityId": "user789",
      "ipAddress": "192.168.1.100",
      "details": {
        "before": {
          "id": "user789",
          "name": "Иван Иванов",
          "role": "student"
        },
        "after": {
          "id": "user789",
          "name": "Иван Петров",
          "role": "student"
        },
        "changes": [
          {
            "field": "name",
            "oldValue": "Иван Иванов",
            "newValue": "Иван Петров"
          }
        ]
      },
      "result": "SUCCESS",
      "createdAt": "2025-11-03T20:10:57Z",
      "user": {
        "id": "user456",
        "name": "Администратор",
        "email": "admin@example.com",
        "role": "admin"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

Примечание: Логирование действий выполняется автоматически для всех CRUD операций и изменений настроек. Подробнее см. Лог активности.

Rate Limiting (планируется)

В production окружении будет применяться rate limiting:

• 100 запросов в минуту для аутентифицированных пользователей
• 10 запросов в минуту для неаутентифицированных запросов

Дополнительная документация

• Роли пользователей
• Лог активности
• Система подгрупп
• Отслеживание посещаемости
• Управление экзаменами
• Менторские встречи
• Форум и обсуждения
• Документы и ресурсы

---

Документация обновлена: 19 ноября 2025 Версия системы: 0.4.0-alpha