Build 060.30: finalize Market Data Acquisition documentation

README.md

@@ -1,33 +1,83 @@
-# dzentra_bot
+# Dzentra
 
-Telegram-бот для автоторговли криптовалютой.
+Dzentra — модульный монолит автоматической торговой системы с
+Telegram-интерфейсом. В текущем принятом Production scope полностью
+собрана вертикаль Trades Feed: получение сделок, проверка
+последовательности, reconnect/recovery, опциональное сохранение в
+PostgreSQL и восстановление после перезапуска.
 
-## Bootstrap v2
-Это стабильный стартовый каркас проекта с:
-- чистой структурой каталогов
-- компактным верхним меню
-- базовыми handlers
-- документацией
-- Docker-файлами
-- опциональным созданием `.venv`, установкой зависимостей и первым git commit
+## Текущий 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](docs/architecture/trades_feed.md).
+
+## Быстрый старт существующего checkout
+
+Требуются Python 3.12, доступный PostgreSQL и Telegram Bot Token. Команды
+выполняются из корня репозитория:
 
-## Рекомендуемый запуск
 ```bash
-/opt/homebrew/bin/python3.12 bootstrap_project.py --with-venv --with-install
+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
 ```
 
-## После bootstrap
+Заполните созданный `app/.env`, не добавляйте его в Git и не
+перезаписывайте уже существующий файл. Затем запустите приложение:
+
 ```bash
 cd app
-source .venv/bin/activate
-python -m src.main
+.venv/bin/python -m src.main
 ```
+
+Настройки режимов, PostgreSQL и безопасный Docker-запуск приведены в
+[эксплуатационном руководстве](docs/operations/trades_feed_runtime.md).
+Более подробная инструкция для разработчика находится в
+[app/README.md](app/README.md).
+
+## Обязательные проверки
+
+Из корня репозитория:
+
+```bash
+./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`:
+
+```bash
+cd app
+.venv/bin/python -m pytest -q
+```
+
+Default pytest-набор исключает opt-in группы `integration`, `stress` и
+`live`, но включает статическую проверку Pyright. Целевой тест не
+заменяет полный type gate.
+
+## Навигация
+
+- [Обзор архитектуры](docs/architecture/overview.md)
+- [Структура проекта](docs/architecture/project_structure.md)
+- [Текущая архитектура Trades Feed](docs/architecture/trades_feed.md)
+- [Эксплуатация Trade Stream Runtime](docs/operations/trades_feed_runtime.md)
+- [Архитектура Build 060.30](docs/migrations/build_060_30_architecture.md)
+
+## Исторический bootstrap
+
+`bootstrap_project.py` — исторический генератор первоначального каркаса.
+Для установки или запуска существующего checkout его использовать не
+нужно.