ai-tutor-module 1.0.0

package/README.md

@@ -0,0 +1,151 @@
+# AI Tutor Module (Short Integration Guide)
+
+## Назначение
+
+**AI Tutor Module** — это встраиваемый чат-модуль с AI-ассистентом для образовательной платформы совместного обучения.
+
+Модуль предоставляет:
+
+* диалог пользователя с AI;
+* историю чатов;
+* потоковые ответы AI;
+* редактирование сообщений с переответом;
+* панель материалов;
+* сбор агрегированной статистики использования.
+
+---
+
+## Формат поставки
+
+Модуль поставляется **в виде npm-пакета** и подключается к платформе как **React-компонент**.
+
+```tsx
+import AiTutorModule from "ai-tutor-module";
+
+<AiTutorModule />
+```
+
+---
+
+## Интеграция с платформой
+
+### 1. Передача данных при создании виджета
+
+Платформа должна передать модулю информацию о контексте через функцию `getInfo`:
+
+```json
+{
+  "widgetId": number,
+  "userId": number,
+  "role": string,
+  "config": object,
+  "board": {
+    "id": number,
+    "name": string,
+    "parentId": number
+  }
+}
+```
+
+Эти данные используются модулем для:
+
+* работы с backend;
+* отправки статистики;
+* синхронизации состояния виджета.
+
+---
+
+### 2. Backend API (обязательный минимум)
+
+Модуль ожидает наличие следующих API:
+
+* авторизация (Bearer Token);
+* управление чатами (создание / удаление / список);
+* отправка сообщений с **потоковым (streaming) ответом**;
+* получение истории чата;
+* редактирование сообщения с переответом AI.
+
+Формат истории сообщений:
+
+```json
+{
+  "messages": [
+    {
+      "id": "string",
+      "role": "user | assistant",
+      "text": "string",
+      "created_at": "ISO-8601"
+    }
+  ]
+}
+```
+
+---
+
+### 3. Потоковые ответы AI
+
+Ответ AI передаётся:
+
+* chunked HTTP response;
+* plain text;
+* с маркером завершения `[DONE]`.
+
+Модуль отображает ответ **по мере получения чанков**.
+
+---
+
+### 4. Статистика
+
+Модуль отправляет **агрегированную статистику** использования во внешний сервис статистики:
+
+* количество чатов;
+* количество сообщений;
+* активное состояние UI.
+
+Модуль **не логирует события**, а отправляет только агрегированные данные.
+
+---
+
+### 5. Закрытие модуля
+
+Для закрытия модуль отправляет событие:
+
+```js
+window.postMessage({ type: "AI_TUTOR_MODULE_CLOSE" }, "*");
+```
+
+Платформа должна обработать это событие и закрыть/удалить модуль.
+
+---
+
+## Ответственность сторон
+
+**Фронтенд (модуль):**
+
+* UI / UX;
+* логика чата;
+* потоковый вывод;
+* мобильная и десктопная версия;
+* статистика.
+
+**Backend:**
+
+* AI-логика;
+* хранение истории;
+* streaming API;
+* авторизация.
+
+**Платформа:**
+
+* встраивание модуля;
+* передача контекста (`getInfo`);
+* жизненный цикл виджета;
+* обработка закрытия.
+
+---
+
+## Статус
+
+- Модуль готов к интеграции
+- Поддерживает streaming
+- Адаптирован под мобильные устройства