# Auto refactoring roadmap

Цель: безопасный поэтапный аудит и рефакторинг `app/src/trading/auto`.

Принципы:

- сначала аудит;
- без изменения торговой логики;
- без изменения AutoTradeState;
- без изменения ExecutionEngine;
- без изменения payload;
- без изменения EventBus / JournalService;
- каждый шаг проверяется перезапуском бота.

## Файлы

| Файл | Статус | Комментарий |
|---|---|---|
| __init__.py | Not audited |  |
| service.py | Not audited |  |
| autonomous_management.py | Not audited |  |
| execution_semantic.py | Not audited |  |
| market_runtime.py | Not audited |  |
| position_health.py | Not audited |  |
| execution_quality.py | Not audited |  |
| position_semantics.py | Not audited |  |
| auto_lifecycle.py | Not audited |  |
| runner.py | Not audited |  |
| signal_runtime.py | Not audited |  |
| state.py | Not audited |  |

## Порядок аудита

1. service.py
2. autonomous_management.py
3. execution_semantic.py
4. market_runtime.py
5. position_health.py
6. execution_quality.py
7. position_semantics.py
8. auto_lifecycle.py
9. runner.py
10. signal_runtime.py
11. state.py

## Правила аудита

Для каждого файла фиксируем:

- назначение;
- размер и сложность;
- зависимости;
- что хорошо;
- что настораживает;
- безопасные улучшения;
- что нельзя менять;
- рекомендуемый следующий шаг.

## service.py

Статус: Completed (без изменений)

Назначение:
- Фасад AutoTradeService.
- Хранит единый runtime AutoTradeState.
- Хранит class-level настройки auto loop, signal confirmation, TTL, execution quality и spread thresholds.

Размер:
- Небольшой/средний.

Связность:
- Зависит от AutoLifecycleMixin и AutoTradeState.
- Не содержит прямой торговой логики.

Что хорошо:
- Нет JournalService/EventBus/payload.
- Нет execution-алгоритмов.
- Настройки читаются централизованно.

Что настораживает:
- Много class-level state.
- Spread thresholds находятся прямо в service.py.

Безопасные улучшения:
- Сейчас не требуются.

Что нельзя менять:
- Значения thresholds.
- Class-level state.
- Названия runtime-полей.
- Наследование от AutoLifecycleMixin.

Итог:
Файл выполняет роль конфигурационного фасада. Рефакторинг на текущем этапе не нужен.

## autonomous_management.py

Статус: Completed after minor cleanup

Назначение:
- Синхронизация autonomous trade management state.
- Определяет autonomous action: HOLD / WATCH / PROTECT / REDUCE / EXIT.
- Обновляет autonomous required-флаги.

Размер:
- Небольшой.

Связность:
- Зависит от AutoTradeState и execution.constants.
- Не вызывает ExecutionEngine напрямую.

Что хорошо:
- Один понятный метод.
- Нет JournalService/EventBus/payload.
- Нет прямого закрытия позиции.
- Используются константы.

Безопасные улучшения:
- Только косметика форматирования.

Что нельзя менять:
- Порядок выбора autonomous action.
- Thresholds confidence.
- Логику aggressive exit escalation.
- Сброс autonomous-state при отсутствии позиции.

Итог:
Файл чистый. Логических правок не требуется.

## execution_semantic.py

Статус: Completed (без изменений)

Назначение:
- Синхронизация semantic-статуса execution слоя для UI.
- Формирует execution_semantic_status/message/reason.
- Преобразует технические причины блокировки в человекочитаемые UI-сообщения.

Размер:
- Небольшой.

Связность:
- Зависит от AutoTradeState.
- Использует ExchangeStatusCode для совместимости с exchange status layer.

Что хорошо:
- Нет JournalService/EventBus/payload.
- Нет торговой логики.
- Нет прямых вызовов ExecutionEngine.
- Логика UI-сообщений отделена от execution layer.

Что настораживает:
- Строковые статусы `"BLOCKED"`, `"READY"`, `"CONFIRMING"`, `"NONE"` пока используются напрямую.
- Но сейчас это не трогаем, чтобы не менять контракт state/UI.

Безопасные улучшения:
- Сейчас не требуются.

Что нельзя менять:
- Приоритеты semantic status.
- Тексты UI-сообщений.
- Совместимость с ExchangeStatusCode.
- Значения execution_semantic_status.

Итог:
Файл выполняет UI-semantic роль и не требует refactoring на текущем этапе.

## market_runtime.py

Статус: Audited / candidate for safe payload extraction

