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

app/modules/shared/README.md

@@ -0,0 +1,40 @@
+# Модуль shared
+
+## 1. Функции модуля
+- Общие инфраструктурные компоненты для всех модулей:
+  - подключение к БД (`db.py`, `bootstrap.py`),
+  - шина событий (`event_bus.py`),
+  - retry и idempotency (`retry_executor.py`, `idempotency_store.py`),
+  - checkpointer,
+  - клиент и настройки GigaChat (`gigachat/*`).
+
+## 2. Диаграмма классов и взаимосвязей
+```mermaid
+classDiagram
+    class EventBus
+    class RetryExecutor
+    class IdempotencyStore
+    class GigaChatClient
+    class GigaChatSettings
+    class GigaChatTokenProvider
+
+    GigaChatClient --> GigaChatSettings
+    GigaChatClient --> GigaChatTokenProvider
+```
+
+## 3. Описание классов
+- `EventBus`: общий асинхронный event-bus для публикации и SSE-стриминга.
+  Методы: `subscribe` — подписка на канал; `unsubscribe` — удаление подписки; `publish` — отправка события; `as_sse` — сериализация события в SSE-формат.
+- `RetryExecutor`: общий механизм повторных попыток для временных ошибок.
+  Методы: `run` — выполняет async-операцию с retry по временным исключениям.
+- `IdempotencyStore`: in-memory хранилище идемпотентных ключей.
+  Методы: `get_task_id` — находит ранее созданную задачу по ключу; `put` — сохраняет ключ и task_id.
+- `GigaChatSettings`: конфигурация доступа к GigaChat.
+  Методы: `from_env` — собирает настройки из переменных окружения.
+- `GigaChatTokenProvider`: управление access token для GigaChat API.
+  Методы: `get_access_token` — возвращает валидный токен (с обновлением при необходимости).
+- `GigaChatClient`: HTTP-клиент для completion и embeddings.
+  Методы: `complete` — выполняет генерацию ответа модели; `embed` — получает векторные представления для списка текстов.
+
+## 4. Сиквенс-диаграммы API
+В модуле нет HTTP endpoint'ов: он предоставляет только инфраструктурные классы для других модулей.