dzentra_bot/docs/roadmap/master-roadmap.md

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.4.1.8 ✅ Execution Freshness & Market Quality Layer

• добавлен слой execution freshness diagnostics
• добавлен слой market quality diagnostics
• AutoTradeState расширен execution quality полями
• добавлены execution_quality и execution_quality_reason
• добавлены execution_quality_message, spread_percent и snapshot_age_seconds
• AutoTradeService начал синхронизировать execution quality в runtime state
• добавлена проверка наличия market snapshot
• добавлена диагностика SNAPSHOT_ERROR
• добавлена диагностика SNAPSHOT_UNAVAILABLE
• добавлена диагностика AGING_SNAPSHOT
• добавлена диагностика STALE_SNAPSHOT
• stale snapshot теперь блокирует вход
• aging snapshot теперь отображается как warning
• нормальный snapshot age больше не засоряет Telegram UI
• age отображается только для AGING_SNAPSHOT / STALE_SNAPSHOT сценариев
• добавлен расчёт bid/ask spread
• добавлен spread warning layer
• добавлен spread block layer
• высокий spread теперь блокирует вход
• повышенный spread теперь отображается как market warning
• execution diagnostics отделены от strategy entry diagnostics
• UI разделяет Условие, Рынок и Вход
• термин Исполнение заменён на более короткий Вход
• нет market data заменено на нет данных рынка
• Telegram UI получил строку market quality warning
• Telegram UI получил строку execution block по качеству рынка
• wide spread отображается компактно как Рынок · spread ...
• high spread отображается как Вход · высокий spread ...
• устранено дублирование age при нормальном snapshot
• добавлена база для spread-aware execution
• добавлена база для stale snapshot protection
• добавлена база для slippage protection
• добавлена база для execution quality analytics
• добавлена база для instrument quality scoring
• выявлена необходимость Spread Hysteresis Layer
• подготовлен следующий этап 07.4.4.1.8.1 Spread Hysteresis Layer

---

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