mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 15:30:16 +03:00
144 lines
12 KiB
Markdown
144 lines
12 KiB
Markdown
# Терминология 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` может импортироваться напрямую по пути, установленному стайлгайдом, и не является узлом графа модулей. Доступный по этому пути файл является всей единицей и не скрывает отдельное внутреннее устройство.
|
||
|
||
Если ресурсу нужны самостоятельная ответственность, собственные архитектурные зависимости, несколько файлов реализации, изменяемое состояние, ввод-вывод или область жизни, он оформляется как модуль.
|
||
|
||
## Структурная модель
|
||
|
||
```text
|
||
SLM root
|
||
├── app
|
||
│ └── точка входа фреймворка
|
||
├── compositions | domains | infra | ui
|
||
│ ├── группа
|
||
│ │ └── модуль
|
||
│ └── модуль
|
||
│ ├── корневые файлы
|
||
│ ├── сегмент
|
||
│ │ ├── файлы
|
||
│ │ ├── компоненты
|
||
│ │ └── вложенные модули
|
||
│ └── вложенный модуль
|
||
└── shared
|
||
├── группа
|
||
├── модуль
|
||
└── ресурс shared
|
||
```
|
||
|
||
Путь и имя папки сами по себе не определяют сущность. Её определяют ответственность, владелец и публичная граница. Физическое сопоставление путей с сущностями задаётся стайлгайдом или конфигурацией проверки проекта.
|