slm-design/DRAFT/level-1/terminology.md

Терминология Level 1

Нормативные определения рабочего черновика. Этот раздел не объявляет правила.

Определения Level 1 задают обязательный смысл архитектурных терминов и используются при толковании всех правил. Код получают только блокирующие требования, а не сами определения.

Базовые понятия

SLM root

Граница структурной архитектуры одного приложения. Внутри неё определяются слои, модули и граф зависимостей Level 1. Монорепозиторий, пакеты и отношения между несколькими SLM root находятся за пределами Level 1.

Ответственность

Связная часть приложения с одной причиной изменяться. Ответственность является самостоятельной, когда ей нужны собственные публичный API, зависимости, состояние или область жизни.

Владелец

Модуль, который определяет публичный API ответственности, её зависимости, состояние, область жизни и внутреннее устройство. Место выполнения кода не переносит владение.

Публичный API

Единая логическая точка внешнего доступа к модулю. Публичный API скрывает внутреннее устройство; конкретное имя файла и механизм экспорта определяет стайлгайд проекта.

Зависимость

Статическая связь внутри одного SLM root, которую импорт или реэкспорт создаёт между архитектурными границами. Обычный импорт, импорт типа и реэкспорт одинаково создают архитектурную зависимость.

Зависимость любого внутреннего файла, сегмента или компонента относится к ближайшему модулю-владельцу. Вложенный модуль начинает собственную границу и становится отдельным узлом графа зависимостей.

Область жизни

Период, в течение которого принадлежащие модулю состояние или долгоживущий ресурс должны оставаться активными.

Ресурс жизненного цикла

Ресурс, работа которого продолжается после первоначального вызова и требует остановки, отмены, отписки или освобождения. Например, подписка, слушатель событий, таймер, наблюдатель, запрос или соединение.

Очистка

Гарантированное прекращение работы ресурса не позже завершения его области жизни. Автоматическая очистка фреймворка считается очисткой владельца, если модуль устанавливает и контролирует соответствующую границу.

Структурные сущности

Нормативная матрица слоёв

Отношение допустимой зависимости между слоями одного SLM root. Матрица определяет, код каких слоёв может импортировать исходный слой; она не обязана образовывать линейный порядок.

Для Level 1 нормативно отношение app → compositions → domains → { infra, ui } → shared. infra и ui являются независимыми ветвями: они не импортируют друг друга. Промежуточный слой не является обязательным посредником.

Слой

Одна из шести верхнеуровневых ролей внутри SLM root:

Слой	Роль
app	Связь приложения с фреймворком: запуск, маршруты и преобразование входных данных
compositions	Сборка продуктового интерфейса: страницы, макеты, экраны, виджеты и другие композиции
domains	Предметные области, их модели, правила, сценарии и продуктовое состояние
infra	Технические сервисы и возможности приложения
ui	Универсальные модули интерфейса без зависимости от конкретной продуктовой композиции
shared	Независимый детерминированный фундамент без знания о продукте, изменяемого состояния и ввода-вывода

Полная матрица допустимых зависимостей:

Исходный слой	Допустимые целевые слои
app	app, compositions, domains, infra, ui, shared
compositions	compositions, domains, infra, ui, shared
domains	domains, infra, ui, shared
infra	infra, shared
ui	ui, shared
shared	shared

Модуль

Минимальная самостоятельная архитектурная единица Level 1. Модуль владеет одной связной ответственностью, размещается в отдельной папке и предоставляет публичный API.

Доменная ответственность

Связная предметная область приложения, которая может включать собственные модели, правила, сценарии и продуктовое состояние. Количество экранов, endpoint-ов, hooks или файлов само по себе не определяет её границу.

Доменный модуль

Обычный SLM-модуль слоя domains, представляющий одну доменную ответственность. Он подчиняется всем правилам модулей, предоставляет единый публичный API и является узлом графа зависимостей.

Доменный модуль может содержать сегменты, компоненты и вложенные модули. Level 1 не требует разделять его внутреннее содержимое по техническим ролям.

Группа

Навигационная папка для модулей и других групп. Группа не является владельцем ответственности, состояния, области жизни, публичного API или узла графа зависимостей.

Сегмент

Внутренняя часть одного модуля, которая группирует его содержимое по назначению. Сегмент не является самостоятельным владельцем, публичным API или узлом графа зависимостей.

Компонент

Сущность фреймворка, которая реализует часть интерфейса родительского модуля. Компонент не образует собственного владельца, публичного API или узла графа зависимостей.

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

Вложенный модуль

Обычный модуль, размещённый внутри границы родительского модуля. Он имеет собственные ответственность, публичный API и узел графа зависимостей и подчиняется всем общим правилам модулей.

Публичный API вложенного модуля доступен коду родительской границы. Для кода за пределами родительского модуля вложенный модуль остаётся внутренней реализацией родителя.

Точка входа фреймворка

Специальная немодульная единица слоя app, которая непосредственно связывает приложение с фреймворком. Её импорты участвуют в проверке направления слоёв, но сама точка входа не является узлом графа модулей.

Ресурс shared

Специальная немодульная единица слоя shared: небольшая детерминированная утилита, общий тип, стиль, конфигурация или статический ресурс без продуктового знания, изменяемого состояния, ввода-вывода, области жизни и собственного публичного API.

Ресурс shared может импортироваться напрямую по пути, установленному стайлгайдом, и не является узлом графа модулей. Доступный по этому пути файл является всей единицей и не скрывает отдельное внутреннее устройство.

Если ресурсу нужны самостоятельная ответственность, собственные архитектурные зависимости, несколько файлов реализации, изменяемое состояние, ввод-вывод или область жизни, он оформляется как модуль.

Структурная модель

SLM root
├── app
│   └── точка входа фреймворка
├── compositions | domains | infra | ui
│   ├── группа
│   │   └── модуль
│   └── модуль
│       ├── корневые файлы
│       ├── сегмент
│       │   ├── файлы
│       │   ├── компоненты
│       │   └── вложенные модули
│       └── вложенный модуль
└── shared
    ├── группа
    ├── модуль
    └── ресурс shared

Путь и имя папки сами по себе не определяют сущность. Её определяют ответственность, владелец и публичная граница. Физическое сопоставление путей с сущностями задаётся стайлгайдом или конфигурацией проверки проекта.