# Приложение 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 его запускать не нужно.