build 039: complete Quotes Feed migration foundation

docs/market_intelligence/builds/build-010-common-snapshots.md

@@ -0,0 +1,193 @@
+# Build 010 — Common Snapshots Layer
+
+**Build ID:** 010
+
+**Компонент:** `common/snapshots.py`
+
+**Статус:** **Accepted**
+
+---
+
+# Цель Build
+
+Реализовать единый слой Snapshot для подсистемы Market Intelligence.
+
+Snapshot представляет собой неизменяемый снимок результата работы аналитического движка в определённый момент времени.
+
+Данный Build создаёт единый формат хранения результатов анализа без привязки к конкретному Engine.
+
+---
+
+# Реализованные компоненты
+
+Создан файл:
+
+```text
+market_intelligence/common/snapshots.py
+```
+
+Реализованы:
+
+- `EngineSnapshot`
+- `build_engine_snapshot()`
+- `engine_snapshot_to_payload()`
+
+---
+
+# Архитектурная задача
+
+До появления данного Build существовал единый Runtime Result (`EngineResult`), но отсутствовал стандартный механизм фиксации его состояния.
+
+После реализации Snapshot Layer каждый результат анализа может быть сохранён в неизменяемом виде.
+
+Snapshot становится стандартным объектом для:
+
+- журналирования;
+- диагностики;
+- формирования Event;
+- хранения истории анализа;
+- последующего сравнения состояний рынка.
+
+---
+
+# Архитектурные решения
+
+В ходе реализации приняты следующие решения.
+
+## Snapshot является неизменяемым
+
+Используется
+
+```python
+@dataclass(frozen=True, slots=True)
+```
+
+После создания Snapshot его содержимое больше не изменяется.
+
+Это гарантирует воспроизводимость результатов анализа.
+
+---
+
+## Snapshot строится только из EngineResult
+
+Snapshot никогда не вычисляет данные самостоятельно.
+
+Он всегда строится через:
+
+```text
+EngineResult
+        ↓
+engine_result_to_payload()
+        ↓
+EngineSnapshot
+```
+
+Таким образом существует единая точка формирования результата анализа.
+
+---
+
+## Snapshot не содержит торговой логики
+
+Snapshot не имеет права хранить:
+
+- команды открытия позиции;
+- команды закрытия позиции;
+- расчёт размера позиции;
+- состояние AutoTrade;
+- состояние Exchange;
+- Runtime Position.
+
+Snapshot фиксирует исключительно аналитический результат.
+
+---
+
+## Payload является частью Snapshot
+
+Snapshot не копирует отдельные поля EngineResult.
+
+Вместо этого используется единый Payload Layer.
+
+Это исключает дублирование логики сериализации.
+
+---
+
+## Независимость от Runtime
+
+Snapshot Layer не зависит от:
+
+- AutoTrade;
+- Exchange;
+- Telegram;
+- Journal;
+- конкретных Engine.
+
+Компонент использует исключительно сущности Common Layer.
+
+---
+
+# Compile Check
+
+Выполнена проверка:
+
+```bash
+python -m compileall \
+src/trading/market_intelligence/common/snapshots.py
+```
+
+Результат:
+
+```text
+Compile successful
+```
+
+---
+
+# Architecture Review
+
+Результат:
+
+**PASSED**
+
+Проверено:
+
+- соблюдение Single Responsibility;
+- неизменяемость Snapshot;
+- отсутствие торговой логики;
+- использование единого Payload Layer;
+- отсутствие нарушения архитектурных границ.
+
+Замечаний не выявлено.
+
+---
+
+# Domain Review
+
+Результат:
+
+**PASSED**
+
+Проверено:
+
+- Snapshot отражает исключительно состояние анализа;
+- отсутствуют торговые решения;
+- структура пригодна для журналирования;
+- структура пригодна для Runtime;
+- структура соответствует Runtime Contract.
+
+Замечаний не выявлено.
+
+---
+
+# Итог Build
+
+Build завершил создание общего Snapshot Layer.
+
+Все аналитические движки платформы получили единый механизм фиксации собственного состояния.
+
+Snapshot становится стандартным архитектурным объектом Market Intelligence.
+
+---
+
+# Build Status
+
+**Accepted**