# Модуль 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)
```