# Master Roadmap — Dzentra Bot

## Цель проекта
Создать Telegram-бота для:
- ручной торговли;
- мониторинга рынка;
- автоторговли;
- аналитики;
- управления стратегиями.

---

# Stage 01 — Bootstrap / Foundation
✔ app bootstrap  
✔ config layer  
✔ logging  
✔ router bootstrap  
✔ DB bootstrap  

✅ Статус: завершён

---

# Stage 02 — System / Diagnostics
✔ system screen  
✔ exchange health  
✔ DB health  
✔ runtime info  
✔ error rendering  

✅ Статус: завершён

---

# Stage 03 — Exchange Integration
✔ mock exchange  
✔ time handling  
✔ exchangeInfo  
✔ private auth  
✔ account + portfolio  
✔ market live polling  
⚠ websocket research / fallback polling  

✅ Статус: завершён (fallback mode)

---

# Stage 04 — Storage / Journal
✔ storage foundation  
✔ event log  
✔ repositories  
✔ UI integration  
✔ journal management  

✅ Статус: завершён

---

# Stage 05 — Trading UI / Draft / Validation
✔ order draft flow  
✔ interactive builder  
✔ validation  
✔ runtime mode helpers  
✔ UI unification  
✔ quantity normalization  

✅ Статус: завершён

---

# Stage 06 — Journal / Navigation / Settings
✔ journal UI  
✔ navigation improvements  
✔ settings screen  
✔ system info  

✅ Статус: завершён

---

# Stage 07 — Auto Trading

## 07.1 — Skeleton UI
✔ экран автоторговли  
✔ state machine  

## 07.2 — Real settings
✔ стратегия  
✔ риск  
✔ символ  
✔ leverage (default x2)

## 07.3 — Analysis Cycle
✔ run_cycle()  
✔ mock signals  
✔ live updates  

### 07.3.1 — Background Runner
✔ asyncio loop  

### 07.3.2 — Live Screens
✔ market  
✔ portfolio  
✔ journal  

### 07.3.3 — Multi Live
✔ multi-screen  
✔ duplicate protection  

### 07.3.4 — Monitoring redesign
✔ новый экран мониторинга  

### 07.3.5 — WebSocket probe
✔ ws skeleton  
⚠ fallback REST polling  

## 07.4 — Strategy Plugin Architecture

### 07.4.1
✔ BaseStrategy  
✔ SignalResult  

### 07.4.2
✔ Strategy Registry  

### 07.4.3 — Trend Strategy
✔ signal generation  
✔ repeat confirmation logic  
✔ confidence scoring  
✔ UI integration  

#### 07.4.3.1 — UI Optimization ✅
✔ compact auto screen  
✔ state-based rendering (OFF / RUNNING / OBSERVING)  
✔ minimal trading layout  
✔ duplicate info removal  

#### 07.4.3.2 — Engine Decoupling (NEXT) ✅
✔ split analysis / UI refresh  
✔ fast price polling (1s)  
✔ slow UI updates (event-driven / 60s)  
✔ anti-flood protection

#### 07.4.3.3 — Paper Position & Execution Engine ✅
- добавлен ExecutionEngine
- реализованы paper-позиции (LONG / SHORT)
- интеграция с AutoTradeService
- синхронизация с UI
- логирование paper execution
- EventBus события (paper_position_opened)

#### Stage 07.4.3.4 — Telegram Strong Signal Alerts ✅
- EventBus-driven уведомления
- Фильтрация READY сигналов
- Поддержка BUY / SELL
- Анти-спам (deduplication)
- Интеграция с Journal
- Runner полностью управляет Telegram-уведомлениями

#### Stage 07.4.3.5 — Debug Commands & Test Mode ✅
- DEBUG_ENABLED env flag
- debug_force_signal API
- instant EventBus processing
- Telegram debug commands
- state inspection (/debug_state)
- journal logging for debug actions
- full pipeline testing without market dependency

