первый коммит

2026-02-27 21:28:09 +03:00
parent 1e376aff24
commit e8805ffe29
171 changed files with 6400 additions and 556 deletions
--- a/app/modules/chat/README.md
+++ b/app/modules/chat/README.md
@@ -0,0 +1,98 @@
+# Модуль chat
+
+## 1. Функции модуля
+- Внешний API чата: создание диалога, отправка сообщения, получение статуса задачи.
+- Асинхронная оркестрация выполнения через `ChatOrchestrator`.
+- Idempotency и стриминг событий по SSE.
+
+## 2. Диаграмма классов и взаимосвязей
+```mermaid
+classDiagram
+    class ChatModule
+    class ChatOrchestrator
+    class TaskStore
+    class DialogSessionStore
+    class IdempotencyStore
+    class EventBus
+    class AgentRunner
+
+    ChatModule --> ChatOrchestrator
+    ChatModule --> TaskStore
+    ChatModule --> DialogSessionStore
+    ChatModule --> IdempotencyStore
+    ChatModule --> EventBus
+    ChatOrchestrator --> AgentRunner
+    ChatOrchestrator --> TaskStore
+    ChatOrchestrator --> DialogSessionStore
+    ChatOrchestrator --> EventBus
+```
+
+## 3. Описание классов
+- `ChatModule`: фасад модуля и регистрация публичных chat endpoint'ов.
+  Методы: `__init__` — собирает stores/orchestrator; `public_router` — публикует REST и SSE маршруты чата.
+- `ChatOrchestrator`: выполняет жизненный цикл user-message как фоновой задачи.
+  Методы: `enqueue_message` — создает задачу и запускает обработку; `_process_task` — исполняет runtime и сохраняет результат; `_resolve_sessions` — валидирует и сопоставляет dialog/rag сессии.
+- `TaskStore`: in-memory store состояний задач.
+  Методы: `create` — создает новую `TaskState`; `get` — возвращает задачу по `task_id`; `save` — обновляет состояние задачи.
+- `DialogSessionStore`: хранилище dialog-сессий поверх БД.
+  Методы: `create` — создает новую dialog-сессию; `get` — читает dialog-сессию по id.
+- `IdempotencyStore`: предотвращает дубль задач по идемпотентному ключу.
+  Методы: `get_task_id` — возвращает существующий `task_id` по ключу; `put` — сохраняет ключ и `task_id`.
+- `EventBus`: асинхронная публикация/подписка событий.
+  Методы: `subscribe` — создает подписку на канал; `unsubscribe` — снимает подписку; `publish` — отправляет событие подписчикам; `as_sse` — сериализует событие в SSE формат.
+- `AgentRunner` (контракт): интерфейс выполнения агентного запроса из chat-слоя.
+  Методы: `run` — принимает данные задачи и возвращает итог `answer`/`changeset`.
+
+## 4. Сиквенс-диаграммы API
+
+### POST /api/chat/dialogs
+Назначение: создает новый диалог, связанный с существующей `rag_session`, чтобы пользователь мог отправлять сообщения в контексте конкретного индекса.
+```mermaid
+sequenceDiagram
+    participant Router as ChatModule.APIRouter
+    participant RagSessions as RagSessionStore
+    participant Dialogs as DialogSessionStore
+
+    Router->>RagSessions: get(rag_session_id)
+    RagSessions-->>Router: exists
+    Router->>Dialogs: create(rag_session_id)
+    Dialogs-->>Router: dialog_session
+```
+
+### POST /api/chat/messages
+Назначение: ставит сообщение пользователя в асинхронную обработку и возвращает `task_id` для отслеживания результата.
+```mermaid
+sequenceDiagram
+    participant Router as ChatModule.APIRouter
+    participant Orchestrator as ChatOrchestrator
+    participant TaskStore as TaskStore
+
+    Router->>Orchestrator: enqueue_message(request, idempotency_key)
+    Orchestrator->>TaskStore: create()/save()
+    Orchestrator-->>Router: task_id,status
+```
+
+### GET /api/tasks/{task_id}
+Назначение: отдает текущее состояние задачи и финальный результат (answer/changeset/error), когда обработка завершена.
+```mermaid
+sequenceDiagram
+    participant Router as ChatModule.APIRouter
+    participant TaskStore as TaskStore
+
+    Router->>TaskStore: get(task_id)
+    TaskStore-->>Router: task_state
+```
+
+### GET /api/events?task_id=...
+Назначение: открывает SSE-поток с прогрессом выполнения задачи и промежуточными событиями.
+```mermaid
+sequenceDiagram
+    participant Router as ChatModule.APIRouter
+    participant Events as EventBus
+
+    Router->>Events: subscribe(task_id)
+    loop until disconnect
+        Events-->>Router: SSE event
+    end
+    Router->>Events: unsubscribe(task_id)
+```