Приложение Dzentra
Каталог app содержит исполняемое Python-приложение, зависимости,
настройки и тесты Dzentra. Приложение объединяет Telegram-бота и
принятую Production-вертикаль Trades Feed.
Реализованные границы
| Возможность | Текущее состояние |
|---|---|
| Live Trades, reconnect и REST Recovery | Подключены к Production Runtime |
| Persistent Trades и checkpoint | Опционально подключены через MARKET_DATA_STORAGE_ENABLED |
| Startup Hydration и Recovery | Выполняются при включённом Storage |
| Historical Access и Replay | Готовы для явного вызова; автоматически не запускаются |
| Quote/Candle REST feeds | Используются существующими Trading/UI сценариями |
| Quote/Candle WebSocket и persistence | Runtime/Consistency/Recovery и persistent writers не подключены |
| Retention и месячные партиции | Только явный вызов; Scheduler их не запускает |
Подробности приведены в текущей архитектуре Trades Feed.
Требования
- Python 3.12;
- PostgreSQL, доступный по параметрам
DB_*; - Telegram Bot Token;
- отдельное виртуальное окружение
app/.venv.
PostgreSQL нужен даже при выключенных Trade Stream и Market Data Storage: обычный Bootstrap всегда инициализирует таблицы журнала и balance snapshots.
Подготовка окружения
Из корня репозитория:
python3.12 -m venv app/.venv
app/.venv/bin/python -m pip install \
--require-hashes \
-r app/requirements-dev.lock
app/.venv/bin/python -m pip check
test -e app/.env || cp app/.env.example app/.env
Замените значения-заглушки в app/.env. Не добавляйте этот файл в Git и
не перезаписывайте существующий .env. Для каждого секрета разрешён либо
прямой параметр, либо соответствующий *_FILE, но не оба одновременно.
requirements-dev.txt остаётся читаемым источником прямых developer
dependencies. Установка выполняется из requirements-dev.lock, который
сохраняет версии Production requirements.lock и добавляет pytest/Pyright.
Вручную редактировать dependency records обоих lock-файлов не следует.
Режимы Trades Feed
TRADE_STREAM_ENABLED |
MARKET_DATA_STORAGE_ENABLED |
Поведение |
|---|---|---|
false |
false |
Trade Runtime и отдельный Market Data pool не создаются |
true |
false |
Live/Recovery работают только с состоянием в памяти |
true |
true |
Добавляются persistent Trades, checkpoint, Hydration и Startup Recovery |
false |
true |
Недопустимая конфигурация; startup завершается ошибкой |
При включённом Trade Stream обязательны явные TRADE_STREAM_WS_URL,
TRADE_STREAM_SYMBOLS и EXCHANGE_BASE_URL. Полный контракт настроек и
Docker secrets находится в
эксплуатационном руководстве.
Запуск
Из каталога app:
.venv/bin/python -m src.main
Ошибка включённого Trade Runtime, Storage или Startup Recovery является фатальной и завершает всё приложение, а не оставляет Telegram polling в частично работающем состоянии.
Проверки разработчика
Обязательная отдельная проверка типов запускается из корня репозитория:
./scripts/check_python_types.sh
app/.venv/bin/python scripts/check_documentation_integrity.py
Ожидаемый результат — 0 errors, 0 warnings для Pyright и issues=0
для documentation gate. Default offline regression запускается из app:
.venv/bin/python -m pytest -q
Default-набор исключает маркеры integration, stress и live. При
этом он включает tests/static/test_python_type_gate.py, поэтому полный
запуск дополнительно контролирует Pyright. Один целевой тест этот gate не
заменяет.
Полная локальная CI-последовательность запускается из корня repository:
./scripts/run_ci_gate.sh all
Подробный manual-canary contract приведён в CI runbook.
Назначение и безопасные команды opt-in наборов:
integration— локальные сетевые и PostgreSQL-сценарии;stress— fixed stress и opt-in soak;live— только явно разрешённая проверка внешних Dzengi endpoints.
Параметры этих запусков не дублируются здесь и поддерживаются в runbook.
Структура и навигация
src/— production-код;tests/unit/иtests/static/— default offline regression;tests/integration/,tests/stress/,tests/live/— opt-in проверки;scripts/иtools/— диагностические и исследовательские утилиты, не automatic Production Runtime;- обзор структуры проекта;
- границы пакета Storage;
- архитектура Build 060.30.
Корневой bootstrap_project.py является историческим генератором
каркаса. Для текущего checkout его запускать не нужно.