#### Stage 07.4.3.6 - Smart Alert Throttling ✅
- cooldown для Telegram сигналов
- suppression повторных BUY/SELL
- journal logging suppressed событий
- не влияет на execution pipeline

#### 07.4.3.7 — Alert priority & UX improvements ✅
- priority levels: HIGH / MEDIUM / LOW
- improved Telegram alert layout
- normalized symbol & leverage formatting
- compatible with cooldown & suppression
- extended debug_signal parameters

#### 07.4.3.8 — Telegram Execution Alerts ✅
- Telegram alerts for paper position opened
- Telegram alerts for paper position closed
- Entry / Exit / Size / PnL rendering
- readable USD formatting
- signal alerts separated from execution alerts

#### 07.4.3.9 — Position flip flow ✅
- instant LONG ↔ SHORT reversal (FLIP)
- new EventBus event: paper_position_flipped
- unified execution alert for flip
- improved execution realism (no idle gap)

#### 07.4.3.10 — Auto UI Refactor & Live Screen ✅

- разделение auto.py → main.py + ui.py
- единый render-пайплайн через AutoTradeRunner
- live-обновление экрана без дублирования сообщений
- компактный UI: Signal / Decision / Position / PnL
- отображение Position Risk и Est. Size
- унификация форматирования (USD / price / leverage)
- защита от лишних edit (message is not modified)

#### 07.4.3.11 — Risk Settings UI & UX ✅

- отдельный экран Risk Settings (SL / TP / Max Loss)
- FSM-ввод значений (проценты и USD)
- inline-редактирование (без новых сообщений)
- временные статусы (auto-clear через ~2.5 сек)
- защита от race condition (убран “скачок” экранов)
- reset risk controls (все параметры → off)
- интеграция в Auto screen (Controls строка)
- интеграция в Settings (Risk Controls summary)
- единая навигация: Auto ↔ Settings ↔ Risk
- UX-подсказки и валидация ввода

#### 07.4.3.12 — Real Risk Engine (execution-level) ✅
- risk checks внутри ExecutionEngine
- SL / TP / ML закрывают позицию
- forced close с risk_reason
- интеграция в основной цикл автоторговли
- Telegram execution alerts с причиной риска
- единая точка принятия решений (execution layer)

#### 07.4.3.13 — Risk-Based Position Sizing & Margin Protection ✅
- risk-based position sizing через SL distance
- размер позиции теперь рассчитывается от Risk %
- execution-level margin validation
- защита от oversized positions
- max reserved balance limit
- execution block reason state
- блокировка ENTRY / FLIP при превышении margin limit
- compact mobile UI redesign
- новый формат SL / TP / ML
- compact position rendering
- estimated margin preview
- max reserved preview
- execution blocked status в UI
- улучшенный mobile formatting
- SL стал обязательным для risk-engine sizing
- risk_percent теперь реально влияет на размер позиции
- flip теперь проходит через margin protection

#### 07.4.3.14 — Auto UI, Realistic Pricing & Debug Live Tools ✅
- redesigned RUNNING auto-trading UI
- HOLD / BUY / SELL / READY state separation
- compact signal rendering with real duration
- confidence hidden for HOLD state
- direction-aware LONG / SHORT UI blocks
- compact active position rendering
- removed zero-value UI noise without position
- realistic bid / ask pricing in auto UI
- realistic bid / ask execution pricing
- TREND strategy switched to mid-price analysis
- corrected own funds / margin calculations
- safer size rounding for margin protection
- signal_started_at support for real-time duration tracking
- improved auto screen refresh handling
- live UI refresh diagnostics in AutoTradeRunner
- new debug UI-state commands
- new paper execution debug commands
- automatic flip direction detection
- live paper execution monitoring commands
- integration testing flow for SL / TP / ML
- integration testing flow for execution alerts
- preparation for isolated debug runtime architecture

#### 07.4.3.15 — Isolated Debug Runtime & Debug Auto Screen ✅

