build 039: complete Quotes Feed migration foundation

docs/market_intelligence/decisions/README.md

@@ -0,0 +1,130 @@
+# Architecture Decisions
+
+Каталог **decisions/** содержит архитектурные решения (ADR — Architecture Decision Record), принятые во время разработки подсистемы **Market Intelligence**.
+
+В отличие от технической документации, ADR отвечают не на вопрос:
+
+> **Что реализовано?**
+
+а на вопрос:
+
+> **Почему архитектура построена именно так?**
+
+Каждое решение принимается только после возникновения реальной инженерной необходимости.
+
+Создание ADR "на будущее" не допускается.
+
+---
+
+# Иерархия архитектурных решений
+
+Архитектурные решения разделены на три уровня.
+
+```text
+Философия разработки
+        ↓
+Правила разработки
+        ↓
+Архитектурные ограничения
+```
+
+Каждый следующий уровень основывается на предыдущем.
+
+---
+
+# Level 1 — Философия разработки
+
+Данные решения определяют общий подход к развитию платформы.
+
+| Decision | Назначение |
+|----------|------------|
+| 001 | Architecture First |
+| 002 | Build Lifecycle |
+
+---
+
+## Основная идея
+
+Сначала проектируется архитектура.
+
+Затем архитектура развивается небольшими завершёнными Build.
+
+---
+
+# Level 2 — Правила разработки
+
+Данные решения определяют инженерный процесс разработки.
+
+| Decision | Назначение |
+|----------|------------|
+| 003 | Domain Review |
+| 004 | No Existing Code Assumptions |
+| 005 | Human Readable Comments |
+| 007 | Documentation Is Code |
+
+---
+
+## Основная идея
+
+Каждый Build проходит обязательные проверки качества.
+
+Разработка ведётся только на основе существующего кода проекта.
+
+Комментарии объясняют архитектурный смысл.
+
+Документация развивается одновременно с кодом.
+
+---
+
+# Level 3 — Архитектурные ограничения
+
+Данные решения определяют фундаментальные ограничения архитектуры платформы.
+
+| Decision | Назначение |
+|----------|------------|
+| 006 | Immutable Engine Contract |
+
+---
+
+## Основная идея
+
+Все аналитические движки используют единый неизменяемый контракт результатов.
+
+---
+
+# Правила создания новых Decision
+
+Новый ADR создаётся только при выполнении следующих условий:
+
+- возникла реальная инженерная проблема;
+- принято архитектурное решение, влияющее на развитие платформы;
+- решение невозможно корректно описать только комментариями в коде;
+- решение будет полезно при дальнейшем сопровождении проекта.
+
+Создание ADR "на всякий случай" запрещается.
+
+---
+
+# Жизненный цикл ADR
+
+Каждый Architecture Decision проходит одинаковый цикл.
+
+```text
+Проблема
+        ↓
+Анализ вариантов
+        ↓
+Принятие решения
+        ↓
+Документирование
+        ↓
+Использование в проекте
+```
+
+---
+
+# Главный принцип
+
+Architecture Decision Record являются частью архитектуры Dzentra.
+
+Они сохраняют инженерные знания проекта и позволяют развивать платформу последовательно даже спустя годы после принятия первоначальных решений.