mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 07:30:16 +03:00
166 lines
11 KiB
Markdown
166 lines
11 KiB
Markdown
# Реестр правил SLM
|
||
|
||
Здесь собраны правила SLM. Это единственное место, где они формулируются; тематические документы объясняют архитектуру и ссылаются на коды.
|
||
|
||
## Размещение кода по слоям
|
||
|
||
### SLM-LAYER-R001
|
||
|
||
> **Назначение слоёв**
|
||
>
|
||
> Код внутри SLM root размещается в слое, нормативная роль которого соответствует ответственности этого кода.
|
||
|
||
### SLM-LAYER-A002
|
||
|
||
> **Направление зависимостей**
|
||
>
|
||
> Внутри одного SLM root код каждого слоя может зависеть только от кода целевых слоёв, разрешённых для него нормативной матрицей слоёв.
|
||
|
||
### SLM-LAYER-R003
|
||
|
||
> **Граница слоя `app`**
|
||
>
|
||
> В `app` размещаются только точки входа фреймворка для запуска, маршрутов, преобразования входных данных и подключения публичных API модулей разрешённых слоёв или ресурсов `shared`; ответственности этих модулей остаются за пределами `app`.
|
||
|
||
## Домены
|
||
|
||
### SLM-DOMAIN-R022
|
||
|
||
> **Владение доменным сценарием**
|
||
>
|
||
> Каждый доменный сценарий имеет ровно один модуль-владелец в слое `domains`. Код, который придаёт сценарию предметный смысл или определяет его продуктовый результат, включая модели, правила, переходы, продуктовое состояние, смысл операций с продуктовыми данными, предметные исходы, доменный UI и обслуживающие сценарий framework-механизмы, принадлежит этому модулю. Модули других слоёв, включая `compositions`, могут только использовать и компоновать сценарий через публичный API доменного модуля; отсутствие подходящего доменного модуля не разрешает временную или постоянную реализацию сценария вне `domains`.
|
||
|
||
### SLM-DOMAIN-R023
|
||
|
||
> **Владение доменным контрактом**
|
||
>
|
||
> Домен самостоятельно определяет публичный контракт своих сценариев на основе предметного смысла. Контракт источника данных не определяет форму доменного контракта и не становится его частью.
|
||
|
||
### SLM-DOMAIN-R024
|
||
|
||
> **Граница внешних данных**
|
||
>
|
||
> Данные и типы внешнего источника не пересекают публичную границу домена и не используются как доменные модели, состояние или результаты. Домен адаптирует внешние данные к собственному контракту до их использования в предметной реализации.
|
||
|
||
### SLM-DOMAIN-R025
|
||
|
||
> **Владение доменными ошибками**
|
||
>
|
||
> Домен объявляет публичный контракт ожидаемых неуспешных исходов своих сценариев. Реализация домена и интеграции с источниками используют этот контракт и не определяют независимые ошибки или новые исходы вне доменной декларации. Потребители зависят только от доменного контракта, а способ представления и передачи ошибок SLM не устанавливает.
|
||
|
||
### SLM-DOMAIN-R026
|
||
|
||
> **Изоляция чужих ошибок**
|
||
>
|
||
> Ошибка внешнего источника или другого модуля не пересекает публичную границу домена в исходной форме. Домен преобразует её в собственный ожидаемый исход либо в неожиданный дефект согласно общей политике приложения.
|
||
|
||
## Границы модулей
|
||
|
||
### SLM-MODULE-A004
|
||
|
||
> **Публичный API модуля**
|
||
>
|
||
> Каждый модуль предоставляет единый логический публичный API через обязательный корневой фасет `index` и, при необходимости, фасеты `client`, `browser` и `server`; код за пределами модуля импортирует его содержимое только через эти фасеты.
|
||
|
||
### SLM-MODULE-A014
|
||
|
||
> **Папка модуля**
|
||
>
|
||
> Каждый модуль размещается в отдельной папке; его публичный API и внутренняя реализация находятся внутри этой границы, а вложенные модули образуют собственные папки.
|
||
|
||
### SLM-MODULE-R006
|
||
|
||
> **Ответственность модуля**
|
||
>
|
||
> Одна модульная граница содержит только код, который модуль выполняет сам для обеспечения одного результата или поведения; код, отвечающий за другой результат, принадлежит другой модульной границе.
|
||
|
||
### SLM-MODULE-R011
|
||
|
||
> **Владелец ответственности**
|
||
>
|
||
> Каждая самостоятельная ответственность и относящийся к ней код принадлежат ровно одной ближайшей модульной границе; вне модульной границы допускаются только точки входа `app` и нормативные ресурсы `shared`.
|
||
|
||
### SLM-MODULE-R012
|
||
|
||
> **Состав публичного API**
|
||
>
|
||
> Публичный API модуля открывает только контракт, необходимый реальным внешним потребителям; детали реализации и изменяемые внутренние механизмы остаются закрытыми.
|
||
|
||
### SLM-MODULE-R020
|
||
|
||
> **Глубина framework-компонентов**
|
||
>
|
||
> Помимо опционального главного framework-файла в корне модуля, остальные framework-компоненты, в том числе выполняющие роли Provider, Guard или Error Boundary, размещаются на одном внутреннем уровне относительно модуля; каталог такой единицы может содержать локальный вспомогательный код, но не содержит другие компонентные единицы или вложенные модули.
|
||
|
||
### SLM-MODULE-R021
|
||
|
||
> **Семантика корня модуля**
|
||
>
|
||
> Помимо объявленных публичных фасетов, в корне модуля допускается только один опциональный главный implementation- или assembly-файл, который однозначно отражает, непосредственно реализует или собирает ответственность модуля; вся остальная реализация размещается в сегментах.
|
||
|
||
## Зависимости между модулями
|
||
|
||
### SLM-DEPENDENCY-A005
|
||
|
||
> **Циклические зависимости**
|
||
>
|
||
> Зависимости между модулями внутри одного SLM root, включая вложенные модули, не образуют циклов.
|
||
|
||
## Назначение групп
|
||
|
||
### SLM-GROUP-R007
|
||
|
||
> **Назначение группы**
|
||
>
|
||
> Группа содержит только модули и другие группы, не владеет файлами реализации, состоянием, жизненным циклом или публичным API и не импортируется внешним кодом.
|
||
|
||
## Назначение сегментов
|
||
|
||
### SLM-SEGMENT-R008
|
||
|
||
> **Граница сегмента**
|
||
>
|
||
> Сегмент организует код только внутри одного модуля и не имеет собственной ответственности, публичного API или границы зависимостей.
|
||
|
||
## Границы вложенных модулей
|
||
|
||
### SLM-NESTED_MODULE-A010
|
||
|
||
> **Доступ к вложенному модулю**
|
||
>
|
||
> Код за пределами родительского модуля не импортирует вложенный модуль напрямую и получает его экспорты только через публичный API родителя.
|
||
|
||
## Жизненный цикл
|
||
|
||
### SLM-LIFECYCLE-R013
|
||
|
||
> **Жизненный цикл ресурсов**
|
||
>
|
||
> Для каждого ресурса жизненного цикла модуль-владелец определяет создание, область жизни, число экземпляров и очистку; ресурс активен только внутри своей области жизни.
|
||
|
||
## Границы сред выполнения
|
||
|
||
### SLM-ENVIRONMENT-R016
|
||
|
||
> **Универсальный фасет**
|
||
>
|
||
> Корневой фасет `index` экспортирует только публичный код, совместимый как с серверным рендерингом, включая RSC, так и с клиентским выполнением, и не импортирует или реэкспортирует код фасетов `client`, `browser` или `server` прямо либо транзитивно.
|
||
|
||
### SLM-ENVIRONMENT-R017
|
||
|
||
> **Клиентский фасет**
|
||
>
|
||
> Фасет `client` экспортирует только клиентский код, который не может выполняться как RSC, и не импортирует или реэкспортирует код фасетов `browser` или `server` прямо либо транзитивно.
|
||
|
||
### SLM-ENVIRONMENT-R018
|
||
|
||
> **Браузерный фасет**
|
||
>
|
||
> Фасет `browser` экспортирует browser-only код и клиентский код, предназначенный для динамического подключения без SSR; потребители всегда импортируют его динамически с отключённым SSR.
|
||
|
||
### SLM-ENVIRONMENT-R019
|
||
|
||
> **Серверный фасет**
|
||
>
|
||
> Фасет `server` экспортирует только server-only код и не импортируется или реэкспортируется фасетами `index`, `client` или `browser` прямо либо транзитивно.
|