- isolated DebugTradeState
- isolated DebugPositionState
- isolated DebugTradeService
- isolated DebugExecutionEngine
- isolated DebugTradeRunner
- separate `/debug_auto_screen`
- separate debug auto UI
- debug commands no longer mutate AutoTradeService
- debug execution no longer mutates ExecutionEngine._position
- debug runner no longer uses AutoTradeRunner
- `/debug_live` disabled as production-runtime injector
- legacy debug commands redirected to isolated debug runtime
- debug LONG / SHORT / FLIP / CLOSE sandbox flow
- debug Start / Stop / Reset controls
- debug PnL live refresh
- debug margin / reserved rendering
- debug bid / ask execution pricing
- fresh REST snapshot support for debug execution
- debug_auto router added
- ordinary 🤖 Автоторговля screen remains unchanged by debug commands
- preparation for production execution pricing layer

#### 07.4.3.16 — Production Execution Pricing Layer

- added isolated runtime market caches
- separated AUTO and DEBUG websocket pricing
- added execution snapshot layer
- added freshness-aware execution pricing
- implemented websocket-first market sourcing
- added REST fallback pricing pipeline
- fixed signal timer reset after START
- removed shared market cache collisions
- stabilized AUTO/DEBUG UI market rendering

#### 07.4.3.17 — Unified Active Screen Lifecycle

- внедрён единый lifecycle основных экранов
- реализовано автоматическое закрытие предыдущего экрана
- устранено накопление Telegram UI-экранов
- унифицировано поведение всех основных экранов
- разделены UI lifecycle и background runtime
- сохранена фоновая работа AutoTradeRunner
- сохранена фоновая работа DebugTradeRunner
- стабилизирована работа live-экранов
- подготовлена архитектура для Telegram push-уведомлений
- подготовлена база для runtime event notifications

#### 07.4.3.18.1 — Runtime Event Skeleton Architecture
- добавлен слой runtime_events
- добавлен слой notifications
- создана модель RuntimeEvent
- создана модель NotificationMessage
- добавлен RuntimeEventPublisher
- добавлен NotificationService skeleton
- добавлен TelegramNotificationChannel
- добавлен NotificationTargetRegistry
- добавлена базовая дедупликация уведомлений
- добавлены шаблоны signal/execution notifications
- зарегистрирован Telegram bot в notification target registry
- зарегистрирован default chat из AUTO/DEBUG runners
- исправлен circular import в package init файлах
- подготовлена архитектура для переноса strong signal alerts

#### 07.4.3.18.2 ✅ Runtime Notification Migration
- strong signal alerts migrated to RuntimeEvent pipeline
- execution alerts migrated to RuntimeEvent pipeline
- detached Telegram delivery
- centralized notification logging
- runtime notification dedupe
- live runtime validation on real paper execution
- auto screen independence from notifications

---

### 07.4.3.19 — Strategy Audit & Signal Quality Layer
- audit SCALP false flip behavior
- add position-aware signal handling
- prevent weak/medium signal flips
- add min hold time before flip
- add flip cooldown
- add spread/slippage buffer
- classify signals as ENTRY / HOLD / EXIT / FLIP
- tune SCALP thresholds

#### 07.4.3.19.1 - Position-aware Flip Protection
- добавлена проверка confidence перед flip
- добавлено подтверждение flip по количеству повторов сигнала
- добавлена минимальная длительность удержания позиции перед flip
- добавлена защита от flip в убыточной позиции без сильного сигнала
- реализована блокировка flip через RuntimeEvent logging
- добавлен dedupe для повторяющихся событий flip-блокировки через _last_flip_block_key
- синхронизировано execution-state после ENTRY / FLIP / CLOSE
- исправлена очистка ghost-позиций после forced exit
- стабилизирован lifecycle paper execution во время ночного runtime-тестирования

