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)
|
||
```
|