feat: уточнить архитектурные границы SLM

This commit is contained in:
2026-07-30 21:44:47 +03:00
parent 4ce6bae61c
commit 15805e28df
28 changed files with 1006 additions and 553 deletions

View File

@@ -2,42 +2,47 @@
> Статус: рабочий черновик. Документы в этой папке не являются спецификацией.
Level 2 предназначен для приложений с устойчивыми доменными API, несколькими способами сборки или самостоятельными framework-модулями домена. Он сохраняет слои Level 1, но заменяет простой доменный модуль доменным пакетом с явными владельцами ролей.
Level 2 предназначен для отдельных предметных областей с устойчивыми API, несколькими способами сборки или самостоятельными framework-модулями. Он сохраняет структурную базу Level 1, но заменяет выбранный доменный модуль доменным пакетом с явными владельцами ролей.
## Наследование Level 1
Level 2 соблюдает определения и правила Level 1, кроме явно заменённых положений:
Доменный пакет Level 2 соблюдает определения и правила Level 1, кроме явно заменённых положений:
| Положение Level 1 | Статус в Level 2 |
|---|---|
| Порядок `app → compositions → domains → infra ui → shared` | Сохраняется |
| Матрица `app → compositions → domains → { infra, ui } → shared` | Сохраняется |
| Модуль, Group, сегмент, компонент, публичный API и граф зависимостей | Сохраняют смысл |
| Доменный модуль и [`SLM-L1-DOMAIN-R015`](../rules/level-1.md#slm-l1-domain-r015) | Заменяются доменным пакетом |
| Единый публичный API модуля `business` | Представлен тремя объявленными фасетами одного логического API |
| Навигационная Group слоя `domains` | Может содержать доменные пакеты |
| Доменный модуль и [`SLM-L1-DOMAIN-R015`](../rules/level-1.md#slm-l1-domain-r015) | Заменяются только для предметной области в пакетной форме |
| Единый публичный API модуля `business` | Представлен обязательными type-only и factory-фасетами и необязательным runtime-фасетом |
| Навигационная Group слоя `domains` | Может одновременно содержать доменные модули и пакеты |
| Group внутри доменного пакета | Содержит обычные SLM-модули и Groups |
Канонический набор требований образуют [правила Level 1](../rules/level-1.md) и [правила Level 2](../rules/level-2.md).
## Когда выбирать Level 2
Level 2 оправдан, когда предметной области нужны один устойчивый `DomainApi`, разные сборки для браузера и сервера, несколько технических интеграций или самостоятельные domain-specific модули React, Vue либо другого фреймворка.
Level 2 оправдан, когда одной предметной области нужны несколько независимо собираемых Domain API, разные browser/server assemblies, несколько технических интеграций или самостоятельные domain-specific модули React, Vue либо другого фреймворка.
Уровень выбирается для всего SLM root. Проект, в котором всем предметным областям достаточно простых доменных модулей, остаётся на Level 1. После завершённого перехода на Level 2 каждая предметная область представлена доменным пакетом как минимум с `business` и одним preset.
Level 2 выбирается для конкретной предметной области. Один SLM root может корректно содержать простые доменные модули Level 1 и доменные пакеты Level 2. Размер каталога сам по себе не требует перехода.
Размер каталога сам по себе не требует перехода.
## Цена Level 2
Пакетная форма намеренно дороже простого доменного модуля. Она добавляет отдельные business-фасеты, минимум одну assembly, явную runtime-инъекцию cross-domain API и adapter-модули для production capabilities. Concrete state/query runtime, SDK и недетерминизм не импортируются напрямую в `business`.
Эта цена оправдана независимой сборкой API, несколькими средами, строгой environment boundary или самостоятельными framework bindings. Если домену не нужны такие свойства, он остаётся модулем Level 1.
## Базовая форма
```text
src/domains/
── auth/ # Доменный пакет
── catalog/ # Доменный модуль Level 1
└── auth/ # Доменный пакет Level 2
├── README.md # Необязательная metadata
├── business/ # Обязательный SLM-модуль
│ ├── index.ts # Только public types
│ ├── factory.ts # Public factory entry
│ └── error.ts # Public error runtime entry
├── presets/ # Обязательная непустая Group
│ ├── factory.ts # Public factories entry
│ └── runtime.ts # Необязательный deterministic runtime
├── assemblies/ # Обязательная непустая Group
│ ├── browser/ # SLM-модуль
│ └── request/ # SLM-модуль
├── adapters/ # При наличии technical dependencies
@@ -51,33 +56,47 @@ src/domains/
## Публичные границы
Приложение получает данные, состояние и результаты домена через готовый экземпляр `DomainApi`. Технический код импортирует только API конкретного модуля:
`business` может объявить несколько API и соответствующих фабрик. Assembly создаёт только нужный для своего контекста именованный граф:
```ts
import type { AuthApi, AuthError } from '@/domains/auth/business'
import { authFactory } from '@/domains/auth/business/factory'
import { isAuthError } from '@/domains/auth/business/error'
import { createBrowserAuth } from '@/domains/auth/presets/browser'
import type {
AuthAdministrationApi,
AuthSessionApi,
} from '@/domains/auth/business'
import {
authAdministrationFactory,
authSessionFactory,
} from '@/domains/auth/business/factory'
import {
AUTH_ERROR_CODES,
isAuthError,
} from '@/domains/auth/business/runtime'
import { createBrowserAuth } from '@/domains/auth/assemblies/browser'
import { AuthSessionProvider } from '@/domains/auth/react/session'
import { LoginForm } from '@/domains/auth/react/login-form'
```
Общие импорты `@/domains/auth` и `@/domains/auth/react` запрещены: пакет и Groups не имеют агрегирующих API. Другие пути внутри `business`, кроме `business`, `business/factory` и `business/error`, являются deep imports.
`business/runtime` существует только при наличии реальных внешних потребителей детерминированных runtime-экспортов. Общие импорты `@/domains/auth` и `@/domains/auth/react` запрещены: пакет и Groups не имеют агрегирующих API.
## Миграция
## Совместное применение форм
Доменные модули Level 1 могут временно сосуществовать с пакетами Level 2 только во время перехода. Такое состояние не является завершённым соответствием Level 2. По [`SLM-L2-MIGRATION-A017`](../rules/level-2.md#slm-l2-migration-a017) старые модули и новые пакеты не создают прямых runtime- или type-only зависимостей; связанные части графа мигрируют вместе.
Простой доменный модуль и доменный пакет могут постоянно сосуществовать в одном SLM root, но одна предметная область имеет только одну форму. При связи, пересекающей границу пакета Level 2, доменный код использует type-only публичный контракт либо детерминированный `business/runtime`; готовые API передаются runtime-аргументами в месте сборки графа.
Если доменному модулю Level 1 нужна runtime-инъекция, которой его текущий публичный API не поддерживает, этот потребитель рефакторится или сам переводится в пакетную форму. Level 2 не создаёт скрытый механизм внедрения в старый модуль.
## Карта черновика
- [Терминология](./terminology.md)
- [Доменный пакет](./domains/domain-package.md)
- [Модуль business](./domains/business.md)
- [Фабрика, зависимости и адаптеры](./domains/factory-ports-adapters.md)
- [Presets и среды выполнения](./domains/presets.md)
- [Фабрики, зависимости и adapters](./domains/factory-ports-adapters.md)
- [Assemblies и среды выполнения](./domains/assemblies.md)
- [Состояние и кэш](./domains/state-cache.md)
- [Framework Groups и модули](./domains/framework-bindings.md)
- [Зависимости](./dependencies.md)
- [Тестирование](./domains/testing.md)
- [Проверка](./validation.md)
- [Миграция auth](./domains/auth-example.md)
- [Переход auth](./domains/auth-example.md)
- [Открытые вопросы](./domains/open-questions.md)