mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 15:30:16 +03:00
149 lines
12 KiB
Markdown
149 lines
12 KiB
Markdown
---
|
||
title: SLM Design
|
||
description: Назначение архитектуры, ключевые принципы и карта разделов документации
|
||
---
|
||
|
||
# Основы SLM Design
|
||
|
||
Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.
|
||
|
||
## Рабочий алгоритм
|
||
|
||
1. Заполни архитектурную карточку из [процесса принятия решения](./decision-process.md): роль, владелец, данные, runtime-capabilities, место, public API, lifecycle и проверки.
|
||
2. Сначала выбери слой ответственности, затем module scope, затем segments и только после этого конкретные файлы.
|
||
3. Для product data и domain state примени [runtime-границу business](./business-runtime-boundary.md).
|
||
4. Выбирай минимальное корректное место и не создавай общий provider, store, package или business-контракт «на будущее».
|
||
5. После реализации пройди [архитектурную проверку](./validation.md). Задача не завершена без обязательных business и assembly tests.
|
||
|
||
## Дополнительные примеры
|
||
|
||
Каноны ниже достаточны для базового архитектурного решения. Если нужен подробный пример реализации, открой конкретный файл:
|
||
|
||
- [Композиция через Provider](../examples/react/composition-provider.md) — page-level provider, store и business composition.
|
||
- [Структуры compositions](../examples/react/composition-structures.md) — допустимые структуры слоя `compositions`.
|
||
- [Business composition](../examples/business-composition.md) — runtime-сборка business-фабрик в `compositions/business/{domain}`.
|
||
- [Тестирование business-модулей](../examples/business-testing.md) — factory-level тесты и тесты сборки.
|
||
|
||
## Разделы спецификации
|
||
|
||
Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:
|
||
|
||
- [Слои](./layers.md) — уровни организации `src/`, направление зависимостей и зона ответственности каждого слоя.
|
||
- [Модули](./modules.md) — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
|
||
- [Атлас файлов SLM](./file-atlas.md) — root files, segments, структуры всех типов modules, public API и tests.
|
||
- [Business-фабрика](./business-factory.md) — контракт business-модуля, logic API, deps, доменные ошибки и сборка фабрик.
|
||
- [Runtime-граница business](./business-runtime-boundary.md) — capabilities фабрики, adapters, hooks, stores и безусловные domain errors.
|
||
- [Сегменты](./segments.md) — внутренние папки модуля (`ui/`, `parts/`, `hooks/`, `types/` и другие) и правила размещения файлов.
|
||
- [Монорепозитории](./monorepo.md) — применение SLM в `apps/` и `packages/`, правила выноса общих слоёв и ограничения для business/compositions.
|
||
- [Архитектурная проверка](./validation.md) — блокирующие gates создания, рефакторинга и ревью.
|
||
|
||
Рекомендуемый порядок чтения: процесс решения → runtime-граница business → архитектурная проверка → атлас или подробности только нужной ветки.
|
||
|
||
## Преимущества
|
||
|
||
### Единый слой композиции
|
||
|
||
Страницы, маршруты и крупные продуктовые части интерфейса собираются в `compositions`. Слой не навязывает жёсткую структуру: команда может использовать `pages/layouts/screens/widgets` или другую организацию под свой фреймворк и продукт.
|
||
|
||
### Вертикальная организация домена
|
||
|
||
Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы, hooks, services и mappers живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: доменная логика локализована.
|
||
|
||
### Dependency Injection без фреймворков
|
||
|
||
Runtime-зависимости business-модуля реализуются через фабрики — модуль декларирует что ему нужно, а composition-сборка предоставляет зависимости. Домены изолированы от SDK, storage и backend-клиентов без DI-контейнеров и шин событий.
|
||
|
||
### Разделение ответственности без перегрузки слоёв
|
||
|
||
Композиция приложения (`compositions/`), сервисы приложения (`infra/`), UI-кит (`ui/`) и общие ресурсы (`shared/`) — разные слои с разной природой. Ни один слой не превращается в свалку разнородного кода.
|
||
|
||
### Графовая композиция там, где она нужна
|
||
|
||
Внутри `compositions` допускается граф импортов через публичный API. Это позволяет page-level store, provider или сборку business-фабрик использовать одновременно в layout, screen и widget, не перенося продуктовый runtime-state в `infra` или `shared`.
|
||
|
||
### Горизонтальная инкапсуляция
|
||
|
||
Вложенные модули (`parts/`) и публичные API позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.
|
||
|
||
### Колокация по умолчанию
|
||
|
||
Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.
|
||
|
||
### Масштабирование через группировку
|
||
|
||
При росте проекта слои не теряют структуру — модули группируются по естественным признакам: композиции по страницам и маршрутам, бизнес-домены по субдоменам, UI-компоненты по уровню абстракции.
|
||
|
||
### Адаптация к монорепозиториям
|
||
|
||
SLM применяется внутри каждого приложения, а `packages/*` используются только для общего кода из слоёв `ui`, `infra` и `shared`. `compositions` и бизнес-домены остаются внутри приложений, чтобы не размывать продуктовые границы.
|
||
|
||
## Происхождение
|
||
|
||
SLM Design вырос на основе:
|
||
|
||
- **Feature-Sliced Design** — слоистая структура, публичный API модуля, направление зависимостей
|
||
- **Vertical Slice Architecture** — модуль как вертикальный срез, содержащий всё необходимое
|
||
- **Screaming Architecture** — структура проекта «кричит» о назначении: открыл `business/auth` — видишь авторизацию
|
||
- **Colocation Principle** — код живёт рядом с местом использования
|
||
|
||
## Пример структуры проекта
|
||
|
||
```text
|
||
src/
|
||
├── app/
|
||
│
|
||
├── compositions/
|
||
│ ├── business/
|
||
│ │ ├── auth/
|
||
│ │ └── user/
|
||
│ ├── pages/
|
||
│ │ ├── home/
|
||
│ │ ├── profile/
|
||
│ │ └── product-detail/
|
||
│ ├── layouts/
|
||
│ │ ├── main/
|
||
│ │ └── dashboard/
|
||
│ ├── screens/
|
||
│ │ ├── home/
|
||
│ │ └── profile/
|
||
│ └── widgets/
|
||
│ ├── page-heading/
|
||
│ └── promo-banner/
|
||
│
|
||
├── business/
|
||
│ ├── auth/
|
||
│ ├── catalog/
|
||
│ ├── orders/
|
||
│ └── chat/
|
||
│
|
||
├── infra/
|
||
│ ├── theme/
|
||
│ ├── i18n/
|
||
│ ├── backend-api/
|
||
│ └── logger/
|
||
│
|
||
├── ui/
|
||
│ ├── button/
|
||
│ ├── input/
|
||
│ ├── modal/
|
||
│ ├── toast/
|
||
│ └── dropdown/
|
||
│
|
||
└── shared/
|
||
├── lib/
|
||
├── types/
|
||
└── styles/
|
||
```
|
||
|
||
## Принципы
|
||
|
||
- **Композиция — отдельный слой.** Страницы, маршруты и крупные продуктовые части интерфейса собираются в `compositions`.
|
||
- **Структура композиции свободна.** Команда сама выбирает организацию внутри `compositions`; базовая рекомендация — `pages/layouts/screens/widgets`.
|
||
- **Домен — единое целое.** Доменная модель, сценарии, типы, services и mappers живут в одном business-модуле. Concrete data/state/query hooks передаются фабрике через adapters.
|
||
- **Колокация.** Код рождается рядом с местом использования и поднимается только при необходимости.
|
||
- **Зависимости однонаправлены за пределами compositions.** `app` подключает `compositions`; `compositions` связывает `business`, `infra`, `ui` и `shared`; `business` вызывает concrete runtime-возможности только через переданные фабрике `deps`.
|
||
- **Product data проходит через business.** Page, layout, screen и widget не обращаются к product source напрямую.
|
||
- **Ошибки принадлежат домену.** Из business API выходят только собственные domain errors со стабильным `code`.
|
||
- **Внутри compositions допустим граф.** Composition modules могут импортировать друг друга через public API.
|
||
- **Архитектура — каркас, не клетка.** Правила фиксируют границы ответственности и public API, а внутреннюю форму композиции определяет команда.
|