🏗️ Архитектурные принципы

Принцип 1: Domain-Core Separation

Описание: Доменная логика изолирована от инфраструктуры. Core-слой не имеет зависимостей от фреймворков, баз данных, HTTP.

Мотивация: Домен — наиболее ценная и стабильная часть системы. Изоляция позволяет тестировать, изменять и переиспользовать бизнес-логику независимо от технических деталей.

Пример нарушения: В доменной сущности Evidence импортируется Prisma client или Express request.

Пример соблюдения: Evidence — чистая TypeScript-сущность с методами, Repository — интерфейс в core, реализация — в инфраструктурном слое.

Проверка на ревью: Импортирует ли код в packages/domain/ что-то из фреймворка? Если да — нарушение.

Принцип 2: Change Protocol First

Описание: Любое изменение, затрагивающее конституцию, доменную модель или архитектуру, начинается с протокола изменений (см. CHANGE_PROTOCOL.md). Код пишется после документации.

Мотивация: Конституция — единственный источник истины. Если изменение не зафиксировано, оно не существует.

Пример нарушения: Разработчик изменил структуру Evidence, добавил поле source_url прямо в код, не обновив CORE_DOMAIN_MODEL.md и DOMAIN_GLOSSARY.md.

Пример соблюдения: Разработчик создал Change Request с описанием нового поля, дождался ADR, обновил конституцию, затем реализовал.

Принцип 3: Immutability by Design

Описание: JTBD, Offer и Experiment имеют версии. После публикации версия неизменяема. Изменения — через новую версию.

Мотивация: Эксперименты и JTBD-гипотезы — это исторические записи. Изменение прошлого делает результаты экспериментов невалидными и нарушает audit trail.

Пример нарушения: Исправление опечатки в опубликованном JTBDVersion напрямую в базе.

Пример соблюдения: Создание новой версии JTBDVersion v1.1 с исправлением, сохранение v1.0 как historical record.

Принцип 4: Evidence over Opinion

Описание: Продуктовые и архитектурные решения принимаются на основе собранных свидетельств, а не мнений. Каждая opportunity card должна ссылаться на evidence.

Мотивация: Субъективные решения приводят к waste: разработка ненужных фич, неверная приоритизация, bias.

Пример нарушения: Включение фичи "чат-бот на сайте" в roadmap, потому что "это модно".

Пример соблюдения: Включение фичи "лендинг для аренды станков" на основе 30 запросов "аренда ткацкого станка" из Метрики.

Принцип 5: Pay for Use

Описание: Архитектура не строит для гипотетических сценариев. Добавляем сложность только когда есть реальные доказательства необходимости.

Мотивация: YAGNI (You Ain't Gonna Need It). Преждевременная оптимизация и абстрагирование — основной источник complexity debt.

Пример нарушения: Добавление абстрактного DataPipelineEngine для обработки данных "на будущее".

Пример соблюдения: Добавление конкретного обработчика JSON из Метрики, рефакторинг в абстракцию — когда появится второй источник.

Принцип 6: Traceability

Описание: Каждый элемент системы трассируется от Vision до кода. Можно проследить, как North Star → Scope → Domain → API → UI → Tests.

Мотивация: Прозрачность решений. Возможность ответить на вопрос "почему это здесь?" на любом уровне системы.

Пример нарушения: В коде есть поле landing_variant_id, но нигде не описано, зачем оно и как связано с доменом.

Пример соблюдения: В TRACEABILITY_POLICY.md описан шаблон, каждый элемент модели имеет trace_id, связывающий с конституционным документом и ADR.

Принцип 7: Convention over Configuration

Описание: Конфигурация платформы выполняется через доменные сущности, а не через YAML-файлы, флаги feature toggle или environment variables.

Мотивация: Конфигурация через домен видна, версионируется, проходит через change protocol и может быть проанализирована.

Пример нарушения: FEATURE_AREND_STANKOV=true в .env.

Пример соблюдения: Создание Offer "Аренда станка СТР-2" через Offer Registry — это и есть включение функциональности.

Принцип 8: Open-Closed Contexts

Описание: Bounded contexts открыты для расширения (добавление новых событий, обработчиков) и закрыты для модификации (изменение существующей логики без протокола).

Мотивация: Изоляция контекстов. Новое поведение добавляется через новые модули/события, не затрагивая работающие контексты.

Пример нарушения: Добавление поля experiment_id в Evidence Graph для "быстрой интеграции" с Experiment контекстом.

Пример соблюдения: Experiment Context подписывается на событие evidence.created и создаёт свои записи связей.

Принцип 9: Tenant Isolation

Описание: Данные клиентов строго изолированы. Каждая сущность содержит tenant_id (organization_id). Запросы всегда фильтруются по tenant.

Мотивация: Безопасность и compliance. Ошибка изоляции — критический инцидент.

Пример нарушения: SQL-запрос без WHERE organization_id = ?.

Пример соблюдения: Все repository методы принимают organization_id как обязательный параметр, middleware добавляет фильтр.

Принцип 10: Failure Transparency

Описание: Ошибки логируются и трассируются, не замалчиваются. Crash early, crash visible.

Мотивация: Невидимые ошибки хуже видимых. Silent failures приводят к некорректным данным, что подрывает доверие к evidence.

Пример нарушения: try { ... } catch { /* ничего */ }.

Пример соблюдения: try { ... } catch (error) { logger.error('Evidence creation failed', { error, entity: evidenceData }); throw; } с записью в AuditLog.