dzentra_bot/README.md

Dzentra

Dzentra — модульный монолит автоматической торговой системы с Telegram-интерфейсом. В текущем принятом Production scope полностью собрана вертикаль Trades Feed: получение сделок, проверка последовательности, reconnect/recovery, опциональное сохранение в PostgreSQL и восстановление после перезапуска.

Текущий scope

• Production ingestion, Consistency, Recovery, persistent checkpoint и Startup Recovery реализованы для Trades.
• Historical Access и deterministic Replay доступны как отдельные API и не запускаются автоматически.
• REST-потоки Quotes и Candles продолжают использоваться Trading/UI. Новые WebSocket Runtime, Consistency/Recovery и persistent writer wiring для них пока не подключены.
• Retention и создание месячных партиций выполняются только явным вызовом.
• Обычный запуск приложения требует PostgreSQL для журнала и balance snapshots, даже если Trade Stream и Market Data Storage выключены.

Подробное фактическое состояние описано в архитектуре Trades Feed.

Быстрый старт существующего checkout

Требуются Python 3.12, доступный PostgreSQL и Telegram Bot Token. Команды выполняются из корня репозитория:

python3.12 -m venv app/.venv
app/.venv/bin/python -m pip install --upgrade pip
app/.venv/bin/python -m pip install -r app/requirements-dev.txt
test -e app/.env || cp app/.env.example app/.env

Заполните созданный app/.env, не добавляйте его в Git и не перезаписывайте уже существующий файл. Затем запустите приложение:

cd app
.venv/bin/python -m src.main

Настройки режимов, PostgreSQL и безопасный Docker-запуск приведены в эксплуатационном руководстве. Более подробная инструкция для разработчика находится в app/README.md.

Обязательные проверки

Из корня репозитория:

./scripts/check_python_types.sh
app/.venv/bin/python scripts/check_documentation_integrity.py

Ожидаемый результат Pyright — 0 errors, 0 warnings, а documentation gate — issues=0. Обычная offline-регрессия запускается из app:

cd app
.venv/bin/python -m pytest -q

Default pytest-набор исключает opt-in группы integration, stress и live, но включает статическую проверку Pyright. Целевой тест не заменяет полный type gate.

Навигация

• Обзор архитектуры
• Структура проекта
• Текущая архитектура Trades Feed
• Эксплуатация Trade Stream Runtime
• Архитектура Build 060.30

Исторический bootstrap

bootstrap_project.py — исторический генератор первоначального каркаса. Для установки или запуска существующего checkout его использовать не нужно.