133 lines
6.4 KiB
Markdown
133 lines
6.4 KiB
Markdown
# Приложение 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](../docs/architecture/trades_feed.md).
|
||
|
||
## Требования
|
||
|
||
- Python 3.12;
|
||
- PostgreSQL, доступный по параметрам `DB_*`;
|
||
- Telegram Bot Token;
|
||
- отдельное виртуальное окружение `app/.venv`.
|
||
|
||
PostgreSQL нужен даже при выключенных Trade Stream и Market Data Storage:
|
||
обычный Bootstrap всегда инициализирует таблицы журнала и balance
|
||
snapshots.
|
||
|
||
## Подготовка окружения
|
||
|
||
Из корня репозитория:
|
||
|
||
```bash
|
||
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 находится в
|
||
[эксплуатационном руководстве](../docs/operations/trades_feed_runtime.md).
|
||
|
||
## Запуск
|
||
|
||
Из каталога `app`:
|
||
|
||
```bash
|
||
.venv/bin/python -m src.main
|
||
```
|
||
|
||
Ошибка включённого Trade Runtime, Storage или Startup Recovery является
|
||
фатальной и завершает всё приложение, а не оставляет Telegram polling в
|
||
частично работающем состоянии.
|
||
|
||
## Проверки разработчика
|
||
|
||
Обязательная отдельная проверка типов запускается из корня репозитория:
|
||
|
||
```bash
|
||
./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`:
|
||
|
||
```bash
|
||
.venv/bin/python -m pytest -q
|
||
```
|
||
|
||
Default-набор исключает маркеры `integration`, `stress` и `live`. При
|
||
этом он включает `tests/static/test_python_type_gate.py`, поэтому полный
|
||
запуск дополнительно контролирует Pyright. Один целевой тест этот gate не
|
||
заменяет.
|
||
|
||
Полная локальная CI-последовательность запускается из корня repository:
|
||
|
||
```bash
|
||
./scripts/run_ci_gate.sh all
|
||
```
|
||
|
||
Подробный manual-canary contract приведён в
|
||
[CI runbook](../docs/operations/ci_gate.md).
|
||
|
||
Назначение и безопасные команды opt-in наборов:
|
||
|
||
- `integration` — локальные сетевые и PostgreSQL-сценарии;
|
||
- `stress` — fixed stress и opt-in soak;
|
||
- `live` — только явно разрешённая проверка внешних Dzengi endpoints.
|
||
|
||
Параметры этих запусков не дублируются здесь и поддерживаются в
|
||
[runbook](../docs/operations/trades_feed_runtime.md).
|
||
|
||
## Структура и навигация
|
||
|
||
- `src/` — production-код;
|
||
- `tests/unit/` и `tests/static/` — default offline regression;
|
||
- `tests/integration/`, `tests/stress/`, `tests/live/` — opt-in проверки;
|
||
- `scripts/` и `tools/` — диагностические и исследовательские утилиты,
|
||
не automatic Production Runtime;
|
||
- [обзор структуры проекта](../docs/architecture/project_structure.md);
|
||
- [границы пакета Storage](src/storage/README.md);
|
||
- [архитектура Build 060.30](../docs/migrations/build_060_30_architecture.md).
|
||
|
||
Корневой `bootstrap_project.py` является историческим генератором
|
||
каркаса. Для текущего checkout его запускать не нужно.
|