Назначение:
- Синхронизация market analysis payload в AutoTradeState.
- Логирование market state / volatility изменений.
- Логирование entry-block событий.

Размер:
- Средний.

Связность:
- Зависит от AutoTradeState, JournalService, JsonDict.
- Не вызывает ExecutionEngine напрямую.

Что хорошо:
- Dedupe market-событий по symbol/strategy.
- Entry-block logging имеет TTL.
- Нет торговых действий.

Что настораживает:
- Большой inline payload внутри `_log_entry_block_if_changed()`.
- `_sync_market_analysis_state()` много полей переносит из payload в state, но это существующий mapping.

Безопасные улучшения:
- Вынести entry-block payload в `_build_entry_block_payload()`.

Что нельзя менять:
- Mapping payload → AutoTradeState.
- Dedupe key.
- Entry-block TTL.
- Journal event_type/action.
- Содержимое payload.

Итог:
Файл рабочий. Первый безопасный шаг — вынести payload builder без изменения поведения.

### market_runtime.py

Выполнено:
- Вынесен `_build_entry_block_payload()`.
- Логика `_log_entry_block_if_changed()` стала отвечать только за dedupe и запись в Journal.
- Содержимое payload не изменено.
- Поведение полностью сохранено.

Статус: Completed

Выполнено:
- Вынесен `_build_entry_block_payload()`.
- Вынесен `_build_market_state_payload()`.
- Методы логирования теперь отвечают только за:
  - dedupe;
  - принятие решения;
  - запись в Journal.
- Формирование payload полностью изолировано.
- Поведение не изменилось.

## position_health.py

Статус: Completed (без изменений)

Назначение:
- Runtime health/risk оценка открытой позиции.
- Формирует pressure, health score/status/reason, risk level/reason, trend alignment, adverse momentum и exit pressure.

Размер:
- Средний/большой.

Связность:
- Зависит от AutoTradeState, safe_float и execution.constants.
- Использует get_position_health_thresholds().

Что хорошо:
- PnL и hold time не рассчитываются здесь.
- Runtime metrics приходят из execution/position_runtime.py.
- Нет JournalService/EventBus/payload.
- Методы разделены по смыслу.
- Thresholds вынесены в constants.

Что настораживает:
- Чувствительный файл: влияет на autonomous management, runtime actions, protection и exit decision.
- Много бизнес-условий.
- Много строковых runtime states.

Безопасные улучшения:
- Сейчас не требуются.

Что нельзя менять:
- Health score формулу.
- Risk level порядок условий.
- Trend alignment logic.
- Adverse momentum logic.
- Exit pressure logic.
- Threshold constants.

Итог:
Файл архитектурно понятный. На текущем safe stage оставляем без изменений.

## execution_quality.py

Статус: Audited / candidate for safe payload extraction

Назначение:
- Оценка качества исполнения.
- Синхронизация exchange availability.
- Проверка свежести market snapshot.
- Проверка spread.
- Синхронизация execution pricing fields.
- Логирование execution quality изменений.
- Расчёт execution quality confidence score.

Размер:
- Большой.

Связность:
- Зависит от AutoTradeState, ExchangeService, ExchangeRuntimeStatus, JournalService.
- Не вызывает ExecutionEngine напрямую.

Что хорошо:
- Exchange availability вынесена отдельно.
- Spread quality вынесен отдельно.
- Execution pricing sync вынесен отдельно.
- Confidence score вынесен отдельно.
- Нет торговых действий.

Что настораживает:
- Inline payload в `_log_exchange_availability_if_changed()`.
- Inline payload в `_log_execution_quality_if_changed()`.
- `_sync_execution_quality_state()` большой и чувствительный.

Безопасные улучшения:
- Вынести `_build_exchange_availability_payload()`.
- Вынести `_build_execution_quality_payload()`.

Что нельзя менять:
- Exchange status mapping.
- Spread thresholds.
- Snapshot refresh logic.
- Fallback price behavior.
- Execution quality transitions.
- Deduplication key.
- Journal event_type/action.
- Confidence score mapping.

Итог:
Файл рабочий. Первый безопасный этап — вынести payload builders без изменения поведения.

### execution_quality.py

Выполнено:
- Вынесен `_build_exchange_availability_payload()`.
- Вынесен `_build_execution_quality_payload()`.
- Логика exchange availability не менялась.
- Логика spread/snapshot quality не менялась.
- Journal payload не изменён.
- Поведение полностью сохранено.

Статус: Completed (safe refactoring stage 1)

## position_semantics.py

Статус: Completed after minor cleanup

