mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 07:30:16 +03:00
feat: уточнить архитектурные границы SLM
This commit is contained in:
@@ -2,21 +2,29 @@
|
||||
|
||||
> Нормативные определения рабочего черновика. Этот раздел не объявляет правила.
|
||||
|
||||
Level 2 наследует терминологию Level 1, сохраняет порядок `app → compositions → domains → infra → ui → shared` и заменяет доменный модуль новой контейнерной сущностью.
|
||||
Level 2 наследует терминологию и матрицу слоёв Level 1. Он применяется отдельно к предметным областям, которым нужна пакетная форма, и не требует переводить остальные доменные модули того же SLM root.
|
||||
|
||||
## Доменный пакет
|
||||
## Формы домена
|
||||
|
||||
### Форма домена
|
||||
|
||||
Структурное представление одной доменной ответственности. На Level 1 предметная область представлена доменным модулем. Для предметной области, использующей Level 2, этот модуль заменяется доменным пакетом. Одна предметная область не использует обе формы одновременно.
|
||||
|
||||
### Доменный пакет
|
||||
|
||||
Самостоятельная контейнерная предметная граница слоя `domains`, представляющая одну доменную ответственность. Доменный пакет не является модулем или Group. Он объединяет SLM-модули и Groups одной предметной области, но не имеет собственного исполняемого кода, состояния, жизненного цикла, публичного API или узла графа зависимостей.
|
||||
|
||||
Корень пакета может содержать только декларативную metadata, обязательный модуль `business` и допустимые Groups. Metadata хранит статические данные о пакете, владении либо конфигурации проверки и не содержит кода, выполняемого приложением, сборщиком или проверяющим инструментом.
|
||||
Корень пакета может содержать только декларативную metadata, обязательный модуль `business` и допустимые Groups. Metadata хранит статические данные о пакете, владении либо конфигурации проверки и не содержит кода, выполняемого приложением.
|
||||
|
||||
Доменный пакет является policy boundary: проверка использует объявленную принадлежность модулей пакету для контроля структуры и междоменных связей. Публичными dependency boundaries кода остаются модули внутри пакета, а не пакет целиком.
|
||||
|
||||
### Навигационная Group слоя `domains`
|
||||
|
||||
Group, размещённая непосредственно в слое `domains` или другой такой Group. На Level 2 она классифицирует доменные пакеты и другие навигационные Groups, но не содержит исполняемый код и не образует dependency boundary.
|
||||
Group, размещённая непосредственно в слое `domains` или другой такой Group. Она классифицирует доменные модули Level 1, доменные пакеты Level 2 и другие навигационные Groups, но не содержит исполняемый код и не образует dependency boundary.
|
||||
|
||||
### Модуль доменного пакета
|
||||
|
||||
Обычный SLM-модуль внутри доменного пакета. Его ответственность относится к одной роли пакета: business, preset, adapter или framework binding. Каждый такой модуль имеет отдельную папку, публичный API и узел графа зависимостей.
|
||||
Обычный SLM-модуль внутри доменного пакета. Его ответственность относится к одной роли пакета: business, assembly, adapter или framework binding. Каждый такой модуль имеет отдельную папку, публичный API и узел графа зависимостей.
|
||||
|
||||
Модуль внутри Group пакета не является вложенным модулем, потому что его ближайшая внешняя граница не является модулем.
|
||||
|
||||
@@ -24,57 +32,77 @@ Group, размещённая непосредственно в слое `domain
|
||||
|
||||
### Модуль business
|
||||
|
||||
Обязательный SLM-модуль `business`, который определяет публичные предметные сценарии, `DomainApi`, одну фабрику, типы зависимостей и публичный контракт доменных ошибок.
|
||||
Обязательный SLM-модуль `business`, который определяет публичные предметные сценарии, один или несколько именованных Domain API, соответствующие им фабрики, типы зависимостей и публичные контракты ожидаемых ошибок.
|
||||
|
||||
`business` является единственным runtime-источником, через который приложение получает доменные данные, состояние и результаты сценариев. Он не зависит от конкретного фреймворка, среды или технической реализации.
|
||||
`business` является предметным владельцем данных, моделей, переходов и результатов сценариев домена. Он не зависит от конкретного фреймворка, среды или технической реализации.
|
||||
|
||||
### Публичные фасеты business
|
||||
|
||||
Три объявленных entry points одного логического публичного API модуля `business`:
|
||||
Объявленные entry points одного логического публичного API модуля `business`:
|
||||
|
||||
| Путь | Содержимое |
|
||||
|---|---|
|
||||
| `business` | Только public types, включая `DomainApi`, зависимости, factory type, DomainError и DomainErrorCode |
|
||||
| `business/factory` | Единственная runtime-фабрика `DomainApi` |
|
||||
| `business/error` | Runtime-коды и guards доменных ошибок |
|
||||
| Путь | Статус | Содержимое |
|
||||
|---|---|---|
|
||||
| `business` | Обязательный | Только public types, включая Domain API, зависимости, factory types и error types |
|
||||
| `business/factory` | Обязательный | Только именованные runtime-фабрики Domain API |
|
||||
| `business/runtime` | Необязательный | Только публичные детерминированные runtime-значения и функции |
|
||||
|
||||
Фасет `business/runtime` может публиковать устойчивые error codes и guards, validators, value constructors, предметные константы и чистые функции, если они нужны реальным внешним потребителям. Он не содержит фабрики, изменяемое состояние, ввод-вывод, сценарии с runtime-зависимостями или environment-specific код.
|
||||
|
||||
Фасеты не являются сегментами, вложенными модулями или самостоятельными узлами графа. Любой другой внешний путь внутрь `business` является deep import.
|
||||
|
||||
### Business-safe внешний пакет
|
||||
|
||||
Внешняя библиотека, допустимая в import-графе `business`: детерминированная, environment-neutral, не выполняющая ввод-вывод и не владеющая изменяемым состоянием или runtime capability. SDK, generated client, storage, state manager, framework и техническая интеграция не становятся business-safe только из-за совместимости с несколькими средами.
|
||||
Внешняя библиотека, допустимая в import-графе `business`: детерминированная, environment-neutral, не выполняющая ввод-вывод и не владеющая изменяемым состоянием или runtime capability. SDK, generated client, storage, state manager, query runtime, framework и техническая интеграция не становятся business-safe только из-за совместимости с несколькими средами.
|
||||
|
||||
### DomainApi
|
||||
### Domain API
|
||||
|
||||
Единый публичный runtime-контракт домена, экземпляр которого создаёт фабрика `business`. Все presets одной предметной области создают API этого контракта и не добавляют собственные предметные методы.
|
||||
Именованный публичный runtime-контракт связного набора предметных сценариев внутри одного домена. Модуль `business` может объявить несколько Domain API, если они независимо собираются, имеют разные технические зависимости или нужны разным средам и потребителям.
|
||||
|
||||
Разделение на API не создаёт новые доменные пакеты и не разрешает дублировать один сценарий в нескольких контрактах. Каждый публичный сценарий принадлежит ровно одному Domain API.
|
||||
|
||||
### Фабрика business
|
||||
|
||||
Единственная публичная функция `business`, которая получает явные зависимости и создаёт экземпляр `DomainApi`. Фабрика не выбирает конкретный preset и не определяет среду выполнения.
|
||||
Публичная функция фасета `business/factory`, которая получает явные зависимости и создаёт экземпляр одного объявленного Domain API. Каждому Domain API соответствует ровно одна публичная фабрика. Фабрика не выбирает assembly или среду выполнения.
|
||||
|
||||
### Предметная власть business
|
||||
|
||||
Право определять публичную доменную модель, допустимые переходы, валидацию внешних значений и семантику результатов. Adapter, assembly или framework binding может хранить, кэшировать и проецировать значения Domain API, но не становится независимым источником предметной модели или переходов.
|
||||
|
||||
### Доменная ошибка
|
||||
|
||||
Безопасная публичная форма ожидаемого сбоя предметного сценария. Модуль `business` объявляет устойчивые коды, тип ошибки и runtime guard. Ошибки SDK, транспорта, storage, адаптера или другого домена не являются доменными ошибками текущего API.
|
||||
Безопасная публичная форма ожидаемого сбоя предметного сценария. Модуль `business` объявляет устойчивый readonly-тип с кодом; при необходимости runtime-коды и guards публикуются через `business/runtime`. Ошибки SDK, транспорта, storage, adapter или другого домена не являются доменными ошибками текущего API.
|
||||
|
||||
Способ передачи ошибки, например exception или discriminated `Result`, не изменяет владение и публичную безопасность ошибки.
|
||||
|
||||
## Техническая сборка
|
||||
|
||||
### Техническая зависимость
|
||||
|
||||
Явная runtime-возможность, необходимая business-фабрике и требующая production-реализации поверх SDK, storage, API платформы, данных запроса или технического сервиса. Type-only cross-domain API dependency, неизменяемая конфигурация и аргумент отдельного предметного сценария не являются техническими зависимостями.
|
||||
Явная runtime-возможность, необходимая business-фабрике и требующая production-реализации. К техническим зависимостям относятся источники данных, SDK, storage, API платформы, state/query runtime, технические сервисы, данные request scope, clock, timer, random, ID generator и другие источники ввода-вывода, состояния или недетерминизма.
|
||||
|
||||
Type-only cross-domain API dependency, неизменяемая конфигурация и аргумент отдельного предметного сценария не являются техническими зависимостями.
|
||||
|
||||
### Adapter
|
||||
|
||||
SLM-модуль в Group `adapters`, который реализует одну или несколько связанных технических зависимостей фабрики поверх SDK, storage, API платформы, данных запроса или технического сервиса. Каждая production-реализация принадлежит adapter-модулю и не размещается внутри preset или composition.
|
||||
SLM-модуль в Group `adapters`, который реализует одну или несколько связанных технических зависимостей business-фабрик поверх SDK, storage, state/query runtime, API платформы, данных запроса или технического сервиса. Одна связная production-реализация принадлежит одному adapter-модулю и не размещается внутри assembly или composition.
|
||||
|
||||
Group `adapters` обязательна и непуста, если фабрика имеет техническую зависимость. Фабрика без технических зависимостей не требует создания этой Group.
|
||||
Group `adapters` обязательна и непуста, если хотя бы одна business-фабрика имеет техническую зависимость. Фабрики без технических зависимостей не требуют создания этой Group.
|
||||
|
||||
Точная обязательная форма технических портов пока не определена и остаётся открытым вопросом Level 2.
|
||||
Точная обязательная поведенческая форма технических портов пока не определена и остаётся открытым вопросом Level 2.
|
||||
|
||||
### Preset
|
||||
### Assembly
|
||||
|
||||
SLM-модуль в Group `presets`, который создаёт `DomainApi` для одного именованного контекста выполнения: браузера, запроса, server action или другого реального окружения. При наличии технических зависимостей он выбирает их adapter-модули и передаёт фабрике готовые runtime-зависимости.
|
||||
SLM-модуль в Group `assemblies`, который создаёт явный именованный граф одного или нескольких Domain API пакета для одного реального контекста выполнения: браузера, запроса, server action или другого окружения. При наличии технических зависимостей assembly выбирает их adapter-модули и передаёт фабрикам готовые runtime-зависимости.
|
||||
|
||||
Каждый доменный пакет содержит минимум один preset. Архитектура не ограничивает их максимальное количество и не требует универсального изоморфного preset.
|
||||
Assembly может принимать готовые API других доменов аргументами. Она не добавляет предметные сценарии, методы API или собственные доменные ошибки.
|
||||
|
||||
Каждый доменный пакет содержит минимум одну assembly. Архитектура не ограничивает их максимальное количество и не требует универсальной изоморфной assembly.
|
||||
|
||||
### Ресурс assembly
|
||||
|
||||
Ресурс жизненного цикла, который assembly сама создаёт для возвращаемого графа API. Создание фабрики или assembly не запускает скрытую долгоживущую работу. Если технический ресурс необходимо активировать при сборке, публичный результат assembly предоставляет cleanup handle; если ресурс запускается явной операцией API, эта операция предоставляет cleanup.
|
||||
|
||||
Assembly без собственного ресурса жизненного цикла не обязана возвращать пустой `dispose`.
|
||||
|
||||
## Framework binding
|
||||
|
||||
@@ -84,15 +112,17 @@ Group доменного пакета, названная по конкретн
|
||||
|
||||
### Framework binding module
|
||||
|
||||
SLM-модуль внутри Framework Group, ответственность которого ограничена domain-specific интеграцией с фреймворком. Например, `react/session` может владеть Provider и hooks сессии, а `react/login-form` — переиспользуемой формой авторизации.
|
||||
SLM-модуль внутри Framework Group, ответственность которого ограничена domain-specific интеграцией с фреймворком. Например, `react/session` может владеть Provider и hooks сессии, а `react/login-form` - переиспользуемой формой авторизации.
|
||||
|
||||
Framework binding module получает готовый `DomainApi`, не вызывает фабрику или preset и не импортирует framework-состояние, hooks или компоненты другого доменного пакета.
|
||||
Framework binding module получает готовые Domain API, не вызывает фабрику или assembly и не импортирует framework-состояние, hooks или компоненты другого домена. Он может использовать совместимые с его ролью state/query libraries и технически кэшировать результаты Domain API, не создавая новую предметную модель.
|
||||
|
||||
## Сборка графа
|
||||
|
||||
### Место сборки графа
|
||||
|
||||
Код модуля `composition`, точки входа `app`, request handler или test setup, который создаёт нужные экземпляры `DomainApi` в ацикличном порядке и передаёт уже созданные API preset-модулям либо напрямую зависимым business-фабрикам. Место сборки не становится владельцем предметных или технических ответственностей модулей. Подробный lifecycle собранного графа пока не нормирован Level 2.
|
||||
Код модуля `composition`, точки входа `app`, request handler или test setup, который создаёт assemblies либо напрямую вызывает фабрики в ацикличном порядке и передаёт уже созданные API зависимым сборкам.
|
||||
|
||||
Место сборки владеет областью жизни совокупного графа и вызывает предоставленные cleanup handles не позже её завершения. Это координационное владение не переносит к нему предметные или технические ответственности внутренних модулей.
|
||||
|
||||
### Граница среды выполнения
|
||||
|
||||
@@ -103,11 +133,12 @@ Framework binding module получает готовый `DomainApi`, не вы
|
||||
```text
|
||||
SLM root
|
||||
└── domains
|
||||
└── доменный пакет
|
||||
├── доменный модуль Level 1
|
||||
└── доменный пакет Level 2
|
||||
├── metadata
|
||||
├── модуль business
|
||||
├── обязательная Group presets
|
||||
│ └── preset-модуль
|
||||
├── обязательная Group assemblies
|
||||
│ └── assembly-модуль
|
||||
├── Group adapters при наличии технических зависимостей
|
||||
│ └── adapter-модуль
|
||||
└── Framework Group react
|
||||
|
||||
Reference in New Issue
Block a user