#### 07.4.3.19.2 — Journal Noise Reduction & Position-aware Signal Logg
Снижение шума журнала и position-aware signal logging ✅
- отключено журналирование auto_screen_refresh_skipped
- отключено журналирование auto_screen_refreshed
- сохранено журналирование ошибок refresh-цикла
- добавлено подавление сигналов, совпадающих с открытой позицией
- добавлен throttled summary auto_position_aligned_signal_suppressed
- снижено количество повторных strong signal уведомлений
- сохранена обработка противоположных сигналов как reversal / flip candidates
- подготовлена база для Signal Intent Layer в следующем этапе

#### 07.4.3.19.3 ✅ Strategy Noise Filter & Signal Intent Layer
- убрано журналирование одиночных BUY / SELL без серии
- HOLD-серии переведены с repeat-count на duration формат
- добавлен формат 🟡 HOLD 5м 36с завершён сигналом SELL
- добавлен signal_intent в payload сигналов
- добавлены intent-типы ENTRY_CANDIDATE, REVERSAL_CANDIDATE, REINFORCE_POSITION, HOLD_MARKET, NOISE
- добавлена position-aware интерпретация сигналов
- добавлено отдельное событие готового сигнала
- подготовлена база для стандартизации журнала в 07.4.3.19.4

#### 07.4.3.19.4 ✅ Journal Runtime Standardization & Export Layer
- унифицированы execution event_type
- удалены legacy paper_* события
- execution logging переведён в единый human-readable стиль
- унифицированы market runtime events
- стандартизирован export logging
- добавлены account-aware export filename
- добавлены [DEMO]/[LIVE] runtime prefixes
- унифицированы risk-control journal events
- централизован EVENT_TITLES mapping
- журнал подготовлен к filters/search layer

---

### 07.4.4

#### 07.4.4.1.1 ✅ Market State Human UI + HOLD Lifecycle Fix
- добавлено короткое human-readable отображение состояния рынка
- технические market_state значения скрыты из основного Auto UI
- убраны `trend=...` и `volatility=...` из Telegram-экрана
- убран timeframe анализа из основного UI как лишняя техническая деталь
- добавлены UI-состояния `📈 Рынок · Рост`, `📉 Рынок · Падение`, `🟰 Рынок · Флэт`, `⚠️ Рынок · Волатильность`, `⏳ Рынок · Анализ`
- подтверждена работа REST klines как основы аналитики рынка
- Market State Engine переведён на анализ свечей OHLCV
- добавлены EMA20 / EMA50 для определения направления тренда
- добавлен ATR для оценки волатильности рынка
- добавлен RSI в аналитический payload
- TREND-стратегия стала market-aware и использует состояние рынка как фильтр входа
- market analysis синхронизируется в AutoTradeState
- исправлен баг ложного завершения `HOLD → HOLD`
- HOLD summary теперь пишется только при реальной смене сигнала
- этап подготовил основу для Market State Journal Events и BTC/ETH Relative Strength Layer

#### 07.4.4.1.2 ✅ Market State Journal Events
- добавлено journal logging изменений состояния рынка
- реализован market-state transition tracking
- добавлены market_state_changed события
- добавлены market_trend_changed события
- добавлены market_volatility_changed события
- market-analysis интегрирован в auto runtime
- устранён spam logging market-analysis циклов
- реализовано logging только при реальной смене состояния
- добавлены human-readable market messages
- убраны raw enum/state значения из UI-журнала
- журнал переведён на explainable market-analysis стиль
- добавлена фиксация отсутствия выраженного направления рынка
- подготовлена база для market analytics layer
- подготовлена база для future AI market commentary
- журнал подготовлен к market filters/search layer