Назначение:
- Semantic/intelligence состояние открытой позиции.
- Формирует lifecycle stage, hold quality, decay state, exit confidence, exit signal, recommended action.
- Считает advanced analytics: MFE, MAE, giveback, fatigue, conviction, reversal risk, stall state.

Размер:
- Большой.

Связность:
- Зависит от AutoTradeState, safe_float и execution.constants.
- Не вызывает ExecutionEngine напрямую.

Что хорошо:
- Нет JournalService/EventBus/payload.
- Нет прямых торговых действий.
- Thresholds вынесены в constants.
- Методы разделены по смыслу.

Что настораживает:
- Очень чувствительный файл: влияет на autonomous management, runtime actions, protection и exit decision.
- Много бизнес-условий.
- Много строковых semantic states.
- `_sync_position_semantics_state()` управляет большим количеством полей AutoTradeState.

Безопасные улучшения:
- Только косметика форматирования.

Что нельзя менять:
- Порядок расчёта lifecycle/advanced analytics/stall/exit confidence.
- Формулы exit confidence.
- Логику damping.
- MFE/MAE/giveback/fatigue/conviction/reversal/stall.
- Threshold constants.
- Значения semantic states.

Итог:
Файл архитектурно понятный, но чувствительный. На текущем safe stage логических правок не требуется.

## auto_lifecycle.py

Статус: Audited / candidate for safe payload extraction

Назначение:
- Lifecycle автоторговли: start / observe / stop.
- Управление background loop.
- Основной run_cycle pipeline.
- Reset signal/runtime tracking.

Размер:
- Большой.

Связность:
- Собирает auto mixins.
- Использует ExecutionEngine, StrategyRegistry, EventBus, JournalService.

Что хорошо:
- run_cycle имеет понятный pipeline.
- Execution делегирован ExecutionEngine.
- Market, signal, health, semantics, autonomous management вынесены в mixins.

Что настораживает:
- Большой `_reset_signal_tracking()`.
- Inline payload в `_log_auto_status_changed()`.
- Дубли reset-полей в start/observe/stop.

Безопасные улучшения:
- Вынести `_build_auto_status_changed_payload()`.

Что нельзя менять:
- Порядок run_cycle.
- start/observe/stop поведение.
- Reset signal tracking.
- EventBus события.
- Journal payload.

Итог:
Файл рабочий. Первый безопасный шаг — вынести payload builder без изменения поведения.

## runner.py

Статус: Audited / candidate for safe payload extraction

Назначение:
- Background runner автоторговли.
- Обработка EventBus событий.
- Публикация RuntimeEvent уведомлений.
- Обновление Telegram auto screen.

Безопасные улучшения:
- Вынести payload builders для notification/journal событий.

Что нельзя менять:
- Worker loop.
- EventBus version handling.
- Dedupe keys.
- Telegram refresh logic.
- RuntimeEvent payload.

Выполнено:
- Вынесен `_build_position_aligned_signal_suppressed_payload()`.
- Вынесен `_build_runtime_signal_payload()`.
- Вынесен `_build_runtime_execution_payload()`.
- Payload подавленного aligned-сигнала не изменён.
- Логика dedupe/TTL не менялась.
- RuntimeEvent payload не изменялся.
- Dedupe keys не менялись.
- Telegram refresh logic не менялась.

Статус: Completed (safe refactoring stage 1)

## signal_runtime.py

Статус: Audited / candidate for safe payload extraction

Назначение:
- Signal runtime tracking.
- Signal confirmation.
- Decision state.
- Runtime expiration.
- Execution confidence.
- Market confidence.

Безопасные улучшения:
- Вынести payload builders.
- Начать с `_build_runtime_expired_payload()`.

Что нельзя менять:
- Confirmation logic.
- READY/BLOCKED logic.
- Execution confidence formula.
- Market confidence formula.
- Runtime TTL reset logic.
- EventBus events.

Выполнено:
- Вынесен `_build_runtime_expired_payload()`.
- Вынесен `_build_ready_signal_payload()`.
- Вынесен `_build_signal_summary_payload()`.
- Вынесен `_build_execution_confidence_factors()`.

Что не менялось:
- Confirmation logic.
- READY/BLOCKED logic.
- Runtime TTL reset logic.
- Execution confidence formula.
- Market confidence formula.
- EventBus events.
- Journal event_type/action.

Статус: Completed (safe refactoring stage 1)

### state.py

Проверено полностью.

Изменения не требуются.

Причина:
- dataclass не содержит бизнес-логики;
- поля уже сгруппированы по подсистемам;
- выделение вложенных dataclass приведёт к массовым изменениям во всём проекте без архитектурной пользы.

Статус:
Completed (no changes required)