Build 060.30: finalize Market Data Acquisition documentation

app/README.md

@@ -1,3 +1,121 @@
-# app
+# Приложение Dzentra
 
-Здесь находятся исходный код приложения, env-файлы и зависимости.
+Каталог `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 --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 и
+не перезаписывайте существующий `.env`. Для каждого секрета разрешён либо
+прямой параметр, либо соответствующий `*_FILE`, но не оба одновременно.
+
+`requirements-dev.txt` устанавливает production dependencies и
+инструменты разработки. Production container использует проверяемый
+hash-lock `requirements.lock`; вручную редактировать его dependency
+records не следует.
+
+## Режимы 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 не
+заменяет.
+
+Назначение и безопасные команды 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 его запускать не нужно.