#### 07.4.4.1.3 ✅ Journal Runtime Cleanup & Event Titles Layer
- унифицирована модель журнала: event_type / заголовок / сообщение
- заголовки событий сокращены до понятных сущностей
- подготовлен общий EVENT_TITLES mapping для journal UI и export layer
- убрано дублирование market_state_changed и market_trend_changed
- market_trend_changed исключён из обычного журналирования
- market trend сохранён в payload для аналитики и debug
- market-analysis сообщения приведены к единому формату
- Auto UI wording уточнён: падение заменено на нисходящий тренд
- сообщения настроек автоторговли приведены к короткому стилю
- символы активов очищены в journal messages: BTC вместо BTC/USD_LEVERAGE
- risk-control logging стал показывать SL / TP / ML в одном сообщении
- notification logging унифицирован через notification_sent / notification_error
- из market runtime сообщений убран лишний [AUTO]
- CSV / XLSX export очищен от эмодзи
- журнал подготовлен к централизованному event_titles.py и future filters/search layer

#### 07.4.4.1.4 ✅ Entry Decision Diagnostics Layer
- добавлен диагностический слой причин не входа в позицию
- AutoTradeState расширен entry_block_reason и entry_block_message
- TrendStrategy начала передавать причины HOLD в payload
- добавлены entry_block_reason к market filter / live data / weak impulse сценариям
- AutoTradeService синхронизирует entry diagnostics в runtime state
- добавлено событие entry_blocked для журнала
- журнал пишет причины не входа только при изменении причины
- добавлена защита от spam logging одинаковых HOLD-причин
- Auto UI показывает строку Вход в позицию · причина
- strategy diagnostics отделены от execution diagnostics
- execution UI приведён к human-readable стилю
- добавлен EVENT_TITLES mapping для entry_blocked
- подготовлена база для анализа частоты причин отказа от входа
- подготовлена база для adaptive thresholds и настройки чувствительности стратегии

#### 07.4.4.1.5 ✅ Runtime Window Cleanup & Symbol Lifecycle Isolation
- внедрён lifecycle cleanup runtime-окон стратегий
- BaseStrategy расширен методом reset_runtime()
- TrendStrategy и ScalpStrategy получили runtime cleanup API
- StrategyRegistry получил reset_runtime() и reset_all_runtime()
- устранено смешивание _price_window между разными активами
- устранено смешивание runtime между TREND и SCALP
- runtime окна теперь изолированы по symbol lifecycle
- runtime окна теперь изолированы по strategy lifecycle
- при смене symbol очищается runtime старого и нового актива
- при смене strategy очищается runtime обеих стратегий
- устранены ложные BUY/SELL после переключения актива
- устранены ложные сигналы после смены стратегии
- AutoTradeService теперь полностью сбрасывает market diagnostics при reset
- очищаются market_state / market_trend / market_volatility
- очищаются market_analysis_interval / market_analysis_reason
- очищаются entry_block_reason / entry_block_message
- устранено визуальное залипание TREND_UP / TREND_DOWN в UI
- после смены актива UI возвращается в состояние “⏳ Идёт анализ”
- удалено дублирующее journal событие market_symbol_changed
- journal приведён к single-result event модели
- runtime lifecycle отделён от user-facing settings events
- подготовлена база для multi-symbol runtime engine
- подготовлена база для signal aging/reset system
- подготовлена база для adaptive runtime memory management

#### 07.4.4.1.6 ✅ Signal Aging & Runtime Expiration
- добавлены поля signal_updated_at и market_analysis_updated_at в AutoTradeState
- добавлены runtime_expired_reason и runtime_expired_message
- внедрён TTL для signal runtime
- внедрён TTL для market analysis runtime
- добавлен runtime expiration handler в AutoTradeService
- добавлено событие runtime_expired для журнала
- добавлена защита от spam logging одинаковых runtime expiration событий
- signal tracking теперь обновляет время последнего сигнала
- market analysis sync теперь обновляет время последней аналитики
- stale signal runtime сбрасывается при превышении TTL
- stale market diagnostics очищаются при превышении TTL
- TrendStrategy получила TTL для live price window
- ScalpStrategy получила отдельный TTL для live price window
- reset_runtime теперь очищает price window и timestamp window
- предотвращено использование старых цен после runtime-паузы
- HOLD timer сохранён как индикатор живого runtime цикла
- Telegram UI переведён на компактные market state labels
- entry diagnostics в UI разделены на Ожидание и Вход
- добавлен compact mapping для длинных entry_block_message
- подтверждена корректная работа runtime lifecycle на флэт-рынке
- выявлен uncovered HOLD diagnostic scenario для следующего этапа
- подготовлена база для advanced market diagnostics layer
- подготовлена база для adaptive thresholds
- подготовлена база для signal freshness-aware execution

