99 lines
5.0 KiB
Markdown
99 lines
5.0 KiB
Markdown
# Модуль 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)
|
|
```
|