build 039: complete Quotes Feed migration foundation
This commit is contained in:
527
docs/stages/stage-08_2-architecture_build_log.md
Normal file
527
docs/stages/stage-08_2-architecture_build_log.md
Normal file
@@ -0,0 +1,527 @@
|
||||
принимаю твое предложение
|
||||
Переделай уже имеющийся stage-08_2-architecture_build_log.md и отформатируй его в markdown, и далее дополнения присылай так же в формате Markdown
|
||||
|
||||
Stage-08.2 — Architecture Build Log
|
||||
|
||||
Документ фиксирует процесс построения архитектуры Market Intelligence.
|
||||
|
||||
В отличие от Git, данный журнал хранит не историю изменения строк кода, а историю архитектурных решений.
|
||||
|
||||
Каждый файл проходит одинаковый жизненный цикл:
|
||||
|
||||
Design
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Compile Check
|
||||
↓
|
||||
Architecture Review
|
||||
↓
|
||||
Accepted
|
||||
|
||||
Файл считается завершённым только после успешного прохождения всех этапов.
|
||||
|
||||
⸻
|
||||
|
||||
Build №001
|
||||
|
||||
Файл
|
||||
|
||||
app/src/trading/market_intelligence/common/enums.py
|
||||
|
||||
Назначение
|
||||
|
||||
Создание единого набора перечислений (Enum), используемых всеми аналитическими движками платформы.
|
||||
|
||||
Данный файл является фундаментом всей подсистемы Market Intelligence и определяет общий язык взаимодействия между Engine.
|
||||
|
||||
Реализовано
|
||||
|
||||
Добавлены перечисления:
|
||||
|
||||
* MarketDirection
|
||||
* MarketBias
|
||||
* MarketPhase
|
||||
* MarketRegime
|
||||
* MarketQuality
|
||||
* EngineStatus
|
||||
* ConfidenceLevel
|
||||
* SignalFreshness
|
||||
* RiskLevel
|
||||
* TimeframeRole
|
||||
* CheckStatus
|
||||
* ProcessingStage
|
||||
|
||||
Архитектурные решения
|
||||
|
||||
Приняты следующие решения:
|
||||
|
||||
* перечисления не содержат торговой логики;
|
||||
* перечисления не принимают торговых решений;
|
||||
* используются только как описание состояния рынка;
|
||||
* комментарии ориентированы на разработчика, а не на трейдера;
|
||||
* проверки движков описываются этапами обработки (ProcessingStage), а не именами файлов;
|
||||
* добавлен ConfidenceLevel как человекочитаемая интерпретация числовой уверенности;
|
||||
* добавлен статус SKIPPED для корректного отображения намеренно пропущенных этапов проверки.
|
||||
|
||||
Compile Check
|
||||
|
||||
PASSED
|
||||
|
||||
Architecture Review
|
||||
|
||||
PASSED
|
||||
|
||||
Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
Рекомендации
|
||||
|
||||
В дальнейшем допускается расширение ProcessingStage, если архитектура платформы потребует новых этапов обработки. До появления реальной необходимости перечисление не расширяется.
|
||||
|
||||
Статус
|
||||
|
||||
ACCEPTED
|
||||
|
||||
⸻
|
||||
|
||||
Build №002
|
||||
|
||||
Файл
|
||||
|
||||
app/src/trading/market_intelligence/common/types.py
|
||||
|
||||
Назначение
|
||||
|
||||
Создание единого набора базовых типовых алиасов, используемых всеми аналитическими движками.
|
||||
|
||||
Файл определяет общий типовой контракт Market Intelligence.
|
||||
|
||||
Реализовано
|
||||
|
||||
Добавлены типы:
|
||||
|
||||
* SymbolName
|
||||
* TimeframeName
|
||||
* EngineName
|
||||
* EngineVersion
|
||||
* ReasonCode
|
||||
* ReasonText
|
||||
* ScoreValue
|
||||
* ConfidenceValue
|
||||
* ProbabilityValue
|
||||
* WeightValue
|
||||
* AgeSeconds
|
||||
* DurationMs
|
||||
* MetricsDict
|
||||
* PayloadDict
|
||||
* ContextDict
|
||||
* MarketData
|
||||
* DependencyResults
|
||||
* DiagnosticMessages
|
||||
* DiagnosticValue
|
||||
|
||||
Повторно используются существующие типы проекта:
|
||||
|
||||
* JsonDict
|
||||
* JsonList
|
||||
|
||||
из src.core.types.
|
||||
|
||||
Архитектурные решения
|
||||
|
||||
Приняты следующие решения:
|
||||
|
||||
* используется единый источник истины (core.types);
|
||||
* отсутствует дублирование базовых типов проекта;
|
||||
* отсутствуют зависимости от Runtime, Telegram, Execution, Journal и Exchange;
|
||||
* файл не содержит торговой логики;
|
||||
* комментарии объясняют назначение типов, а не синтаксис Python.
|
||||
|
||||
Compile Check
|
||||
|
||||
PASSED
|
||||
|
||||
Architecture Review
|
||||
|
||||
PASSED
|
||||
|
||||
Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
Рекомендации
|
||||
|
||||
Тип DependencyResults временно использует Any. После появления общего EngineResult в common/models.py рекомендуется заменить значение словаря на специализированный тип результата движка.
|
||||
|
||||
В перспективе допускается переход от универсальных словарей (PayloadDict, MetricsDict, ContextDict) к специализированным TypedDict, если это потребуется для усиления типизации и улучшения поддержки IDE.
|
||||
|
||||
Статус
|
||||
|
||||
ACCEPTED
|
||||
|
||||
⸻
|
||||
|
||||
Общий прогресс Stage-08.2
|
||||
|
||||
Common
|
||||
|
||||
Файл Статус
|
||||
enums.py ✅ Accepted
|
||||
types.py ✅ Accepted
|
||||
constants.py ✅ Accepted
|
||||
reasons.py ⏳ Planned
|
||||
scores.py ⏳ Planned
|
||||
models.py ⏳ Planned
|
||||
validation.py ⏳ Planned
|
||||
checks.py ⏳ Planned
|
||||
payloads.py ⏳ Planned
|
||||
snapshots.py ⏳ Planned
|
||||
events.py ⏳ Planned
|
||||
timeframes.py ⏳ Planned
|
||||
|
||||
⸻
|
||||
|
||||
Архитектурные принципы Stage-08
|
||||
|
||||
На текущем этапе подтверждены следующие принципы разработки:
|
||||
|
||||
* архитектура проектируется раньше реализации;
|
||||
* каждый файл проходит обязательную компиляцию;
|
||||
* каждый файл проходит обязательный Architecture Review;
|
||||
* обязательные и рекомендательные замечания фиксируются отдельно;
|
||||
* новый код не должен содержать преждевременных сущностей “на будущее”;
|
||||
* комментарии должны быть понятны разработчику без знаний трейдинга;
|
||||
* все изменения должны соответствовать Engine Runtime Contract;
|
||||
* развитие платформы ведётся небольшими логически завершёнными шагами с обязательной проверкой качества каждого шага.
|
||||
|
||||
⸻
|
||||
|
||||
Эволюция процесса разработки
|
||||
|
||||
По мере развития Stage-08 процесс разработки был дополнен обязательными архитектурными проверками.
|
||||
|
||||
Начиная с Build №004 каждый новый файл проходит полный цикл проверки качества.
|
||||
|
||||
Полный цикл разработки
|
||||
|
||||
Architecture Design
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Compile Check
|
||||
↓
|
||||
Architecture Review
|
||||
↓
|
||||
Domain Review
|
||||
↓
|
||||
Accepted
|
||||
|
||||
⸻
|
||||
|
||||
Compile Check
|
||||
|
||||
Проверяет техническую корректность файла.
|
||||
|
||||
Цель проверки:
|
||||
|
||||
* успешная компиляция;
|
||||
* отсутствие синтаксических ошибок;
|
||||
* корректность импортов;
|
||||
* возможность безопасного включения файла в проект.
|
||||
|
||||
Без успешного Compile Check дальнейшие проверки не выполняются.
|
||||
|
||||
⸻
|
||||
|
||||
Architecture Review
|
||||
|
||||
Проверяет соответствие архитектуре Dzentra.
|
||||
|
||||
Во время проверки анализируется:
|
||||
|
||||
* соблюдение зон ответственности;
|
||||
* отсутствие нарушения слоёв архитектуры;
|
||||
* отсутствие циклических зависимостей;
|
||||
* возможность масштабирования;
|
||||
* соответствие Engine Runtime Contract;
|
||||
* соответствие принятому стилю проекта.
|
||||
|
||||
Architecture Review оценивает качество архитектуры независимо от предметной области.
|
||||
|
||||
⸻
|
||||
|
||||
Domain Review
|
||||
|
||||
Проверяет соответствие предметной области Market Intelligence.
|
||||
|
||||
Во время проверки анализируется:
|
||||
|
||||
* правильность используемой терминологии;
|
||||
* соответствие названий реальному поведению рынка;
|
||||
* отсутствие смешивания анализа рынка и торговых решений;
|
||||
* отсутствие логики открытия, закрытия или сопровождения сделок внутри аналитических компонентов;
|
||||
* понятность комментариев разработчику без специальных знаний трейдинга;
|
||||
* корректность описания рыночных состояний и процессов.
|
||||
|
||||
Domain Review гарантирует, что Market Intelligence остаётся системой анализа поведения рынка, а не системой принятия торговых решений.
|
||||
|
||||
⸻
|
||||
|
||||
Правила разработки Stage-08
|
||||
|
||||
При реализации Stage-08 приняты следующие обязательные правила.
|
||||
|
||||
1. Архитектура проектируется раньше кода
|
||||
|
||||
Каждый новый компонент сначала проектируется, после чего начинается его реализация.
|
||||
|
||||
⸻
|
||||
|
||||
2. Не использовать предположения о существующем коде
|
||||
|
||||
Если для реализации нового файла требуется существующая часть проекта, соответствующий файл предварительно запрашивается и используется как источник истины.
|
||||
|
||||
Запрещается:
|
||||
|
||||
* дублировать существующие сущности;
|
||||
* самостоятельно создавать альтернативные реализации уже существующих моделей;
|
||||
* делать предположения о текущем состоянии проекта.
|
||||
|
||||
⸻
|
||||
|
||||
3. Один источник истины
|
||||
|
||||
Общие сущности повторно используются из существующих модулей проекта.
|
||||
|
||||
Новые реализации создаются только при отсутствии соответствующей функциональности.
|
||||
|
||||
⸻
|
||||
|
||||
4. Каждый файл должен быть логически завершён
|
||||
|
||||
Файл считается завершённым только после успешного прохождения полного цикла проверки качества.
|
||||
|
||||
Частично реализованные решения не считаются завершёнными независимо от объёма написанного кода.
|
||||
|
||||
⸻
|
||||
|
||||
5. Комментарии ориентированы на разработчика
|
||||
|
||||
Комментарии должны объяснять назначение компонента простым техническим языком.
|
||||
|
||||
Предпочтительно объяснять:
|
||||
|
||||
* зачем существует объект;
|
||||
* какую задачу он решает;
|
||||
* какие ограничения существуют.
|
||||
|
||||
Следует избегать объяснения синтаксиса Python.
|
||||
|
||||
⸻
|
||||
|
||||
6. Аналитика не принимает торговых решений
|
||||
|
||||
Компоненты Market Intelligence описывают состояние рынка.
|
||||
|
||||
Они не должны:
|
||||
|
||||
* открывать сделки;
|
||||
* закрывать сделки;
|
||||
* изменять позиции;
|
||||
* рассчитывать объёмы ордеров;
|
||||
* выполнять действия биржи.
|
||||
|
||||
Принятие торговых решений выполняется только верхними уровнями архитектуры платформы.
|
||||
|
||||
⸻
|
||||
|
||||
История развития процесса
|
||||
|
||||
Build Изменение процесса
|
||||
Build №001 Введён обязательный Compile Check
|
||||
Build №001 Введён обязательный Architecture Review
|
||||
Build №003 Введён Architecture Build Log
|
||||
Build №004 Введён обязательный Domain Review
|
||||
Build №004 Запрещено предполагать существующий код — все необходимые файлы предварительно запрашиваются
|
||||
|
||||
⸻
|
||||
|
||||
Build №003 — Post Review Notes
|
||||
|
||||
После завершения Build №003 были приняты дополнительные архитектурные решения.
|
||||
|
||||
Решение №001
|
||||
|
||||
Архитектурные константы должны содержать только ограничения платформы.
|
||||
|
||||
В common/constants.py запрещается размещать:
|
||||
|
||||
* параметры технических индикаторов;
|
||||
* параметры торговых стратегий;
|
||||
* настройки открытия и закрытия сделок;
|
||||
* параметры биржи;
|
||||
* параметры управления позицией.
|
||||
|
||||
Подобные константы должны размещаться только внутри соответствующих Engine.
|
||||
|
||||
⸻
|
||||
|
||||
Решение №002
|
||||
|
||||
Константы должны быть сгруппированы по смысловым разделам.
|
||||
|
||||
При дальнейшем развитии файла рекомендуется придерживаться следующего порядка:
|
||||
|
||||
Score
|
||||
Confidence
|
||||
Probability
|
||||
Runtime
|
||||
Diagnostics
|
||||
Architecture
|
||||
Timeframes
|
||||
Safety
|
||||
|
||||
Это обеспечивает единый стиль оформления и упрощает сопровождение файла по мере роста платформы.
|
||||
|
||||
⸻
|
||||
|
||||
Решение №003
|
||||
|
||||
Временные интервалы являются частью конфигурации платформы, а не жёстким ограничением архитектуры.
|
||||
|
||||
DEFAULT_TIMEFRAMES описывает базовую конфигурацию первого этапа разработки Market Intelligence.
|
||||
|
||||
В дальнейшем архитектура должна позволять использовать дополнительные интервалы времени без изменения логики Engine.
|
||||
|
||||
⸻
|
||||
|
||||
Решение №004
|
||||
|
||||
Возраст результата анализа и возраст торгового сигнала являются разными понятиями.
|
||||
|
||||
Используются две независимые архитектурные константы:
|
||||
|
||||
* DEFAULT_STALE_AFTER_SECONDS — определяет момент, после которого аналитический результат считается устаревшим.
|
||||
* DEFAULT_SIGNAL_TTL_SECONDS — определяет момент, после которого влияние аналитического сигнала начинает постепенно уменьшаться.
|
||||
|
||||
Совпадение их значений допускается, однако их назначение принципиально различается.
|
||||
|
||||
⸻
|
||||
|
||||
Решение №005
|
||||
|
||||
Константы не должны зависеть от конкретного Engine.
|
||||
|
||||
Все значения, размещаемые в common/constants.py, должны быть одинаково применимы для любого аналитического движка платформы.
|
||||
|
||||
При появлении константы, относящейся только к одному Engine, она переносится в каталог соответствующего Engine.
|
||||
|
||||
⸻
|
||||
|
||||
Итог Build №003
|
||||
|
||||
Build №003 полностью соответствует принятой архитектуре Stage-08 и остаётся базовым источником архитектурных ограничений Market Intelligence.
|
||||
|
||||
⸻
|
||||
|
||||
Build №004
|
||||
|
||||
Файл
|
||||
|
||||
app/src/trading/market_intelligence/common/reasons.py
|
||||
|
||||
Назначение
|
||||
|
||||
Создание единого реестра машинных кодов причин (ReasonCode), используемых всеми аналитическими движками Market Intelligence.
|
||||
|
||||
Файл определяет стандартный словарь причин, который применяется при диагностике, построении результатов, публикации событий и журналировании.
|
||||
|
||||
Реализовано
|
||||
|
||||
Добавлен единый класс ReasonCode, включающий причины для следующих областей:
|
||||
|
||||
* Common
|
||||
* Data
|
||||
* Engine Runtime
|
||||
* Validation
|
||||
* Market State
|
||||
* Structure
|
||||
* Trend
|
||||
* Momentum
|
||||
* Volatility
|
||||
* Wave
|
||||
* Cycle
|
||||
* Liquidity
|
||||
* Regime
|
||||
* Confidence
|
||||
* Signal Aging
|
||||
* Timeframe
|
||||
|
||||
Архитектурные решения
|
||||
|
||||
Приняты следующие решения:
|
||||
|
||||
* движки публикуют только стандартизированные коды причин;
|
||||
* движки не формируют человекочитаемый текст;
|
||||
* причины полностью отделены от пользовательского интерфейса;
|
||||
* причины не содержат торговых действий;
|
||||
* единый словарь причин используется всеми Engine платформы;
|
||||
* причины описывают только состояние рынка и состояние работы движка.
|
||||
|
||||
Compile Check
|
||||
|
||||
PASSED
|
||||
|
||||
Architecture Review
|
||||
|
||||
PASSED
|
||||
|
||||
Domain Review
|
||||
|
||||
PASSED
|
||||
|
||||
Обязательные замечания
|
||||
|
||||
Нет.
|
||||
|
||||
Рекомендации
|
||||
|
||||
После завершения проектирования моделей рекомендуется реализовать отдельный слой формирования человекочитаемых объяснений (common/reason_texts.py или аналогичный модуль), который будет преобразовывать ReasonCode в диагностические сообщения для журнала, интерфейса и отчётов.
|
||||
|
||||
Статус
|
||||
|
||||
ACCEPTED
|
||||
|
||||
⸻
|
||||
|
||||
Общий прогресс Stage-08.2
|
||||
|
||||
Common
|
||||
|
||||
Файл Статус
|
||||
enums.py ✅ Accepted
|
||||
types.py ✅ Accepted
|
||||
constants.py ✅ Accepted
|
||||
reasons.py ✅ Accepted
|
||||
scores.py ⏳ Planned
|
||||
models.py ⏳ Planned
|
||||
payloads.py ⏳ Planned
|
||||
snapshots.py ⏳ Planned
|
||||
events.py ⏳ Planned
|
||||
timeframes.py ⏳ Planned
|
||||
|
||||
⸻
|
||||
|
||||
История развития процесса
|
||||
|
||||
Начиная с Build №004 каждый логически завершённый файл сопровождается обязательным обновлением Architecture Build Log.
|
||||
|
||||
Это гарантирует синхронное развитие:
|
||||
|
||||
* архитектуры;
|
||||
* исходного кода;
|
||||
* инженерной документации.
|
||||
|
||||
Журнал является частью процесса разработки и обновляется одновременно с завершением каждого Build.
|
||||
Reference in New Issue
Block a user