#### 07.4.4.1.7 ✅ Live Market Runtime & Advanced Trend Diagnostics
- внедрён полноценный live market runtime pipeline
- добавлен websocket-based realtime market runtime
- добавлен REST fallback для market runtime
- внедрён runtime-aware MarketPriceCache
- cache переведён на isolation по runtime_key
- добавлен market snapshot layer в ExchangeService
- добавлены get_market_snapshot и get_execution_snapshot
- добавлен get_fresh_market_snapshot
- добавлен refresh_market_snapshot_cache
- внедрена модель ExecutionPriceSnapshot
- execution pipeline получил поддержку bid/ask
- execution pipeline получил freshness tracking
- execution pipeline получил source tracking
- MarketDataRunner теперь обновляет runtime cache
- websocket runtime теперь автоматически reconnect'ится
- websocket runtime теперь безопасно fallback'ится в REST
- TrendStrategy переведена на market snapshot analysis
- TrendStrategy теперь использует bid/ask mid-price
- добавлен _analysis_price для execution-aware анализа
- добавлен direction_ratio analysis layer
- добавлен live impulse confirmation layer
- TREND теперь требует подтверждение live momentum
- live impulse теперь анализируется через runtime price windows
- улучшена фильтрация noise movement
- снижено количество ложных BUY/SELL импульсов
- TrendStrategy получила расширенные HOLD diagnostics
- HOLD ветки теперь передают entry_block_reason
- HOLD ветки теперь передают entry_block_message
- Telegram UI теперь отображает причины HOLD
- Telegram UI теперь отображает compact market states
- HOLD runtime теперь визуально подтверждает живой цикл
- HOLD timer сохранён как runtime heartbeat indicator
- AutoTradeRunner получил protected execution loop
- исключения стратегии больше не убивают runtime
- исключения UI refresh больше не убивают runtime
- исключения event handler больше не убивают runtime
- runtime loop теперь логирует auto_run_cycle_error
- runtime loop теперь логирует auto_refresh_loop_error
- защищён asyncio lifecycle автоторговли
- исправлен critical runtime bug с TrendStrategy.analyze
- восстановлен realtime refresh автоторговли
- исправлен freeze Telegram UI
- исправлено зависание market state на “Идёт анализ”
- исправлено зависание HOLD timer
- исправлена race condition между screen register и runner.start
- стабилизирована смена инструмента во время runtime
- подтверждена корректная работа websocket runtime
- подтверждена корректная работа REST fallback
- подготовлена база для spread-aware execution
- подготовлена база для stale snapshot protection
- подготовлена база для adaptive execution engine
- подготовлена база для execution quality metrics
- подготовлена база для advanced market diagnostics
- подготовлена база для multi-timeframe analysis

---

### 07.4.5
⏳ Scalping Strategy  

### 07.3.6 — Signal Engine
⏳ реальные сигналы  

### 07.3.7 — Execution Engine
⏳ исполнение ордеров  

### 07.3.8 — Analytics
⏳ статистика торговли  

🟡 Статус: в работе

---

# Stage 08 — Analytics / Reports
⏳ отчёты  
⏳ pnl  
⏳ winrate  
⏳ drawdown  

⚪ Статус: не начат

---

# Stage 09 — Production Readiness
⏳ deployment  
⏳ monitoring  
⏳ alerts  
⏳ backups  

⚪ Статус: не начат

---

## Текущий статус проекта

👉 Завершён: 07.4.3.1  
👉 Следующий шаг: 07.4.3.2 — Engine Decoupling + Price Polling