API — LITE SOFT DEV

Публичный REST API портала — маршруты /api/v1 по группам.

Публичный API живёт на WEB PORTAL под префиксом /api/v1. Браузер обращается только сюда; внутренний API NEURO CORE описан отдельно.

Версионирование API

Версия в пути. Ломающее изменение — новый префикс /api/v2, старый продолжает работать.

Вход в систему

POST/api/v1/auth/login

Вход по техническому ID школьника. Пароль не используется: идентификатор выдаёт школа. При успехе сервер создаёт сессию и кладёт её в httpOnly cookie — токен недоступен из JavaScript.

student_idstringобязательный

Технический ID, выданный школой.

Запрос

{
  "student_id": "stu-2041-0187"
}

Ответ 200 (Set-Cookie: session=…; HttpOnly)

{
  "user": {
    "id": "u-71bc04",
    "role": "student",
    "grade": 9
  },
  "expires_at": "2026-07-13T18:00:00Z"
}

Список курсов

GET/api/v1/courses

Возвращает курсы, доступные текущему пользователю, с кратким прогрессом по каждому. Требует активной сессии.

Ответ 200

{
  "courses": [
    {
      "id": "course-01",
      "title": "Морские профессии региона",
      "modules": 8,
      "progress": 0.62
    },
    {
      "id": "course-02",
      "title": "Основы судовождения",
      "modules": 12,
      "progress": 0.0
    }
  ]
}

Курс: материалы и прогресс

GET/api/v1/courses/{id}

Материалы курса и детальный прогресс пользователя по модулям.

idstringобязательный

Идентификатор курса в пути запроса.

Ответ 200

{
  "id": "course-01",
  "title": "Морские профессии региона",
  "modules": [
    {
      "id": "m-1",
      "title": "Порт и логистика",
      "completed": true
    },
    {
      "id": "m-2",
      "title": "Судовождение",
      "completed": false
    }
  ],
  "progress": 0.62
}

Список диалогов ассистента

GET/api/v1/assistant/sessions

Диалоги текущего пользователя с ИИ-ассистентом, отсортированы по последней активности.

Ответ 200

{
  "sessions": [
    {
      "id": "s-3f9a12",
      "title": "Профессии моря",
      "updated_at": "2026-07-12T14:03:11Z"
    }
  ]
}

Начать диалог

POST/api/v1/assistant/sessions

Создаёт новый диалог с ассистентом. Тело можно не передавать — сценарий по умолчанию общий.

scenariostring

Сценарий диалога, например career. Необязателен.

Запрос

{
  "scenario": "career"
}

Ответ 201

{
  "id": "s-8c2e77",
  "scenario": "career",
  "created_at": "2026-07-13T09:15:40Z"
}

История сообщений

GET/api/v1/assistant/sessions/{id}/messages

Сообщения диалога в хронологическом порядке. RBAC: пользователь видит только собственные диалоги.

idstringобязательный

Идентификатор диалога в пути запроса.

Ответ 200

{
  "messages": [
    {
      "id": "msg-01",
      "role": "user",
      "text": "Какие профессии связаны с морем?"
    },
    {
      "id": "msg-02",
      "role": "assistant",
      "text": "Судовождение — одна из ключевых профессий региона…"
    }
  ]
}

Отправить сообщение

POST/api/v1/assistant/sessions/{id}/messages

Отправляет вопрос ассистенту. Ответ — поток токенов через WebSocket (см. Realtime), а не обычный JSON.

idstringобязательный

Идентификатор диалога в пути запроса.

textstringобязательный

Текст сообщения пользователя.

Что происходит внутри:

RBAC: школьник владеет сессией.
Проверка кэша LLM в Redis — попадание отвечает мгновенно.
Обезличивание данных.
POST /v1/chat на NEURO CORE, стрим ответа в WebSocket.
Диалог сохраняет NEURO CORE Service — портал в MongoDB не пишет.

Запрос

{
  "text": "Какие профессии связаны с морем в нашем регионе?"
}

Стрим (WebSocket, сервер → клиент)

{ "type": "token", "data": "Судово" }
{ "type": "token", "data": "ждение — " }
{ "type": "done",  "data": { "message_id": "msg-03" } }

Профиль интересов

GET/api/v1/career/interests

Профиль интересов пользователя и его динамика по времени.

Ответ 200

{
  "interests": [
    { "tag": "море", "weight": 0.92 },
    { "tag": "техника", "weight": 0.71 }
  ],
  "dynamics": [
    { "month": "2026-05", "top": "техника" },
    { "month": "2026-06", "top": "море" }
  ]
}

Админка

Группа маршрутов /api/v1/admin/... (все методы) — школы, курсы, опросы и аналитика. Доступ разграничен ролями RBAC; детальные поля описываются по мере стабилизации админки.

Загрузка вне API

В MVP материалы RAG загружаются через папку private_knowledge на NEURO CORE, не через API. Загрузка через админку — следующий этап.

Примеры маршрутов

GET  /api/v1/admin/schools
POST /api/v1/admin/courses
GET  /api/v1/admin/analytics/usage

Не является API

MongoDB, Qdrant, vLLM, ingest worker и Redis — внутренние компоненты. Из интернета к ним не обратиться: только через Go-API портала или NEURO CORE Service.