mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 07:30:16 +03:00
chore: Новый черновик DRAFT, удалить старые docs-v
This commit is contained in:
@@ -1,24 +0,0 @@
|
||||
---
|
||||
layout: home
|
||||
title: SLM Design in English
|
||||
titleTemplate: false
|
||||
sidebar: false
|
||||
hero:
|
||||
name: English edition
|
||||
text: Translation is planned
|
||||
tagline: The Russian specification is currently the only normative source. The English edition will preserve its structure and rule IDs.
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Open Russian specification
|
||||
link: /ru/specification/
|
||||
- theme: alt
|
||||
text: Language selection
|
||||
link: /
|
||||
features:
|
||||
- title: No partial translation
|
||||
details: An incomplete English rule set is not published as normative documentation.
|
||||
- title: Stable identifiers
|
||||
details: Future translated requirements will use the same SLM rule IDs as the Russian source.
|
||||
- title: Equal URL structure
|
||||
details: English documentation is reserved under /en/ alongside the Russian /ru/ section.
|
||||
---
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
layout: home
|
||||
title: SLM Design
|
||||
titleTemplate: false
|
||||
sidebar: false
|
||||
hero:
|
||||
name: SLM Design
|
||||
text: Explicit architecture boundaries
|
||||
tagline: A draft specification for ownership, dependencies, runtime, and lifecycle in product applications.
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Русская спецификация
|
||||
link: /ru/
|
||||
- theme: alt
|
||||
text: English
|
||||
link: /en/
|
||||
features:
|
||||
- title: Base SLM
|
||||
details: A complete minimal architecture built around explicit ownership and five application layers.
|
||||
- title: Independent overlays
|
||||
details: Advanced and Pro add separate rule sets directly to base SLM without inheriting each other.
|
||||
- title: Stable rules
|
||||
details: Every normative requirement has a permanent rule ID suitable for reviews and automated checks.
|
||||
---
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
layout: home
|
||||
title: SLM Design
|
||||
titleTemplate: false
|
||||
sidebar: false
|
||||
hero:
|
||||
name: Документация SLM Design
|
||||
text: Один портал для правил и практики
|
||||
tagline: Нормативная спецификация, реестр правил и будущий архитектурный гайд в единой структуре.
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Открыть спецификацию
|
||||
link: /ru/specification/
|
||||
- theme: alt
|
||||
text: Найти правило
|
||||
link: /ru/specification/rules
|
||||
features:
|
||||
- title: SLM Design Specification
|
||||
details: Нормативный источник архитектурных правил, ownership boundaries и требований соответствия.
|
||||
link: /ru/specification/
|
||||
linkText: Читать спецификацию
|
||||
- title: Реестр правил
|
||||
details: Все Base, Advanced и Pro rules с фильтрами, точными anchors и копируемыми permalink-ссылками.
|
||||
link: /ru/specification/rules
|
||||
linkText: Открыть реестр
|
||||
- title: Architecture Guide
|
||||
details: Будущий учебный материал для последовательного изучения и практического применения Specification.
|
||||
---
|
||||
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: Архитектурная модель
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Архитектурная Модель
|
||||
|
||||
## Структура приложения
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/
|
||||
├── compositions/
|
||||
├── infra/
|
||||
├── ui/
|
||||
└── shared/
|
||||
```
|
||||
|
||||
**SLM-BASE-ARCH-001 - ОБЯЗАН.** Base SLM-приложение должно разделять код по ответственности между слоями `app`, `compositions`, `infra`, `ui` и `shared`.
|
||||
|
||||
Не каждый слой обязан содержать код в минимальном приложении. Пустые папки и speculative scaffolding не требуются.
|
||||
|
||||
## Группы ответственности
|
||||
|
||||
| Группа | Слои | Ответственность |
|
||||
|---|---|---|
|
||||
| Framework composition | `app`, `compositions` | Подключение к framework и сборка application flows |
|
||||
| Product | Product owner; в base SLM - `compositions` | Product semantics, UI и flows владеющего module |
|
||||
| Technical | `infra`, `ui` | Technical capabilities и универсальный UI |
|
||||
| Foundation | `shared` | Детерминированный общий фундамент |
|
||||
|
||||
## Верхнеуровневое направление
|
||||
|
||||
```text
|
||||
app -> compositions | shared
|
||||
compositions -> compositions | infra | ui | shared
|
||||
infra -> infra | shared
|
||||
ui -> ui | shared
|
||||
shared -/-> остальные SLM-слои
|
||||
```
|
||||
|
||||
Framework APIs и external packages регулируются ответственностью импортирующего слоя и не показаны как SLM-слои.
|
||||
|
||||
**SLM-BASE-ARCH-002 - ОБЯЗАН.** Верхнеуровневое направление зависимостей между base SLM-слоями должно соблюдаться для runtime imports и type imports, кроме явно описанных исключений.
|
||||
|
||||
**SLM-BASE-ARCH-003 - ЗАПРЕЩЕНО.** Нижний слой не может импортировать `app` или `compositions`.
|
||||
|
||||
**SLM-BASE-ARCH-004 - ЗАПРЕЩЕНО.** `infra`, `ui` и `shared` не могут владеть product wiring или выступать service locator для application modules.
|
||||
|
||||
## Путь данных
|
||||
|
||||
```text
|
||||
app
|
||||
-> product owner public API
|
||||
-> infra public API
|
||||
-> external source
|
||||
```
|
||||
|
||||
**SLM-BASE-ARCH-005 - ОБЯЗАН.** Каждый переход product data должен сохранять ownership: framework связывает, product owner определяет semantics, а technical capability не присваивает себе product model.
|
||||
|
||||
## Путь UI
|
||||
|
||||
```text
|
||||
app route
|
||||
-> page/layout composition
|
||||
-> product UI
|
||||
-> universal UI
|
||||
-> shared styles/resources
|
||||
```
|
||||
|
||||
Product UI принадлежит product owner; в base SLM таким owner является composition. Универсальный product-agnostic UI принадлежит `ui`.
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
title: Архитектурные modes
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Архитектурные Modes
|
||||
|
||||
SLM является самостоятельной базовой архитектурой. Architecture mode - опциональный независимый overlay, который добавляет или явно заменяет отдельные правила base SLM.
|
||||
|
||||
```text
|
||||
SLM Advanced = SLM + Advanced rules
|
||||
SLM Pro = SLM + Pro rules
|
||||
```
|
||||
|
||||
`SLM Advanced` и `SLM Pro` не наследуют друг друга. Совпадающее требование декларируется отдельно внутри каждого overlay и не создаёт общей mode-ветки.
|
||||
|
||||
## Выбор архитектуры
|
||||
|
||||
Приложение использует один из трёх вариантов:
|
||||
|
||||
```text
|
||||
SLM
|
||||
SLM + Advanced
|
||||
SLM + Pro
|
||||
```
|
||||
|
||||
**SLM-BASE-MODE-001 - ОБЯЗАН.** Приложение должно зафиксировать использование base SLM и, при наличии, ровно одного overlay: `Advanced` или `Pro`.
|
||||
|
||||
**SLM-BASE-MODE-002 - ЗАПРЕЩЕНО.** Одно приложение не может одновременно заявлять соответствие `SLM Advanced` и `SLM Pro`.
|
||||
|
||||
**SLM-BASE-MODE-003 - ОБЯЗАН.** Выбранный overlay должен применяться ко всему приложению в пределах одной SLM application boundary.
|
||||
|
||||
Выбор выполняет команда на стадии планирования. Сигналами могут быть количество product responsibilities, связанность modules, runtime state, client/server execution, lifecycle risks и количество команд разработки. Фиксированные числовые пороги не устанавливаются.
|
||||
|
||||
| Вариант | Когда рассматривать |
|
||||
|---|---|
|
||||
| `SLM` | Product responsibilities удобно удерживать внутри compositions без дополнительного слоя |
|
||||
| `SLM Advanced` | Нужны самостоятельные domains, но команда хочет свободно выбирать их внутреннюю структуру и связи |
|
||||
| `SLM Pro` | Нужны изолированные domains, явные runtime contracts, adapters, lifecycle и усиленные checks |
|
||||
|
||||
## Применимость правил
|
||||
|
||||
Base-правило имеет идентификатор вида:
|
||||
|
||||
```text
|
||||
SLM-BASE-AREA-NNN
|
||||
```
|
||||
|
||||
Mode-specific правила имеют идентификаторы:
|
||||
|
||||
```text
|
||||
SLM-ADV-AREA-NNN
|
||||
SLM-PRO-AREA-NNN
|
||||
```
|
||||
|
||||
**SLM-BASE-MODE-004 - ОБЯЗАН.** Base-правила SLM применяются при любом выбранном варианте архитектуры. Если overlay явно заменяет base rule только в определённом scope, исходное base-правило продолжает действовать за пределами этого scope.
|
||||
|
||||
**SLM-BASE-MODE-005 - ОБЯЗАН.** Для `SLM Advanced` применяются только base-правила и правила из `modes/advanced`.
|
||||
|
||||
**SLM-BASE-MODE-006 - ОБЯЗАН.** Для `SLM Pro` применяются только base-правила и правила из `modes/pro`.
|
||||
|
||||
**SLM-BASE-MODE-007 - ЗАПРЕЩЕНО.** Правило другого overlay не может использоваться как обязательное требование, разрешение или исключение.
|
||||
|
||||
**SLM-BASE-MODE-008 - ОБЯЗАН.** Mode-specific правило, заменяющее base-поведение, должно явно назвать заменяемый base rule ID или нормативный раздел и точный scope замены.
|
||||
|
||||
## Независимые overlays
|
||||
|
||||
### SLM Advanced
|
||||
|
||||
[SLM Advanced](./modes/advanced/index.md) описывает полный Advanced-delta относительно base SLM.
|
||||
|
||||
### SLM Pro
|
||||
|
||||
[SLM Pro](./modes/pro/index.md) описывает полный Pro-delta относительно base SLM.
|
||||
|
||||
## Изменение overlay
|
||||
|
||||
**SLM-BASE-MODE-009 - МОЖЕТ.** Команда может подключить, заменить или удалить overlay при изменении требований к архитектуре.
|
||||
|
||||
**SLM-BASE-MODE-010 - ОБЯЗАН.** После изменения конфигурации приложение может заявлять соответствие только после выполнения применимых base-правил с учётом scoped replacements и, при наличии, полного rule set выбранного overlay.
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: Основные инварианты
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Основные Инварианты
|
||||
|
||||
SLM Design организует frontend-приложение по владельцам ответственности. Архитектурная единица определяется не типом файла, а тем, кто владеет моделью, поведением, данными, runtime и lifecycle.
|
||||
|
||||
## Ответственность до размещения
|
||||
|
||||
**SLM-BASE-FND-001 - ОБЯЗАН.** Перед размещением кода необходимо определить его владельца, public boundary, runtime dependencies и lifecycle scope.
|
||||
|
||||
**SLM-BASE-FND-002 - СЛЕДУЕТ.** Код следует размещать в минимальном scope, который полностью владеет его ответственностью.
|
||||
|
||||
**SLM-BASE-FND-003 - ЗАПРЕЩЕНО.** Нельзя переносить код в общий слой или общий package только на основании предполагаемого будущего переиспользования.
|
||||
|
||||
## Путь продуктовых данных
|
||||
|
||||
Product data проходят через public boundary текущего владельца согласно [SLM-BASE-DATA-001](./state-and-data.md#product-gateway). Внешний сервис может оставаться физическим источником данных, но transport contract не становится product model автоматически.
|
||||
|
||||
## Явные зависимости
|
||||
|
||||
**SLM-BASE-FND-007 - ОБЯЗАН.** Runtime capabilities должны поступать владельцу поведения через разрешённые imports, явные arguments или contracts, а не через скрытый service locator или global mutable state.
|
||||
|
||||
**SLM-BASE-FND-008 - ЗАПРЕЩЕНО.** Type cast, barrel, alias, dynamic import или helper в `shared` не могут использоваться для обхода применимой архитектурной границы.
|
||||
|
||||
## Public API
|
||||
|
||||
Межмодульное взаимодействие и deep imports регулируются [SLM-BASE-API-001 - SLM-BASE-API-005](./public-api-and-imports.md#общие-правила).
|
||||
|
||||
## Scope и lifecycle
|
||||
|
||||
Создание, scope, activation и cleanup применимых runtimes и resources определены в [Runtime и lifecycle](./runtime-and-lifecycle.md).
|
||||
|
||||
## Overlays
|
||||
|
||||
Base SLM не вводит дополнительные архитектурные слои и специализированные runtime contracts. Каждый overlay самостоятельно определяет свои добавления и замены base-правил.
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
title: SLM Design Specification
|
||||
version: 0.1.0-draft
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# SLM Design Specification
|
||||
|
||||
Эта директория содержит единый нормативный корпус SLM Design 2.0. Base SLM является законченной минимальной архитектурой; дополнительные ограничения подключаются независимыми overlays `SLM Advanced` или `SLM Pro`.
|
||||
|
||||
Пока статус равен `draft`, документы описывают проектируемую архитектуру и не заменяют действующую документацию в `old-docs/`.
|
||||
|
||||
## Нормативный язык
|
||||
|
||||
| Термин | Значение |
|
||||
|---|---|
|
||||
| `ОБЯЗАН` | Требование необходимо выполнить для соответствия спецификации |
|
||||
| `ЗАПРЕЩЕНО` | Действие является нарушением спецификации |
|
||||
| `СЛЕДУЕТ` | Рекомендуемое решение; отступление требует явного обоснования |
|
||||
| `МОЖЕТ` | Допустимый, но необязательный вариант |
|
||||
|
||||
Правила имеют стабильные идентификаторы. Base использует формат `SLM-BASE-AREA-NNN`, Advanced - `SLM-ADV-AREA-NNN`, Pro - `SLM-PRO-AREA-NNN`. Точное нормативное требование принадлежит только той главе, где объявлен его rule ID.
|
||||
|
||||
Все объявления доступны в [реестре правил](./rules.md). Для прямого перехода можно открыть поиск `Ctrl/⌘ K` и ввести полный rule ID.
|
||||
|
||||
## Architecture modes
|
||||
|
||||
Base SLM не требует overlay. Если команда выбирает дополнительную архитектурную политику, она подключает ровно один независимый mode согласно [Архитектурным modes](./architecture-modes.md):
|
||||
|
||||
```text
|
||||
SLM Advanced = SLM + Advanced rules
|
||||
SLM Pro = SLM + Pro rules
|
||||
```
|
||||
|
||||
## Приоритет
|
||||
|
||||
**SLM-BASE-DOC-001 - ОБЯЗАН.** При конфликте между главами спецификации и любым ненормативным материалом приоритет имеет спецификация.
|
||||
|
||||
**SLM-BASE-DOC-002 - ЗАПРЕЩЕНО.** Ненормативный документ не может вводить новое обязательное правило, исключение или архитектурную границу.
|
||||
|
||||
**SLM-BASE-DOC-003 - ОБЯЗАН.** Изменение принятого архитектурного правила должно вноситься в главу, которая владеет соответствующим rule ID.
|
||||
|
||||
## Base SLM
|
||||
|
||||
### Основы
|
||||
|
||||
- [Основные инварианты](./foundations.md)
|
||||
- [Терминология](./terminology.md)
|
||||
- [Архитектурная модель](./architecture-model.md)
|
||||
|
||||
### Слои
|
||||
|
||||
- [Обзор слоёв](./layers/index.md)
|
||||
- [App](./layers/app.md)
|
||||
- [Compositions](./layers/compositions.md)
|
||||
- [Infra](./layers/infra.md)
|
||||
- [UI](./layers/ui.md)
|
||||
- [Shared](./layers/shared.md)
|
||||
|
||||
### Общие правила
|
||||
|
||||
- [Модули и группы](./modules-and-groups.md)
|
||||
- [Сегменты](./segments.md)
|
||||
- [Public API и импорты](./public-api-and-imports.md)
|
||||
- [State и data](./state-and-data.md)
|
||||
- [Runtime и lifecycle](./runtime-and-lifecycle.md)
|
||||
- [Тестирование и соответствие](./testing-and-conformance.md)
|
||||
- [Монорепозитории](./monorepo.md)
|
||||
|
||||
## Overlays
|
||||
|
||||
### SLM Advanced
|
||||
|
||||
- [Отличия Advanced от base SLM](./modes/advanced/index.md)
|
||||
- [Domains в SLM Advanced](./modes/advanced/domains.md)
|
||||
|
||||
### SLM Pro
|
||||
|
||||
- [Отличия Pro от base SLM](./modes/pro/index.md)
|
||||
- [Domains в SLM Pro](./modes/pro/domains/index.md)
|
||||
- [Business](./modes/pro/domains/business.md)
|
||||
- [Framework surface](./modes/pro/domains/framework.md)
|
||||
- [Ports и adapters](./modes/pro/domains/ports-and-adapters.md)
|
||||
- [Client и server assembly](./modes/pro/domains/client-and-server.md)
|
||||
- [Cross-domain boundary](./modes/pro/domains/cross-domain-boundary.md)
|
||||
- [Тестирование Pro domains](./modes/pro/domains/testing.md)
|
||||
|
||||
## Область текущего draft
|
||||
|
||||
Base SLM фиксирует ownership, пять основных слоёв, public boundaries, state и lifecycle. Текущие версии Advanced и Pro в первую очередь определяют собственные независимые модели слоя `domains`; будущие mode-specific правила могут относиться к любому разделу архитектуры.
|
||||
|
||||
Точная форма React Providers, окончательная политика package extraction и единая модель query cache не фиксируются сверх явно объявленных инвариантов base или выбранного overlay.
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
title: Слой App
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Слой App
|
||||
|
||||
`app` является boundary между framework routing/runtime и SLM-модулями приложения.
|
||||
|
||||
## Ответственность
|
||||
|
||||
`app` может содержать:
|
||||
|
||||
- route files;
|
||||
- framework layout/error/loading/not-found entries;
|
||||
- framework metadata и route parameters;
|
||||
- bootstrap imports;
|
||||
- подключение global styles/assets;
|
||||
- framework-required middleware и handlers.
|
||||
|
||||
## Правила
|
||||
|
||||
**SLM-BASE-APP-001 - ОБЯЗАН.** Route entry должен оставаться тонким adapter, нормализующим framework input и делегирующим готовому composition module.
|
||||
|
||||
```text
|
||||
framework route
|
||||
→ composition entry
|
||||
```
|
||||
|
||||
**SLM-BASE-APP-002 - ЗАПРЕЩЕНО.** `app` не может владеть product page, screen, widget, product scenario, store или application wiring.
|
||||
|
||||
**SLM-BASE-APP-003 - ЗАПРЕЩЕНО.** Route entry не должен напрямую собирать product integrations, вызывать SDK или формировать product model.
|
||||
|
||||
**SLM-BASE-APP-004 - ОБЯЗАН.** Framework-specific input должен быть считан в `app` и передан вниз в минимальной нормализованной форме.
|
||||
|
||||
Механическая нормализация включает извлечение route params, headers и framework wrappers. Product validation, создание value objects и выбор product outcome остаются у владельца product semantics.
|
||||
|
||||
Запрет другим SLM-слоям импортировать `app` определяется base-правилом `SLM-BASE-ARCH-003`.
|
||||
|
||||
**SLM-BASE-APP-006 - СЛЕДУЕТ.** Framework behavior, которому нужны product dependencies или product UI, следует реализовать готовым composition entry и только подключить из `app`.
|
||||
|
||||
**SLM-BASE-APP-007 - МОЖЕТ.** `app` может напрямую импортировать framework APIs и static/global resources из `shared`, если framework требует подключить их в root entry.
|
||||
|
||||
## Допустимая структура
|
||||
|
||||
Структуру `app` определяет framework. SLM не требует превращать framework directories в SLM modules и не требует `index.ts` для route folders.
|
||||
|
||||
```text
|
||||
app/
|
||||
├── layout.tsx
|
||||
├── error.tsx
|
||||
├── not-found.tsx
|
||||
├── api/
|
||||
└── products/
|
||||
└── [product]/
|
||||
└── page.tsx
|
||||
```
|
||||
|
||||
## Примеры нарушений
|
||||
|
||||
Следующие сущности являются примерами нарушений `SLM-BASE-APP-002` и `SLM-BASE-APP-003`:
|
||||
|
||||
- `ProductPage`;
|
||||
- product Provider;
|
||||
- application service creator;
|
||||
- page-local store;
|
||||
- product mapper;
|
||||
- reusable product component;
|
||||
- concrete product integration.
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
title: Слой Compositions
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Слой Compositions
|
||||
|
||||
`compositions` собирает application flows из module public APIs, technical capabilities и UI modules и может владеть product logic в пределах своей ответственности.
|
||||
|
||||
## Ответственность
|
||||
|
||||
Composition может быть:
|
||||
|
||||
- page;
|
||||
- route composition entry;
|
||||
- layout;
|
||||
- screen;
|
||||
- widget;
|
||||
- provider composition;
|
||||
- multi-module hook;
|
||||
- non-visual application wiring owner.
|
||||
|
||||
Структура слоя свободна и отражает продуктовую навигацию приложения.
|
||||
|
||||
```text
|
||||
compositions/
|
||||
├── pages/
|
||||
├── layouts/
|
||||
├── screens/
|
||||
├── widgets/
|
||||
└── providers/
|
||||
```
|
||||
|
||||
Эти папки являются groups, а не отдельными слоями.
|
||||
|
||||
## Product ownership
|
||||
|
||||
**SLM-BASE-CMP-001 - ОБЯЗАН.** Product flow и его локальная product logic должны принадлежать минимальной composition, охватывающей всех consumers этой ответственности.
|
||||
|
||||
Composition может использовать public API `infra` для external operations, сохраняя product mapping, outcomes и fallback semantics у себя.
|
||||
|
||||
## Public boundaries
|
||||
|
||||
**SLM-BASE-CMP-005 - ЗАПРЕЩЕНО.** Composition не может импортировать private services, integrations, stores, Context или другие internal paths используемого module.
|
||||
|
||||
## Product UI
|
||||
|
||||
**SLM-BASE-CMP-006 - ОБЯЗАН.** UI, объединяющий несколько самостоятельных modules, route/page scope либо application flow, принадлежит `compositions`.
|
||||
|
||||
Примеры:
|
||||
|
||||
- application header;
|
||||
- order flow, объединяющий несколько product responsibilities;
|
||||
- page screen;
|
||||
- route guard с navigation outcome;
|
||||
- widget, использующий public APIs двух самостоятельных modules.
|
||||
|
||||
**SLM-BASE-CMP-007 - МОЖЕТ.** Composition может использовать product UI, опубликованный другими modules, и universal UI, передавая props, callbacks и slots.
|
||||
|
||||
## State
|
||||
|
||||
**SLM-BASE-CMP-008 - ОБЯЗАН.** Page-local presentation state принадлежит минимальной composition, охватывающей всех его consumers.
|
||||
|
||||
Примеры page-local state:
|
||||
|
||||
- открытие sidebar;
|
||||
- активная вкладка;
|
||||
- route-local wizard step;
|
||||
- presentation filters;
|
||||
- состояние раскрытия section.
|
||||
|
||||
**SLM-BASE-CMP-009 - ЗАПРЕЩЕНО.** Page store не может становиться параллельным владельцем product model или canonical product cache другого owner.
|
||||
|
||||
## Imports
|
||||
|
||||
**SLM-BASE-CMP-010 - МОЖЕТ.** Composition module может импортировать public API других composition modules, infra, ui и shared.
|
||||
|
||||
Runtime-циклы между composition modules запрещены base-правилом `SLM-BASE-API-016`.
|
||||
|
||||
**SLM-BASE-CMP-015 - ОБЯЗАН.** Client и server composition entries должны иметь раздельные public entrypoints и environment markers, если composition участвует в обоих runtime graphs.
|
||||
|
||||
## Scope
|
||||
|
||||
Composition может владеть application, route, page, request или test scope. Выбор scope должен следовать правилам [runtime и lifecycle](../runtime-and-lifecycle.md).
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: Слои
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Слои
|
||||
|
||||
Слой определяет вид ответственности, допустимые зависимости и типы modules внутри верхнеуровневой папки `src`.
|
||||
|
||||
## Матрица ответственности
|
||||
|
||||
| Слой | Владеет | Не владеет |
|
||||
|---|---|---|
|
||||
| [`app`](./app.md) | Framework routes, bootstrap, глобальные framework boundaries | Product UI, product logic, page state, application wiring |
|
||||
| [`compositions`](./compositions.md) | Pages, layouts, screens, widgets, product flows, application wiring и scope | Universal UI primitives, technical transports |
|
||||
| [`infra`](./infra.md) | Technical services, transports, platform integrations | Product semantics и application wiring |
|
||||
| [`ui`](./ui.md) | Product-agnostic UI modules | Product scenarios и data sources |
|
||||
| [`shared`](./shared.md) | Детерминированные общие resources | Runtime state, I/O и product knowledge |
|
||||
|
||||
## Общие правила
|
||||
|
||||
**SLM-BASE-LAY-001 - ОБЯЗАН.** Module должен располагаться в слое, который владеет его основной ответственностью.
|
||||
|
||||
**SLM-BASE-LAY-002 - ЗАПРЕЩЕНО.** Нельзя выбирать слой по техническому типу файла без определения владельца поведения и данных.
|
||||
|
||||
**SLM-BASE-LAY-003 - ОБЯЗАН.** Межслойный import должен одновременно соответствовать общей dependency direction и public API импортируемого module.
|
||||
|
||||
**SLM-BASE-LAY-004 - ЗАПРЕЩЕНО.** Нельзя создавать proxy module в разрешённом слое только для обхода запрещённого направления import.
|
||||
|
||||
**SLM-BASE-LAY-005 - СЛЕДУЕТ.** При смешанной ответственности module следует разделить по реальным владельцам. Application flow и UI нескольких самостоятельных modules следует собирать в `compositions`.
|
||||
|
||||
## Выбор слоя
|
||||
|
||||
| Вопрос | Слой |
|
||||
|---|---|
|
||||
| Код существует только из-за framework route/bootstrap? | `app` |
|
||||
| Код собирает page, route или несколько самостоятельных modules? | `compositions` |
|
||||
| Код выражает product flow или product responsibility без owner, введённого overlay? | `compositions` |
|
||||
| Код предоставляет technical capability приложения? | `infra` |
|
||||
| Компонент не содержит product semantics и scenario? | `ui` |
|
||||
| Код детерминирован, не знает продукт и не имеет runtime state? | `shared` |
|
||||
|
||||
Overlay может добавлять собственный слой и изменять ownership только в явно объявленном delta.
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
title: Слой Infra
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Слой Infra
|
||||
|
||||
`infra` содержит technical capabilities приложения, не определяющие product model и scenarios.
|
||||
|
||||
## Примеры modules
|
||||
|
||||
```text
|
||||
infra/
|
||||
├── http/
|
||||
├── backend-api/
|
||||
├── realtime/
|
||||
├── analytics/
|
||||
├── logger/
|
||||
├── app-config/
|
||||
├── storage/
|
||||
├── i18n/
|
||||
└── theme/
|
||||
```
|
||||
|
||||
## Правила
|
||||
|
||||
**SLM-BASE-INF-001 - ОБЯЗАН.** Infra module должен описывать technical capability, а не product semantics или scenario.
|
||||
|
||||
**SLM-BASE-INF-002 - МОЖЕТ.** Infra module может импортировать public API другого infra module и `shared`.
|
||||
|
||||
Запрет infra импортировать `compositions` или `app` определяется base-правилом `SLM-BASE-ARCH-003`.
|
||||
|
||||
**SLM-BASE-INF-004 - ЗАПРЕЩЕНО.** Infra не может владеть product wiring, собирать application graph или предоставлять generic product service locator.
|
||||
|
||||
**SLM-BASE-INF-005 - ЗАПРЕЩЕНО.** Infra не создаёт product errors, product fallback и product model из transport DTO.
|
||||
|
||||
**SLM-BASE-INF-006 - МОЖЕТ.** Infra может экспортировать technical client, transport, event source, storage primitive или platform wrapper через собственный public API.
|
||||
|
||||
**SLM-BASE-INF-007 - ОБЯЗАН.** Generated SDK и transport details должны оставаться внутри technical или private integration boundary владельца и не становиться частью public product contract.
|
||||
|
||||
## Product integration
|
||||
|
||||
Infra знает technical mechanism:
|
||||
|
||||
```text
|
||||
HTTP client
|
||||
WebSocket transport
|
||||
local storage primitive
|
||||
analytics SDK
|
||||
```
|
||||
|
||||
Product owner определяет semantics использования capability; infra предоставляет механизм через public API. Один infra module может использоваться несколькими product owners без знания их semantics.
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
title: Слой Shared
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Слой Shared
|
||||
|
||||
`shared` является детерминированным фундаментом приложения и не знает о SLM-модулях верхних слоёв.
|
||||
|
||||
## Допустимое содержимое
|
||||
|
||||
- pure utilities;
|
||||
- value predicates;
|
||||
- product-agnostic types;
|
||||
- styling foundation и tokens;
|
||||
- static resources;
|
||||
- compile-time constants без product ownership;
|
||||
- deterministic formatting primitives.
|
||||
|
||||
## Правила
|
||||
|
||||
**SLM-BASE-SHR-001 - ОБЯЗАН.** Результат shared utility должен определяться явными аргументами и не зависеть от скрытого runtime environment.
|
||||
|
||||
**SLM-BASE-SHR-002 - ЗАПРЕЩЕНО.** `shared` не может импортировать `app`, `compositions`, `infra` или `ui`.
|
||||
|
||||
**SLM-BASE-SHR-003 - ЗАПРЕЩЕНО.** `shared` не может владеть product types, product rules, runtime state, I/O, storage access или event subscriptions.
|
||||
|
||||
**SLM-BASE-SHR-004 - ЗАПРЕЩЕНО.** Нельзя переносить product helper, DTO, integration contract или product config в `shared` для обхода import boundary.
|
||||
|
||||
**SLM-BASE-SHR-005 - СЛЕДУЕТ.** Код следует поднимать в `shared` только при подтверждённой product-agnostic semantics, а не из-за повторения нескольких строк.
|
||||
|
||||
## Отличие от других слоёв
|
||||
|
||||
| Код | Владелец |
|
||||
|---|---|
|
||||
| Email validator с product rules | Владеющий product module |
|
||||
| Generic string trim utility | `shared` |
|
||||
| Browser storage wrapper | `infra` |
|
||||
| Product storage integration | Product owner; storage primitive - `infra` |
|
||||
| UI spacing tokens | `shared` |
|
||||
| Button consuming spacing tokens | `ui` |
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: Слой UI
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Слой UI
|
||||
|
||||
`ui` содержит reusable presentation modules без product scenario и product ownership.
|
||||
|
||||
## Примеры
|
||||
|
||||
```text
|
||||
ui/
|
||||
├── button/
|
||||
├── input/
|
||||
├── icon/
|
||||
├── modal/
|
||||
├── carousel/
|
||||
├── tabs/
|
||||
└── tooltip/
|
||||
```
|
||||
|
||||
## Правила
|
||||
|
||||
**SLM-BASE-UI-001 - ОБЯЗАН.** UI module должен быть применим без product-specific knowledge.
|
||||
|
||||
**SLM-BASE-UI-002 - ЗАПРЕЩЕНО.** UI module не может импортировать `compositions`, `app` или product-specific infra.
|
||||
|
||||
**SLM-BASE-UI-003 - МОЖЕТ.** UI module может импортировать public API других UI modules и `shared`.
|
||||
|
||||
**SLM-BASE-UI-004 - ЗАПРЕЩЕНО.** UI module не выбирает product data source, не вызывает product scenario и не владеет multi-module behavior.
|
||||
|
||||
**SLM-BASE-UI-005 - МОЖЕТ.** UI module может владеть локальным interaction state, необходимым только для собственной presentation mechanics.
|
||||
|
||||
**SLM-BASE-UI-006 - ОБЯЗАН.** Компонент с product semantics должен принадлежать владеющему product module, а не `ui`.
|
||||
|
||||
## Классификация
|
||||
|
||||
| Сущность | Владелец |
|
||||
|---|---|
|
||||
| `Button`, `Input`, `Modal` | `ui` |
|
||||
| `LoginForm` одной auth responsibility | Владеющий product module |
|
||||
| Application header | `compositions` |
|
||||
| Generic date picker | `ui` |
|
||||
| Medication schedule | Владеющий product module согласно ownership |
|
||||
|
||||
Универсальность определяется отсутствием product knowledge, а не количеством текущих consumers.
|
||||
@@ -1,122 +0,0 @@
|
||||
---
|
||||
title: Domains в SLM Advanced
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: advanced
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Domains в SLM Advanced
|
||||
|
||||
> Overlay: `SLM Advanced`. Base: [SLM](../../index.md).
|
||||
|
||||
Domain является законченным вертикальным product module с одной предметной ответственностью и явным public boundary. Кроме base-правил modules и segments, Advanced не предписывает обязательную внутреннюю архитектуру domain.
|
||||
|
||||
## Domain и group
|
||||
|
||||
**SLM-ADV-DOM-001 - ОБЯЗАН.** Конечный domain должен располагаться непосредственно в `domains` или внутри одной или нескольких навигационных groups.
|
||||
|
||||
```text
|
||||
domains/{domain}
|
||||
domains/{group}/{domain}
|
||||
domains/{group}/{nested-group}/{domain}
|
||||
```
|
||||
|
||||
**SLM-ADV-DOM-002 - ОБЯЗАН.** Узел domain tree с собственным public API, state, integration или runtime должен классифицироваться как конечный domain, а не domain group.
|
||||
|
||||
```text
|
||||
domains/
|
||||
├── navigation/ # domain
|
||||
└── knv/ # group
|
||||
├── auth/ # domain
|
||||
├── user/ # domain
|
||||
└── orders/ # domain
|
||||
```
|
||||
|
||||
**SLM-ADV-DOM-003 - ОБЯЗАН.** Первой архитектурной единицей в group tree является конечная папка, владеющая самостоятельной product responsibility.
|
||||
|
||||
## Ownership
|
||||
|
||||
**SLM-ADV-DOM-004 - ОБЯЗАН.** Domain должен владеть одной сформулированной product responsibility и предоставлять её внешним consumers через собственный public API.
|
||||
|
||||
Domain может владеть:
|
||||
|
||||
- product model и value objects;
|
||||
- scenarios и operations;
|
||||
- domain state и transitions;
|
||||
- normalization и product errors;
|
||||
- product source integration;
|
||||
- framework hooks и UI одного domain;
|
||||
- runtime-specific setup.
|
||||
|
||||
**SLM-ADV-DOM-005 - ЗАПРЕЩЕНО.** Domain не может владеть framework route entry, page/layout composition, UI нескольких самостоятельных product responsibilities, universal technical capability или product-agnostic UI primitive.
|
||||
|
||||
## Структура
|
||||
|
||||
```text
|
||||
domains/knv/auth/
|
||||
├── hooks/
|
||||
├── providers/
|
||||
├── services/
|
||||
├── stores/
|
||||
├── mappers/
|
||||
├── types/
|
||||
├── ui/
|
||||
├── parts/
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Это пример, а не обязательный scaffold. Небольшой domain может состоять из одного файла и public entrypoint.
|
||||
|
||||
Domain может хранить файлы в корне и использовать любые необходимые segments согласно base-правилам [SLM-BASE-SEG-001 - SLM-BASE-SEG-003](../../segments.md#правила).
|
||||
|
||||
**SLM-ADV-DOM-006 - ЗАПРЕЩЕНО.** Нельзя создавать пустые segments или копировать полную структуру другого domain без текущей ответственности.
|
||||
|
||||
**SLM-ADV-DOM-007 - МОЖЕТ.** Domain может владеть hooks, Providers, Context, services, stores, mappers, types, product UI и другими implementation units своей ответственности.
|
||||
|
||||
## Public API
|
||||
|
||||
Public boundary Advanced domain следует base-правилам `SLM-BASE-API-001` и `SLM-BASE-API-002`.
|
||||
|
||||
**SLM-ADV-DOM-009 - МОЖЕТ.** Public API domain может экспортировать выбранные командой hooks, Providers, Context, components, service APIs, store access APIs и types как стабильный contract.
|
||||
|
||||
**SLM-ADV-DOM-010 - ЗАПРЕЩЕНО.** Если product responsibility получила domain owner, app, composition или infra не могут создавать параллельную модель этой ответственности либо обходить её public boundary.
|
||||
|
||||
## Dependencies
|
||||
|
||||
```text
|
||||
composition -> domain
|
||||
domain -> domain | infra | ui | shared
|
||||
```
|
||||
|
||||
**SLM-ADV-DOM-011 - МОЖЕТ.** Domain может runtime-импортировать public API другого Advanced domain.
|
||||
|
||||
**SLM-ADV-DOM-012 - МОЖЕТ.** Domain может напрямую использовать public API `infra`, `ui` и `shared` без обязательной промежуточной abstraction.
|
||||
|
||||
Runtime cycles запрещены base-правилом `SLM-BASE-API-016`.
|
||||
|
||||
**SLM-ADV-DOM-013 - ЗАПРЕЩЕНО.** Type-only dependency cycle между domains запрещён, даже если runtime graph остаётся ацикличным.
|
||||
|
||||
## Data flow
|
||||
|
||||
```text
|
||||
composition
|
||||
-> domain public API
|
||||
-> domain hook/service
|
||||
-> infra
|
||||
-> external source
|
||||
```
|
||||
|
||||
**SLM-ADV-DOM-014 - ОБЯЗАН.** Product consumers за пределами domain должны получать его данные и поведение через public API domain, а не повторять тот же integration flow напрямую через `infra`.
|
||||
|
||||
## Product UI
|
||||
|
||||
**SLM-ADV-DOM-015 - МОЖЕТ.** Product UI одной domain responsibility может принадлежать этому domain.
|
||||
|
||||
UI нескольких самостоятельных responsibilities остаётся в `compositions` согласно base-правилу `SLM-BASE-CMP-006`.
|
||||
|
||||
## Monorepo boundary
|
||||
|
||||
**SLM-ADV-DOM-016 - ОБЯЗАН.** Advanced domain должен оставаться внутри `apps/{app}/src/domains` до принятия отдельной package-модели.
|
||||
|
||||
**SLM-ADV-DOM-017 - ЗАПРЕЩЕНО.** Workspace package не может называться Advanced Domain для целей Specification, если он не соответствует application path и ownership этой главы.
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
title: SLM Advanced
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: advanced
|
||||
base: slm
|
||||
---
|
||||
|
||||
# SLM Advanced
|
||||
|
||||
`SLM Advanced` является независимым overlay непосредственно над [base SLM](../../index.md).
|
||||
|
||||
```text
|
||||
SLM Advanced = SLM + Advanced rules
|
||||
```
|
||||
|
||||
## Отличия от SLM
|
||||
|
||||
| Область | Base SLM | SLM Advanced |
|
||||
|---|---|---|
|
||||
| Product ownership | Product logic принадлежит compositions | Устойчивая product responsibility может быть извлечена в domain |
|
||||
| Слои | `app`, `compositions`, `infra`, `ui`, `shared` | Добавляется `domains` |
|
||||
| Структура domain | Отсутствует | Свободная, внутренние роли выбирает команда |
|
||||
| Domain dependencies | Отсутствуют | Ацикличные imports через public API разрешены |
|
||||
| External integration | Composition использует infra | Domain может использовать infra напрямую |
|
||||
|
||||
## Расширение архитектурной модели
|
||||
|
||||
**SLM-ADV-ARCH-001 - ОБЯЗАН.** SLM Advanced должен расширять набор base-слоёв слоем `domains` для самостоятельных product responsibilities.
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/
|
||||
├── compositions/
|
||||
├── domains/
|
||||
├── infra/
|
||||
├── ui/
|
||||
└── shared/
|
||||
```
|
||||
|
||||
**SLM-ADV-ARCH-002 - ОБЯЗАН.** Дополнительные dependency edges Advanced должны соответствовать следующему направлению:
|
||||
|
||||
```text
|
||||
compositions -> domains
|
||||
domains -> domains | infra | ui | shared
|
||||
```
|
||||
|
||||
Base dependency direction для остальных слоёв сохраняется.
|
||||
|
||||
## Изменение product ownership
|
||||
|
||||
**SLM-ADV-CMP-001 - ОБЯЗАН.** Если product responsibility получила domain owner, Advanced заменяет для этой ответственности base-правило `SLM-BASE-CMP-001`: domain владеет собственной product logic, а composition владеет application flow и связывает public APIs.
|
||||
|
||||
Product logic без domain owner продолжает следовать base SLM и принадлежит минимальной composition.
|
||||
|
||||
**SLM-ADV-CMP-010 - МОЖЕТ.** Composition module может импортировать public API Advanced domains в дополнение к imports, разрешённым base-правилом `SLM-BASE-CMP-010`.
|
||||
|
||||
## Advanced Domain Specification
|
||||
|
||||
Полная Advanced-модель слоя описана в [Domains](./domains.md). Других mode-specific отличий текущий draft Advanced не вводит.
|
||||
@@ -1,130 +0,0 @@
|
||||
---
|
||||
title: Business в SLM Pro
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Business
|
||||
|
||||
> Overlay: `SLM Pro`.
|
||||
|
||||
`business` является framework-neutral зоной domain и единственным владельцем его продуктовой semantics.
|
||||
|
||||
## Структура
|
||||
|
||||
```text
|
||||
domains/{group...}/{domain}/business/
|
||||
├── {domain}.factory.ts
|
||||
├── index.ts
|
||||
├── types/
|
||||
├── ports/
|
||||
├── services/
|
||||
├── errors/
|
||||
├── mappers/
|
||||
├── selectors/
|
||||
├── validators/
|
||||
└── lib/
|
||||
```
|
||||
|
||||
Конкретный набор внутренних segments определяется размером domain. Обязательны роль factory и public boundary, но не каждая папка из примера.
|
||||
|
||||
## Factory boundary
|
||||
|
||||
**SLM-PRO-BUS-001 - ОБЯЗАН.** Business должен создавать public runtime API через factory `{domain}Factory`.
|
||||
|
||||
**SLM-PRO-BUS-002 - ОБЯЗАН.** Factory должна принимать все runtime capabilities через business-owned dependency contracts.
|
||||
|
||||
**SLM-PRO-BUS-003 - ОБЯЗАН.** Factory должна возвращать framework-neutral DomainRuntime. Stateless logic API считается DomainRuntime и соблюдает тот же public boundary.
|
||||
|
||||
**SLM-PRO-BUS-004 - ЗАПРЕЩЕНО.** Factory не может возвращать React hooks, components, Providers, layouts, route guards или framework boundaries.
|
||||
|
||||
**SLM-PRO-BUS-005 - ЗАПРЕЩЕНО.** Factory constructor не может выполнять I/O, открывать socket, регистрировать subscription, запускать timer или читать hidden environment.
|
||||
|
||||
## Public API
|
||||
|
||||
**SLM-PRO-BUS-006 - ОБЯЗАН.** `business/index.ts` должен экспортировать единственное runtime value: factory.
|
||||
|
||||
**SLM-PRO-BUS-007 - МОЖЕТ.** `business/index.ts` может экспортировать business-owned types через `export type`.
|
||||
|
||||
```ts
|
||||
export { authFactory } from './auth.factory'
|
||||
|
||||
export type {
|
||||
AuthDeps,
|
||||
AuthFactory,
|
||||
AuthRuntime,
|
||||
AuthState,
|
||||
} from './types'
|
||||
```
|
||||
|
||||
**SLM-PRO-BUS-008 - ЗАПРЕЩЕНО.** Error classes, error guards, error code constants, selectors, validators, formatters, services, mappers и port implementations не экспортируются как отдельные runtime values.
|
||||
|
||||
Если внешнему consumer нужна такая capability, она должна быть осмысленной частью factory runtime API, а не обходным direct export.
|
||||
|
||||
## Runtime API
|
||||
|
||||
DomainRuntime может предоставлять:
|
||||
|
||||
- commands;
|
||||
- imperative queries;
|
||||
- snapshots;
|
||||
- subscriptions;
|
||||
- selectors через стабильные methods;
|
||||
- validation operations;
|
||||
- typed outcomes;
|
||||
- explicit lifecycle operations.
|
||||
|
||||
**SLM-PRO-BUS-009 - ОБЯЗАН.** Runtime API должен говорить на языке domain и не повторять endpoint names, SDK tree или storage schema.
|
||||
|
||||
**SLM-PRO-BUS-010 - ЗАПРЕЩЕНО.** Public contract не может раскрывать generated DTO, SDK client, query-library result, concrete store API, raw Context или adapter.
|
||||
|
||||
## Dependencies и ports
|
||||
|
||||
**SLM-PRO-BUS-011 - ОБЯЗАН.** Business-owned dependency описывает минимальную внешнюю возможность на языке domain.
|
||||
|
||||
```ts
|
||||
export type AuthPhonePort = {
|
||||
requestCode: (phone: string) => Promise<unknown>
|
||||
verifyCode: (input: VerifyPhoneCodeInput) => Promise<unknown>
|
||||
}
|
||||
```
|
||||
|
||||
**SLM-PRO-BUS-012 - ОБЯЗАН.** Ненадёжный внешний результат должен приниматься как `unknown`, если business обязан проверить его runtime-форму.
|
||||
|
||||
**SLM-PRO-BUS-013 - ЗАПРЕЩЕНО.** Business dependency не может быть generated DTO, полный SDK client, `StoreApi`, QueryClient или framework hook.
|
||||
|
||||
**SLM-PRO-BUS-014 - ОБЯЗАН.** Subscription port должен предоставлять cleanup contract.
|
||||
|
||||
## Imports
|
||||
|
||||
Business может runtime-импортировать:
|
||||
|
||||
- собственные файлы;
|
||||
- детерминированный `shared`;
|
||||
- pure libraries без I/O, hidden state и public type leakage.
|
||||
|
||||
Business может type-only импортировать стабильный public contract другого domain, если dependency невозможно корректно описать локальным port. Локальный consumer-owned port является предпочтительным вариантом.
|
||||
|
||||
**SLM-PRO-BUS-015 - ЗАПРЕЩЕНО.** Business не импортирует React, query runtime, state manager, SDK, generated operation, HTTP client, storage implementation, browser API, infra, composition или assembly.
|
||||
|
||||
Cross-domain imports дополнительно регулируются правилами `SLM-PRO-XDOM-*` в [Cross-domain boundary](./cross-domain-boundary.md).
|
||||
|
||||
## Normalization и errors
|
||||
|
||||
**SLM-PRO-BUS-017 - ОБЯЗАН.** External result должен быть нормализован в business-owned model до выхода из DomainRuntime.
|
||||
|
||||
**SLM-PRO-BUS-018 - ОБЯЗАН.** Malformed successful response должен считаться нарушением runtime contract, а не валидным отсутствием данных.
|
||||
|
||||
**SLM-PRO-BUS-019 - ОБЯЗАН.** Expected domain outcome и technical failure должны быть различимы в public contract.
|
||||
|
||||
**SLM-PRO-BUS-020 - ЗАПРЕЩЕНО.** Source error, HTTP status, SDK error class, raw response и transport message не могут быть consumer contract.
|
||||
|
||||
Business может выражать ожидаемые outcomes через typed result или domain error. Эта draft-версия не предписывает единственную форму обработки ожидаемых ошибок, но требует business-owned semantics и стабильных discriminants.
|
||||
|
||||
## State
|
||||
|
||||
**SLM-PRO-BUS-021 - ОБЯЗАН.** Business владеет domain state model, допустимыми transitions и semantics commands/selectors.
|
||||
|
||||
Framework-neutral state runtime может быть создан самой factory или предоставлен через business-owned port. Concrete store implementation остаётся запрещённой dependency по [SLM-PRO-BUS-015](#imports) и не раскрывается в public API.
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: Client и server assembly в SLM Pro
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Client и Server Assembly
|
||||
|
||||
> Overlay: `SLM Pro`.
|
||||
|
||||
`client` и `server` создают готовые runtime-specific instances одного domain поверх его business factory и adapters.
|
||||
|
||||
## Client assembly
|
||||
|
||||
```text
|
||||
domains/{group...}/{domain}/client/
|
||||
├── create-{domain}-client-runtime.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
```ts
|
||||
export const createAuthClientRuntime = (): AuthRuntime => {
|
||||
return authFactory({
|
||||
phoneAuth: browserPhoneAuthAdapter,
|
||||
session: browserSessionAdapter,
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
Client technical inputs ограничены client environment/config и platform capabilities, необходимыми для создания adapters собственного domain. Runtime values другого domain technical input не являются.
|
||||
|
||||
**SLM-PRO-ASM-001 - ОБЯЗАН.** Runtime imports client assembly должны ограничиваться собственной business factory, собственными client adapters, собственной React surface и необходимыми client technical inputs. Type-only foreign contracts допускаются по [SLM-PRO-XDOM-005](./cross-domain-boundary.md#type-only-contracts).
|
||||
|
||||
**SLM-PRO-ASM-002 - ОБЯЗАН.** Client assembly должна возвращать готовый runtime собственного domain.
|
||||
|
||||
Запрет на foreign runtime values определяется правилом [SLM-PRO-XDOM-001](./cross-domain-boundary.md#runtime-imports).
|
||||
|
||||
**SLM-PRO-ASM-004 - МОЖЕТ.** Client или server assembly может принимать готовую внешнюю capability через собственный input contract.
|
||||
|
||||
```ts
|
||||
createUserClientRuntime({ auth: auth.session })
|
||||
```
|
||||
|
||||
Такой input не даёт user domain права создавать AuthRuntime или импортировать его client entrypoint.
|
||||
|
||||
## Server assembly
|
||||
|
||||
```text
|
||||
domains/{group...}/{domain}/server/
|
||||
├── create-{domain}-server-runtime.ts
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Server technical inputs ограничены request/framework data, server environment/config и platform capabilities, необходимыми для создания server adapters собственного domain. Runtime values другого domain technical input не являются.
|
||||
|
||||
**SLM-PRO-ASM-005 - ОБЯЗАН.** Server assembly должна создавать новый runtime в scope, соответствующем request или другой явно выбранной server lifetime.
|
||||
|
||||
**SLM-PRO-ASM-006 - ЗАПРЕЩЕНО.** Server assembly не может повторно использовать adapter или runtime instance, захвативший request credentials, cookies, headers или user-specific state другого scope.
|
||||
|
||||
**SLM-PRO-ASM-007 - ОБЯЗАН.** Framework/request input используется только для создания server adapters и не протекает как raw framework object в business API.
|
||||
|
||||
**SLM-PRO-ASM-008 - ОБЯЗАН.** Server entrypoint должен иметь явный server-only marker, если framework предоставляет такой механизм.
|
||||
|
||||
**SLM-PRO-ASM-016 - ОБЯЗАН.** Runtime imports server assembly должны ограничиваться собственной business factory, собственными server adapters и необходимыми server technical inputs; runtime import React/client surface запрещён. Type-only foreign contracts допускаются по [SLM-PRO-XDOM-005](./cross-domain-boundary.md#type-only-contracts).
|
||||
|
||||
## Constructor и activation
|
||||
|
||||
Assembly определяет способ создания, но не владеет полным cross-domain graph.
|
||||
|
||||
Отсутствие product request, socket connection и background resource при вызове runtime creator определяется base-правилом `SLM-BASE-LIFE-002`.
|
||||
|
||||
```text
|
||||
module import
|
||||
→ определяет creator
|
||||
|
||||
creator call
|
||||
→ создаёт runtime instance
|
||||
|
||||
explicit start
|
||||
→ запускает resources
|
||||
```
|
||||
|
||||
**SLM-PRO-ASM-010 - ОБЯЗАН.** Resources запускает composition scope owner в выбранном scope согласно [lifecycle rules](../../../runtime-and-lifecycle.md).
|
||||
|
||||
## Public entrypoints
|
||||
|
||||
**SLM-PRO-CMP-004 - ЗАПРЕЩЕНО.** Composition не может повторять adapter wiring, если domain public assembly уже создаёт готовый runtime.
|
||||
|
||||
**SLM-PRO-CMP-013 - ОБЯЗАН.** Composition должна использовать public client/server creator domain, если domain предоставляет runtime-specific assembly.
|
||||
|
||||
**SLM-PRO-CMP-014 - МОЖЕТ.** Composition может вызвать public business factory напрямую только для universal domain, у которого нет external ports, concrete adapters и runtime-specific input.
|
||||
|
||||
**SLM-PRO-ASM-011 - ОБЯЗАН.** Client и server assembly должны иметь разные public entrypoints.
|
||||
|
||||
**SLM-PRO-ASM-012 - ЗАПРЕЩЕНО.** Общий domain barrel не может runtime-реэкспортировать одновременно client и server surfaces.
|
||||
|
||||
## Server/client bridge
|
||||
|
||||
Client и server runtimes являются разными instances над общей business semantics.
|
||||
|
||||
Запрет на передачу DomainRuntime, functions, Context, store или query client через serializable server/client boundary определяется правилом [SLM-BASE-DATA-012](../../../state-and-data.md#serializable-boundaries).
|
||||
|
||||
**SLM-PRO-ASM-014 - МОЖЕТ.** Server может передать client assembly только serializable business-owned bootstrap data без secrets и mutable runtime objects.
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
title: Cross-domain boundary
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Cross-domain Boundary
|
||||
|
||||
> Overlay: `SLM Pro`.
|
||||
|
||||
Domains не образуют скрытый runtime graph внутри слоя `domains`. Граф связывается только graph owner в `compositions`.
|
||||
|
||||
## Composition graph
|
||||
|
||||
**SLM-PRO-CMP-001 - ОБЯЗАН.** Runtime graph нескольких domains должен собираться в composition, которая владеет его scope.
|
||||
|
||||
```ts
|
||||
const auth = createAuthRuntime()
|
||||
const user = createUserRuntime({ auth: auth.session })
|
||||
const orders = createOrdersRuntime({ user: user.agreements })
|
||||
```
|
||||
|
||||
**SLM-PRO-CMP-002 - ОБЯЗАН.** Composition должна создавать domain runtimes в явном ацикличном порядке.
|
||||
|
||||
**SLM-PRO-CMP-003 - ОБЯЗАН.** Cross-domain dependency должна передаваться как готовая минимальная capability, а не разрешаться service locator или domain import.
|
||||
|
||||
**SLM-PRO-CMP-012 - ОБЯЗАН.** App-specific graph type должен отражать только реально предоставленные runtimes; `Partial<Graph>` с последующим приведением к полному graph запрещён.
|
||||
|
||||
## Runtime imports
|
||||
|
||||
**SLM-PRO-XDOM-001 - ЗАПРЕЩЕНО.** Ни одна zone domain A не может импортировать, реэкспортировать, dynamic-import или разрешать через service locator runtime value domain B.
|
||||
|
||||
Запрет включает foreign business API, hooks, Provider, Context, components, adapters, runtime creators и event emitters.
|
||||
|
||||
Foreign runtime capability может поступить только argument-ом от composition согласно разделу [Runtime capability injection](#runtime-capability-injection).
|
||||
|
||||
## Type-only contracts
|
||||
|
||||
**SLM-PRO-API-008 - СЛЕДУЕТ.** Cross-domain capability следует описывать consumer-owned structural port вместо зависимости от полного foreign API type.
|
||||
|
||||
**SLM-PRO-XDOM-014 - ЗАПРЕЩЕНО.** Public contract зависимого domain не может реэкспортировать полный foreign DomainRuntime type как собственную cross-domain dependency.
|
||||
|
||||
**SLM-PRO-XDOM-005 - МОЖЕТ.** Business и client/server input contracts domain могут type-only импортировать минимальный стабильный business contract другого domain.
|
||||
|
||||
Предпочтение consumer-owned port определяется правилом `SLM-PRO-API-008`.
|
||||
|
||||
```ts
|
||||
export type UserAuthPort = {
|
||||
getSessionSnapshot: () => SessionSnapshot
|
||||
subscribeToSession: (listener: () => void) => () => void
|
||||
}
|
||||
```
|
||||
|
||||
Type-only import не разрешает runtime import и не переносит ownership.
|
||||
|
||||
**SLM-PRO-XDOM-012 - ЗАПРЕЩЕНО.** Type dependency cycle между domains запрещён, даже если не создаёт runtime cycle.
|
||||
|
||||
## Runtime capability injection
|
||||
|
||||
**SLM-PRO-XDOM-007 - МОЖЕТ.** Domain runtime creator может принять готовую structurally compatible capability, созданную другим domain и переданную composition.
|
||||
|
||||
```ts
|
||||
const auth = createAuthClientRuntime()
|
||||
const user = createUserClientRuntime({ auth: auth.session })
|
||||
```
|
||||
|
||||
User domain знает только свой input contract. Он не знает creator, Provider, adapters и scope AuthRuntime.
|
||||
|
||||
**SLM-PRO-XDOM-008 - ОБЯЗАН.** Передаваемая capability должна быть минимальной и не раскрывать raw store, Context, SDK client или mutable internals foreign domain.
|
||||
|
||||
**SLM-PRO-XDOM-013 - МОЖЕТ.** Structurally compatible foreign capability может реализовать consumer-owned port напрямую. Wrapper adapter создаётся только при необходимости преобразовать contracts или lifecycle.
|
||||
|
||||
## React composition
|
||||
|
||||
Если React-сущность использует runtime API двух domains, она принадлежит `compositions`.
|
||||
|
||||
```tsx
|
||||
const ProtectedOrderForm = () => {
|
||||
const auth = useAuth()
|
||||
const order = useOrder()
|
||||
|
||||
return auth.isAuthenticated
|
||||
? <OrderForm order={order} />
|
||||
: <AuthPrompt />
|
||||
}
|
||||
```
|
||||
|
||||
**SLM-PRO-XDOM-009 - ОБЯЗАН.** Props, callbacks и slots, передаваемые из composition в domain UI, должны оставаться domain-local или presentation-neutral. Foreign domain semantics остаётся во владеющей composition.
|
||||
|
||||
```tsx
|
||||
<AuthRequired>
|
||||
<OrderForm />
|
||||
</AuthRequired>
|
||||
```
|
||||
|
||||
Такое связывание выполняется в composition, а не внутри auth или orders.
|
||||
|
||||
## Events
|
||||
|
||||
Прямая подписка на event emitter другого domain через runtime import запрещена правилом `SLM-PRO-XDOM-001`.
|
||||
|
||||
Composition может передать event capability через consumer-owned port:
|
||||
|
||||
```ts
|
||||
const orders = createOrdersClientRuntime({
|
||||
userEvents: {
|
||||
subscribeToIdentity: user.identity.subscribe,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Cycles
|
||||
|
||||
**SLM-PRO-XDOM-011 - ЗАПРЕЩЕНО.** Runtime dependency cycle между domains является нарушением границы и не может скрываться event bus, lazy resolution или two-way service locator.
|
||||
|
||||
**SLM-PRO-LIFE-008 - ОБЯЗАН.** Cross-domain graph запускается в dependency order и освобождается в обратном порядке.
|
||||
|
||||
Ненормативное пояснение: при обнаружении цикла следует пересмотреть один из вариантов:
|
||||
|
||||
- пересмотреть границы domains;
|
||||
- перенести orchestration в composition;
|
||||
- выделить отдельную product responsibility;
|
||||
- инвертировать зависимость через consumer-owned port.
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
title: Framework surface в SLM Pro
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Framework Surface
|
||||
|
||||
> Overlay: `SLM Pro`.
|
||||
|
||||
Framework surface адаптирует готовый DomainRuntime к execution model конкретного framework. В текущей структуре React surface располагается в `react/`.
|
||||
|
||||
## Структура React surface
|
||||
|
||||
```text
|
||||
domains/{group...}/{domain}/react/
|
||||
├── context/
|
||||
├── providers/
|
||||
├── hooks/
|
||||
├── ui/
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
Ни один segment не обязателен без реальной потребности.
|
||||
|
||||
## Runtime access
|
||||
|
||||
**SLM-PRO-FRM-001 - ОБЯЗАН.** Framework surface должна работать с конкретным DomainRuntime через domain-owned runtime access boundary.
|
||||
|
||||
**SLM-PRO-FRM-002 - ЗАПРЕЩЕНО.** Framework hook или component не может самостоятельно вызывать business factory, создавать adapters или разрешать runtime из global service locator.
|
||||
|
||||
**SLM-PRO-FRM-003 - ОБЯЗАН.** Runtime access boundary должна получать готовый DomainRuntime извне и не создавать параллельное domain state.
|
||||
|
||||
Для React типичным механизмом является private Context, связывающий статически экспортированные hooks/components с переданным runtime instance. Это пояснение не предписывает точную форму или количество Providers в текущем draft.
|
||||
|
||||
**Domain runtime Provider** - часть framework surface, получающая готовый DomainRuntime и предоставляющая его framework consumers одного domain. Provider не создаёт cross-domain graph автоматически.
|
||||
|
||||
## Imports
|
||||
|
||||
**SLM-PRO-FRM-004 - ОБЯЗАН.** React surface должна импортировать business runtime contracts только через `import type`.
|
||||
|
||||
**SLM-PRO-FRM-005 - ЗАПРЕЩЕНО.** React surface не может runtime-импортировать business factory, private business services, selectors, validators, errors или constants.
|
||||
|
||||
**SLM-PRO-FRM-006 - ЗАПРЕЩЕНО.** React surface не может импортировать domain adapters, SDK, product infra client или assembly.
|
||||
|
||||
**SLM-PRO-FRM-007 - МОЖЕТ.** React surface может импортировать public API `ui`, `shared` и framework libraries, разрешённые её runtime profile.
|
||||
|
||||
Cross-domain runtime imports framework surface запрещены правилом [SLM-PRO-XDOM-001](./cross-domain-boundary.md#runtime-imports).
|
||||
|
||||
## Hooks
|
||||
|
||||
**SLM-PRO-FRM-009 - ОБЯЗАН.** Domain hook должен получать product data и behavior только через текущий DomainRuntime.
|
||||
|
||||
**SLM-PRO-FRM-010 - МОЖЕТ.** Hook может использовать framework query/cache runtime как private implementation поверх imperative DomainRuntime query.
|
||||
|
||||
**SLM-PRO-FRM-011 - ЗАПРЕЩЕНО.** Query hook не может использовать adapter или SDK call как fetcher в обход DomainRuntime.
|
||||
|
||||
**SLM-PRO-FRM-012 - ЗАПРЕЩЕНО.** Query-library types, cache keys и raw mutate API не могут становиться public business contract.
|
||||
|
||||
## Domain UI
|
||||
|
||||
Domain React UI может:
|
||||
|
||||
- вызывать hooks своего domain;
|
||||
- использовать universal UI;
|
||||
- отображать domain-owned states и outcomes;
|
||||
- принимать callbacks, props и slots от composition.
|
||||
|
||||
**SLM-PRO-FRM-013 - ЗАПРЕЩЕНО.** Domain UI не может импортировать runtime другого domain или оркестрировать route/page flow.
|
||||
|
||||
Владение React UI, использующим несколько domains, определено base-правилом [SLM-BASE-CMP-006](../../../layers/compositions.md#product-ui).
|
||||
|
||||
## Client boundary
|
||||
|
||||
**SLM-PRO-FRM-015 - ОБЯЗАН.** Entry point React hooks, Context и interactive UI должен быть явно отмечен как client runtime согласно правилам используемого framework.
|
||||
|
||||
**SLM-PRO-FRM-016 - ЗАПРЕЩЕНО.** Server-compatible React export не может попадать в client entrypoint только из-за нахождения рядом с client hooks или Provider.
|
||||
|
||||
React не является синонимом client runtime; environment profile определяется фактическими dependencies export.
|
||||
@@ -1,158 +0,0 @@
|
||||
---
|
||||
title: Domains в SLM Pro
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Domains в SLM Pro
|
||||
|
||||
> Overlay: `SLM Pro`. Base: [SLM](../../../index.md).
|
||||
|
||||
Domain является изолированным вертикальным product module с одной предметной ответственностью, явным public boundary и строгими внутренними dependency zones.
|
||||
|
||||
## Domain и group
|
||||
|
||||
**SLM-PRO-DOM-001 - ОБЯЗАН.** Конечный Pro domain должен располагаться непосредственно в `domains` или внутри одной или нескольких навигационных groups.
|
||||
|
||||
```text
|
||||
domains/{domain}
|
||||
domains/{group}/{domain}
|
||||
domains/{group}/{nested-group}/{domain}
|
||||
```
|
||||
|
||||
**SLM-PRO-DOM-002 - ОБЯЗАН.** Узел domain tree с собственным public API, state, integration, assembly или runtime должен классифицироваться как конечный domain, а не domain group.
|
||||
|
||||
```text
|
||||
domains/
|
||||
├── navigation/ # domain
|
||||
└── knv/ # group
|
||||
├── auth/ # domain
|
||||
├── user/ # domain
|
||||
└── orders/ # domain
|
||||
```
|
||||
|
||||
**SLM-PRO-DOM-003 - ОБЯЗАН.** Первой архитектурной единицей в group tree является конечная папка, владеющая самостоятельной product responsibility.
|
||||
|
||||
## Ownership
|
||||
|
||||
**SLM-PRO-DOM-004 - ОБЯЗАН.** Pro domain должен владеть одной сформулированной product responsibility и предоставлять её внешним consumers через собственные public entrypoints.
|
||||
|
||||
Pro domain может владеть:
|
||||
|
||||
- product model и value objects;
|
||||
- scenarios и operations;
|
||||
- domain state и transitions;
|
||||
- normalization и product errors;
|
||||
- business-owned ports;
|
||||
- concrete integrations собственных ports;
|
||||
- framework hooks и UI одного domain;
|
||||
- client/server runtime assembly.
|
||||
|
||||
**SLM-PRO-DOM-005 - ЗАПРЕЩЕНО.** Domain не может владеть framework route entry, page/layout composition, UI нескольких самостоятельных product responsibilities, universal technical capability или product-agnostic UI primitive.
|
||||
|
||||
Public entrypoints Pro domain следуют base-правилам `SLM-BASE-API-001` и `SLM-BASE-API-002`; Pro-главы вводят дополнительные ограничения exports.
|
||||
|
||||
**SLM-PRO-DOM-007 - ЗАПРЕЩЕНО.** Если product responsibility получила Pro domain owner, app, composition или infra не могут создавать параллельную модель этой ответственности либо обходить её public boundary.
|
||||
|
||||
**SLM-PRO-DOM-008 - ОБЯЗАН.** Для domain-owned responsibility это правило заменяет base-правило `SLM-BASE-CMP-001`: business владеет product logic, а composition владеет application flow и runtime graph.
|
||||
|
||||
Product responsibility считается устойчивой, если имеет самостоятельную product model или transitions, используется несколькими application flows либо владеет external integration/lifecycle contract.
|
||||
|
||||
**SLM-PRO-DOM-017 - ОБЯЗАН.** Каждая устойчивая product responsibility должна иметь Pro domain owner; route/page-local presentation flow остаётся ответственностью composition.
|
||||
|
||||
## Внутренние zones
|
||||
|
||||
```text
|
||||
domains/{group...}/{domain}/
|
||||
├── business/
|
||||
├── react/
|
||||
├── adapters/
|
||||
├── client/
|
||||
└── server/
|
||||
```
|
||||
|
||||
| Zone | Статус | Ответственность |
|
||||
|---|---|---|
|
||||
| [`business`](./business.md) | Обязательная | Product model, factory, ports, scenarios, errors |
|
||||
| [`react`](./framework.md) | Опциональная | React runtime access, hooks, Providers, domain UI |
|
||||
| [`adapters`](./ports-and-adapters.md) | Опциональная | Concrete реализации business-owned ports |
|
||||
| [`client`](./client-and-server.md) | Опциональная | Browser/client assembly одного domain |
|
||||
| [`server`](./client-and-server.md) | Опциональная | Server/request assembly одного domain |
|
||||
|
||||
**SLM-PRO-DOM-009 - ОБЯЗАН.** Каждый Pro domain должен содержать `business` как единственного владельца product model и business semantics.
|
||||
|
||||
**SLM-PRO-DOM-010 - СЛЕДУЕТ.** Опциональную zone следует добавлять только при наличии реального runtime consumer и самостоятельной ответственности.
|
||||
|
||||
**SLM-PRO-DOM-011 - ЗАПРЕЩЕНО.** Нельзя создавать пустые симметричные `react`, `adapters`, `client` или `server` на будущее.
|
||||
|
||||
**SLM-PRO-DOM-012 - ОБЯЗАН.** Domain zones должны соблюдать внутреннюю dependency direction, даже если физически находятся под одним владельцем.
|
||||
|
||||
**SLM-PRO-MOD-001 - ОБЯЗАН.** `business`, `react`, `adapters`, `client` и `server` являются внутренними zones одного domain, а не самостоятельными верхнеуровневыми modules.
|
||||
|
||||
**SLM-PRO-SEG-001 - ЗАПРЕЩЕНО.** Domain zones нельзя трактовать как взаимозаменяемые generic segments.
|
||||
|
||||
Внутри каждой zone могут использоваться обычные base SLM segments по фактической необходимости.
|
||||
|
||||
## Внутреннее направление
|
||||
|
||||
```text
|
||||
business -> shared | pure libraries
|
||||
react -> ui | shared | framework libraries
|
||||
adapters -> infra | SDK | platform runtime
|
||||
client -> own business factory | own client adapters | own framework surface | client technical inputs
|
||||
server -> own business factory | own server adapters | server technical inputs
|
||||
```
|
||||
|
||||
Матрица описывает runtime imports. React surface может type-only импортировать собственные business contracts, adapters - собственные business ports/types, а client/server inputs - разрешённые cross-domain contracts.
|
||||
|
||||
## Путь данных
|
||||
|
||||
```text
|
||||
composition
|
||||
-> domain client/server assembly при наличии runtime-specific setup
|
||||
или напрямую business factory для universal domain
|
||||
-> DomainRuntime
|
||||
-> business scenario
|
||||
-> business-owned port
|
||||
-> domain adapter
|
||||
-> infra / SDK / storage / external source
|
||||
```
|
||||
|
||||
**SLM-PRO-DOM-013 - ОБЯЗАН.** DomainRuntime, созданный business factory, должен быть единственным product gateway своего Pro domain для runtime consumers.
|
||||
|
||||
Stateless logic API также является DomainRuntime, если он создан factory и соблюдает тот же public boundary.
|
||||
|
||||
## Product UI
|
||||
|
||||
**SLM-PRO-DOM-014 - МОЖЕТ.** Product UI одной Pro domain responsibility может принадлежать framework surface этого domain.
|
||||
|
||||
UI нескольких самостоятельных responsibilities остаётся в `compositions` согласно base-правилу `SLM-BASE-CMP-006`.
|
||||
|
||||
## Cross-domain graph
|
||||
|
||||
```text
|
||||
composition
|
||||
-> создаёт несколько domain runtimes
|
||||
-> передаёт готовые capabilities
|
||||
```
|
||||
|
||||
Pro domain не создаёт runtime другого domain и не импортирует его runtime surface. Точные правила определены в [Cross-domain boundary](./cross-domain-boundary.md).
|
||||
|
||||
**Graph owner** - composition, являющаяся scope owner нескольких DomainRuntime, связанных направленными dependencies в одном ацикличном graph, и определяющая порядок их создания, activation и cleanup.
|
||||
|
||||
## Monorepo boundary
|
||||
|
||||
**SLM-PRO-DOM-015 - ОБЯЗАН.** Pro domain должен оставаться внутри `apps/{app}/src/domains` до принятия отдельной package-модели.
|
||||
|
||||
**SLM-PRO-DOM-016 - ЗАПРЕЩЕНО.** Workspace package не может называться Pro Domain для целей Specification, если он не соответствует application path и ownership этой главы.
|
||||
|
||||
## Главы Pro Domain Specification
|
||||
|
||||
- [Business](./business.md)
|
||||
- [Framework surface](./framework.md)
|
||||
- [Ports и adapters](./ports-and-adapters.md)
|
||||
- [Client и server assembly](./client-and-server.md)
|
||||
- [Cross-domain boundary](./cross-domain-boundary.md)
|
||||
- [Тестирование Pro domains](./testing.md)
|
||||
@@ -1,100 +0,0 @@
|
||||
---
|
||||
title: Ports и adapters в SLM Pro
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Ports и Adapters
|
||||
|
||||
> Overlay: `SLM Pro`.
|
||||
|
||||
Port определяет потребность business. Adapter связывает эту потребность с concrete runtime.
|
||||
|
||||
## Ownership
|
||||
|
||||
```text
|
||||
domain/
|
||||
├── business/
|
||||
│ └── ports/
|
||||
└── adapters/
|
||||
```
|
||||
|
||||
**SLM-PRO-ADP-001 - ОБЯЗАН.** Port должен принадлежать `business` того domain, который потребляет capability.
|
||||
|
||||
**SLM-PRO-ADP-002 - ОБЯЗАН.** Concrete adapter должен принадлежать тому же domain, но находиться вне `business`.
|
||||
|
||||
**SLM-PRO-ADP-003 - ЗАПРЕЩЕНО.** Infra или external SDK не могут объявлять business port от имени domain.
|
||||
|
||||
**SLM-PRO-ADP-014 - ОБЯЗАН.** External technical capability из infra, SDK, storage или platform runtime должна реализовывать business port через adapter собственного domain, а этот adapter должен подключаться assembly того же domain. Готовая capability другого DomainRuntime может удовлетворять consumer-owned port напрямую только по правилу [SLM-PRO-XDOM-013](./cross-domain-boundary.md#runtime-capability-injection).
|
||||
|
||||
## Adapter contract
|
||||
|
||||
**SLM-PRO-ADP-004 - ОБЯЗАН.** Responsibilities adapter должны ограничиваться применимыми integration operations:
|
||||
|
||||
- импортировать type-only business port и domain input types;
|
||||
- импортировать public infra API, SDK или platform runtime;
|
||||
- переводить domain arguments в transport arguments;
|
||||
- возвращать raw/unknown source result для business normalization;
|
||||
- подписываться на concrete event source через явный lifecycle contract.
|
||||
|
||||
**SLM-PRO-ADP-005 - ЗАПРЕЩЕНО.** Adapter не может выполнять следующие domain/framework responsibilities:
|
||||
|
||||
- создавать domain error;
|
||||
- выбирать domain fallback;
|
||||
- реализовывать business rule;
|
||||
- объявлять domain model;
|
||||
- экспортировать concrete client consumer-коду;
|
||||
- вызывать framework hook;
|
||||
- runtime-импортировать или самостоятельно разрешать другой domain runtime.
|
||||
|
||||
Adapter может работать с минимальной foreign capability, явно переданной composition, только для преобразования contract или lifecycle согласно `SLM-PRO-XDOM-013`.
|
||||
|
||||
**SLM-PRO-ADP-006 - ОБЯЗАН.** Adapter должен реализовывать ровно тот port contract, который необходим business.
|
||||
|
||||
**SLM-PRO-ADP-007 - ЗАПРЕЩЕНО.** Нельзя передавать полный client, если port требует ограниченный набор capabilities.
|
||||
|
||||
**SLM-PRO-ADP-008 - ЗАПРЕЩЕНО.** Adapter integration logic не должна писаться inline в composition или runtime assembly.
|
||||
|
||||
## Client и server adapters
|
||||
|
||||
Adapters могут быть разделены по runtime:
|
||||
|
||||
```text
|
||||
adapters/
|
||||
├── client/
|
||||
│ ├── browser-session.adapter.ts
|
||||
│ └── websocket-orders.adapter.ts
|
||||
└── server/
|
||||
├── request-session.adapter.ts
|
||||
└── server-orders-api.adapter.ts
|
||||
```
|
||||
|
||||
**SLM-PRO-ADP-009 - ОБЯЗАН.** Client adapter не должен попадать в server graph, а server adapter - в client graph.
|
||||
|
||||
**SLM-PRO-ADP-010 - ОБЯЗАН.** Runtime-specific adapter должен иметь явный environment marker, если framework предоставляет такой механизм.
|
||||
|
||||
## Event sources
|
||||
|
||||
Socket, subscription и event listener реализуют event port:
|
||||
|
||||
```ts
|
||||
export type OrdersEventsPort = {
|
||||
subscribe: (listener: (event: unknown) => void) => () => void
|
||||
}
|
||||
```
|
||||
|
||||
**SLM-PRO-ADP-011 - ОБЯЗАН.** Event adapter должен возвращать cleanup и не открывать connection при module import.
|
||||
|
||||
**SLM-PRO-ADP-012 - ОБЯЗАН.** Wire event проходит business normalization до изменения domain state или передачи consumer-коду.
|
||||
|
||||
**SLM-PRO-LIFE-013 - МОЖЕТ.** Один physical transport может обслуживать adapters нескольких domains, если transport остаётся domain-agnostic, а adapters получают суженные channels.
|
||||
|
||||
## Public boundary
|
||||
|
||||
**SLM-PRO-API-014 - ЗАПРЕЩЕНО.** Public business, framework, client или server entrypoint не может реэкспортировать concrete adapter внешним consumers.
|
||||
|
||||
**SLM-PRO-ADP-013 - ЗАПРЕЩЕНО.** `adapters` не имеет внешнего public API для app, compositions или других domains.
|
||||
|
||||
Adapters доступны только assembly собственного domain и собственным contract tests.
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
title: Тестирование Pro domains
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# Тестирование Pro Domains
|
||||
|
||||
> Overlay: `SLM Pro`.
|
||||
|
||||
Общие правила [тестирования и соответствия](../../../testing-and-conformance.md) дополняются проверками строгих business, adapter, assembly и framework boundaries.
|
||||
|
||||
## Business factory tests
|
||||
|
||||
**SLM-PRO-TEST-001 - ОБЯЗАН.** Каждый public method runtime API, возвращаемого factory, должен иметь factory-level tests.
|
||||
|
||||
Factory-level tests должны проверять применимые случаи:
|
||||
|
||||
- happy path;
|
||||
- malformed external result;
|
||||
- rejected dependency;
|
||||
- синхронное исключение dependency;
|
||||
- domain outcome/error semantics;
|
||||
- side-effect order;
|
||||
- state transition;
|
||||
- отсутствие constructor-time I/O;
|
||||
- public API shape.
|
||||
|
||||
**SLM-PRO-TEST-002 - ОБЯЗАН.** Factory-level test должен создавать runtime через public `business` entrypoint, а не deep-import factory internals.
|
||||
|
||||
## Adapter tests
|
||||
|
||||
**SLM-PRO-TEST-003 - ОБЯЗАН.** Adapter с mapping, transport payload, error channel или lifecycle должен иметь contract tests на применимые responsibilities.
|
||||
|
||||
**SLM-PRO-TEST-004 - ЗАПРЕЩЕНО.** Adapter test не должен дублировать business scenario tests или утверждать domain fallback/error semantics.
|
||||
|
||||
## Assembly tests
|
||||
|
||||
**SLM-PRO-TEST-005 - ОБЯЗАН.** Client/server assembly tests должны проверять корректную передачу ports, runtime profile isolation и отсутствие I/O при creation.
|
||||
|
||||
**SLM-PRO-TEST-006 - ОБЯЗАН.** Server assembly с request data должен иметь isolation test для параллельных scopes.
|
||||
|
||||
## Framework tests
|
||||
|
||||
**SLM-PRO-TEST-007 - ОБЯЗАН.** Framework surface tests должны проверять runtime access boundary, предсказуемую ошибку при отсутствии runtime boundary, mapping public outcomes и lifecycle integration.
|
||||
|
||||
## Composition tests
|
||||
|
||||
**SLM-PRO-TEST-009 - ОБЯЗАН.** Tests cross-domain composition должны проверять topology, точный graph contract, переданные capabilities и lifecycle cleanup.
|
||||
|
||||
**SLM-PRO-TEST-010 - ОБЯЗАН.** Scope с неполным набором domains не должен типизироваться как полный application graph.
|
||||
|
||||
## Architecture checks
|
||||
|
||||
**SLM-PRO-TEST-019 - ОБЯЗАН.** Pro repository checks должны проверять применимые строгие domain boundaries:
|
||||
|
||||
- client/server markers;
|
||||
- forbidden runtime imports между domains;
|
||||
- private adapters;
|
||||
- business entrypoint shape;
|
||||
- zone dependency direction.
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: SLM Pro
|
||||
status: draft
|
||||
normative: true
|
||||
overlay: pro
|
||||
base: slm
|
||||
---
|
||||
|
||||
# SLM Pro
|
||||
|
||||
`SLM Pro` является независимым overlay непосредственно над [base SLM](../../index.md).
|
||||
|
||||
```text
|
||||
SLM Pro = SLM + Pro rules
|
||||
```
|
||||
|
||||
## Отличия от SLM
|
||||
|
||||
| Область | Base SLM | SLM Pro |
|
||||
|---|---|---|
|
||||
| Product ownership | Product logic принадлежит compositions | Устойчивая product responsibility принадлежит изолированному domain |
|
||||
| Слои | `app`, `compositions`, `infra`, `ui`, `shared` | Добавляется `domains` |
|
||||
| Структура domain | Отсутствует | `business`, framework surface, adapters, client/server assembly |
|
||||
| Domain dependencies | Отсутствуют | Cross-domain runtime imports запрещены, capabilities передаются composition |
|
||||
| External integration | Composition использует infra | Private domain adapter реализует business-owned port |
|
||||
| Testing | Risk-based base tests | Обязательные tests для используемых factory, adapter, assembly и graph boundaries |
|
||||
|
||||
## Расширение архитектурной модели
|
||||
|
||||
**SLM-PRO-ARCH-001 - ОБЯЗАН.** SLM Pro должен расширять набор base-слоёв слоем `domains` для изолированных product responsibilities.
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/
|
||||
├── compositions/
|
||||
├── domains/
|
||||
├── infra/
|
||||
├── ui/
|
||||
└── shared/
|
||||
```
|
||||
|
||||
**SLM-PRO-ARCH-002 - ОБЯЗАН.** Дополнительные dependency edges Pro должны соответствовать следующему направлению:
|
||||
|
||||
```text
|
||||
compositions -> domains
|
||||
domains -> согласно внутренним Pro zones
|
||||
```
|
||||
|
||||
Base dependency direction для остальных слоёв сохраняется.
|
||||
|
||||
**SLM-PRO-CMP-010 - МОЖЕТ.** Composition module может импортировать public entrypoints Pro domains в дополнение к imports, разрешённым base-правилом `SLM-BASE-CMP-010`.
|
||||
|
||||
## Pro Domain Specification
|
||||
|
||||
Полная Pro-модель слоя описана в [Domains](./domains/index.md). Других mode-specific отличий текущий draft Pro не вводит.
|
||||
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: Модули и группы
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Модули и Группы
|
||||
|
||||
## Module
|
||||
|
||||
Module является минимальным самостоятельным владельцем ответственности и предоставляет public boundary внешнему коду.
|
||||
|
||||
**SLM-BASE-MOD-001 - ОБЯЗАН.** Module должен иметь одну сформулированную ответственность и одного архитектурного owner.
|
||||
|
||||
**SLM-BASE-MOD-002 - ОБЯЗАН.** Внешний consumer взаимодействует с module только через его public API.
|
||||
|
||||
**SLM-BASE-MOD-003 - СЛЕДУЕТ.** Module следует ограничивать только теми внутренними parts и segments, которые необходимы текущей ответственности.
|
||||
|
||||
Типичные modules:
|
||||
|
||||
- page, layout, screen или widget в `compositions`;
|
||||
- technical service в `infra`;
|
||||
- reusable UI module в `ui`.
|
||||
|
||||
`app` содержит framework entries и не обязан организовываться как SLM modules. `shared` может содержать небольшие public units, но не runtime modules.
|
||||
|
||||
## Group
|
||||
|
||||
Group классифицирует modules и другие groups, но не владеет поведением.
|
||||
|
||||
**SLM-BASE-MOD-004 - ЗАПРЕЩЕНО.** Group не может иметь `index.ts`, public API, state, runtime, dependencies или assembly.
|
||||
|
||||
**SLM-BASE-MOD-005 - ЗАПРЕЩЕНО.** Внешний код не может импортировать group path.
|
||||
|
||||
**SLM-BASE-MOD-006 - МОЖЕТ.** Group может содержать другие groups и конечные modules.
|
||||
|
||||
```text
|
||||
compositions/
|
||||
└── pages/ # group
|
||||
├── home/ # composition module
|
||||
└── profile/ # composition module
|
||||
```
|
||||
|
||||
## Component
|
||||
|
||||
Component является presentation unit внутри module и не считается самостоятельным архитектурным owner.
|
||||
|
||||
**SLM-BASE-MOD-008 - ЗАПРЕЩЕНО.** Component не может самостоятельно выбирать application-level product source, выполнять module wiring или оркестрировать несколько самостоятельных modules.
|
||||
|
||||
**SLM-BASE-MOD-009 - МОЖЕТ.** Component может владеть локальной presentation mechanics и рендерить другие components, разрешённые слоем владельца.
|
||||
|
||||
**SLM-BASE-MOD-010 - ОБЯЗАН.** Presentation unit с самостоятельной ответственностью, внешними архитектурными dependencies или внутренней modular structure должна оформляться как module или nested module. Сам факт локального hook/state не делает component модулем.
|
||||
|
||||
## Nested module
|
||||
|
||||
Самостоятельная часть родительского module может быть оформлена nested module, если имеет собственную ответственность и public boundary только внутри родителя.
|
||||
|
||||
```text
|
||||
compositions/pages/home/
|
||||
└── parts/
|
||||
└── hero-section/
|
||||
├── hero-section.tsx
|
||||
└── index.ts
|
||||
```
|
||||
|
||||
**SLM-BASE-MOD-011 - ЗАПРЕЩЕНО.** Nested module не может использоваться для сокрытия ответственности, которой фактически владеет другой module или layer.
|
||||
|
||||
## Scope evolution
|
||||
|
||||
**SLM-BASE-MOD-012 - СЛЕДУЕТ.** Код следует поднимать из локального owner в более широкий module только после появления реального совместного consumer или общей ответственности.
|
||||
|
||||
**SLM-BASE-MOD-013 - ЗАПРЕЩЕНО.** Физическое повторение само по себе не доказывает общий ownership.
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
title: Монорепозитории
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Монорепозитории
|
||||
|
||||
SLM применяется внутри границы каждого frontend-приложения. Workspace packages имеют собственные public boundaries и ownership.
|
||||
|
||||
## Application boundary
|
||||
|
||||
```text
|
||||
apps/
|
||||
└── web/
|
||||
└── src/
|
||||
├── app/
|
||||
├── compositions/
|
||||
├── infra/
|
||||
├── ui/
|
||||
└── shared/
|
||||
```
|
||||
|
||||
**SLM-BASE-MONO-001 - ОБЯЗАН.** Каждое приложение должно самостоятельно определять свои application compositions, product ownership и runtime wiring.
|
||||
|
||||
**SLM-BASE-MONO-002 - ЗАПРЕЩЕНО.** Workspace package не может импортировать код из `apps/*`.
|
||||
|
||||
**SLM-BASE-MONO-003 - ЗАПРЕЩЕНО.** Одно приложение не может deep-import исходники другого приложения вместо общего package contract.
|
||||
|
||||
## Package boundary
|
||||
|
||||
**SLM-BASE-MONO-004 - ОБЯЗАН.** Package должен иметь самостоятельного owner, public exports и подтверждённую reuse/ownership semantics.
|
||||
|
||||
**SLM-BASE-MONO-005 - ЗАПРЕЩЕНО.** Нельзя создавать package только для обхода layer direction, public API или иной объявленной dependency boundary.
|
||||
|
||||
**SLM-BASE-MONO-006 - ОБЯЗАН.** Consumers импортируют package через объявленный package export, а не через filesystem path к internal source.
|
||||
|
||||
## Типичные packages
|
||||
|
||||
Допустимыми кандидатами являются:
|
||||
|
||||
- product-agnostic UI kit;
|
||||
- technical infra client;
|
||||
- deterministic shared foundation;
|
||||
- schema/codegen/tooling package;
|
||||
- configuration package без application-specific wiring.
|
||||
|
||||
Base SLM не присваивает package дополнительный архитектурный статус автоматически.
|
||||
|
||||
## Dependency direction
|
||||
|
||||
**SLM-BASE-MONO-009 - ОБЯЗАН.** Package dependency graph должен оставаться ацикличным и соответствовать заявленной ответственности packages.
|
||||
|
||||
**SLM-BASE-MONO-010 - ЗАПРЕЩЕНО.** Shared package не может импортировать application composition или app-specific infra package.
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: Public API и импорты
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Public API и Импорты
|
||||
|
||||
Public API ограничивает знание consumers о внутренней структуре module. Точная форма entrypoint определяется владельцем и не требует обязательного `index.ts`.
|
||||
|
||||
## Общие правила
|
||||
|
||||
**SLM-BASE-API-001 - ОБЯЗАН.** Межмодульный import должен использовать объявленный public entrypoint импортируемого module.
|
||||
|
||||
**SLM-BASE-API-002 - ЗАПРЕЩЕНО.** Deep imports во внутренние segments, files и иные private paths другого module запрещены.
|
||||
|
||||
**SLM-BASE-API-003 - ОБЯЗАН.** Каждый runtime export должен иметь реального consumer за пределами владеющего entrypoint и стабильную ответственность.
|
||||
|
||||
**SLM-BASE-API-004 - ЗАПРЕЩЕНО.** Public API не может случайно раскрывать implementation unit, который владелец считает private или lifecycle которого не является частью public contract.
|
||||
|
||||
**SLM-BASE-API-005 - ОБЯЗАН.** Alias или package subpath должен физически разрешаться TypeScript, tests и production build.
|
||||
|
||||
**SLM-BASE-API-009 - МОЖЕТ.** Public entrypoint может быть root `index.ts`, отдельным named entry, package export или другим явно объявленным path.
|
||||
|
||||
**SLM-BASE-API-010 - ОБЯЗАН.** Public и private paths module должны быть различимы consumers и repository tooling.
|
||||
|
||||
## Layer matrix
|
||||
|
||||
| Importer | Runtime imports |
|
||||
|---|---|
|
||||
| `app` | Public composition entries, shared static/global resources |
|
||||
| `compositions` | Compositions, infra, ui, shared |
|
||||
| `infra` | Infra, shared |
|
||||
| `ui` | UI, shared |
|
||||
| `shared` | External pure libraries only |
|
||||
|
||||
## Type-only imports
|
||||
|
||||
**SLM-BASE-API-006 - МОЖЕТ.** `import type` может использоваться для разрешённого contract dependency без создания runtime edge.
|
||||
|
||||
**SLM-BASE-API-007 - ЗАПРЕЩЕНО.** Type-only import не разрешает перенос ownership, импорт private concrete runtime type или обход layer boundary.
|
||||
|
||||
## Groups
|
||||
|
||||
Отсутствие public entrypoint у group определяется base-правилом `SLM-BASE-MOD-004`.
|
||||
|
||||
**SLM-BASE-API-015 - ОБЯЗАН.** Composition public API экспортирует только entry components, access APIs, types и contracts, необходимые внешним composition consumers.
|
||||
|
||||
## Cycles
|
||||
|
||||
**SLM-BASE-API-016 - ЗАПРЕЩЕНО.** Runtime import cycle между modules запрещён независимо от того, способен ли bundler его выполнить.
|
||||
|
||||
**SLM-BASE-API-017 - ЗАПРЕЩЕНО.** Barrel не должен создавать скрытый cycle между ready composition и access API её children.
|
||||
|
||||
Дополнительные entrypoints и import restrictions принадлежат overlay, который их вводит.
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
title: Реестр правил
|
||||
status: draft
|
||||
normative: false
|
||||
search: false
|
||||
aside: false
|
||||
---
|
||||
|
||||
# Реестр Правил
|
||||
|
||||
Реестр формируется автоматически из нормативных объявлений Specification. Для быстрого перехода к известному ID также можно открыть поиск `Ctrl/⌘ K`, ввести полный идентификатор и нажать `Enter`.
|
||||
|
||||
<RuleCatalog />
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
title: Runtime и lifecycle
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Runtime и Lifecycle
|
||||
|
||||
Lifecycle является архитектурной частью любого mutable runtime, subscription и external resource. Эти правила не требуют создавать отдельный runtime или factory, если у module нет соответствующего состояния или resources.
|
||||
|
||||
## Definition, creation и activation
|
||||
|
||||
Для module с создаваемым runtime применима модель:
|
||||
|
||||
```text
|
||||
definition
|
||||
-> module объявляет creator
|
||||
|
||||
creation
|
||||
-> creator создаёт instance без external effects
|
||||
|
||||
activation
|
||||
-> scope owner запускает resources и получает cleanup
|
||||
```
|
||||
|
||||
**SLM-BASE-LIFE-001 - ЗАПРЕЩЕНО.** Module import не должен выполнять product I/O, открывать connection или регистрировать global listener.
|
||||
|
||||
**SLM-BASE-LIFE-002 - ОБЯЗАН.** Если module предоставляет factory или runtime creator, creation должна быть side-effect free относительно external resources.
|
||||
|
||||
**SLM-BASE-LIFE-003 - ОБЯЗАН.** Subscription, socket, timer и listener запускаются явной operation владельца scope.
|
||||
|
||||
**SLM-BASE-LIFE-004 - ОБЯЗАН.** Каждый запущенный resource должен иметь cleanup или dispose contract.
|
||||
|
||||
## Scope
|
||||
|
||||
| Scope | Примеры владельца |
|
||||
|---|---|
|
||||
| Application | Root composition/provider |
|
||||
| Route branch | Route layout composition |
|
||||
| Page | Page composition/provider |
|
||||
| Component flow | Nested composition module |
|
||||
| Request | Server composition/request builder |
|
||||
| Test | Test setup/wrapper |
|
||||
|
||||
**SLM-BASE-LIFE-005 - ОБЯЗАН.** Scope owner должен определить количество instances и duration каждого mutable runtime или resource.
|
||||
|
||||
**SLM-BASE-LIFE-006 - ЗАПРЕЩЕНО.** Module-level singleton не может использоваться как случайная замена application scope.
|
||||
|
||||
**SLM-BASE-LIFE-007 - МОЖЕТ.** Application singleton допустим только при явном application ownership и отсутствии request-, identity- и user-specific data.
|
||||
|
||||
## Activation и cleanup
|
||||
|
||||
**SLM-BASE-LIFE-009 - ОБЯЗАН.** Повторный mount/unmount, включая development Strict Mode, не должен оставлять duplicate subscription или abandoned resource.
|
||||
|
||||
**SLM-BASE-LIFE-010 - СЛЕДУЕТ.** `start` и cleanup следует проектировать idempotent либо явно защищать от повторного вызова.
|
||||
|
||||
**SLM-BASE-LIFE-018 - ОБЯЗАН.** Если activation составного resource set завершилась ошибкой, scope owner должен освободить уже успешно запущенную часть в обратном порядке.
|
||||
|
||||
**SLM-BASE-LIFE-019 - ОБЯЗАН.** Ошибка cleanup должна быть наблюдаемой и не должна препятствовать попытке освободить остальные resources scope.
|
||||
|
||||
## Events и sockets
|
||||
|
||||
Product event обрабатывается владельцем product semantics; socket остаётся technical transport.
|
||||
|
||||
**SLM-BASE-LIFE-011 - ЗАПРЕЩЕНО.** Framework component не может открывать product socket напрямую при render или module import.
|
||||
|
||||
**SLM-BASE-LIFE-012 - ОБЯЗАН.** Invalid event и connection failure должны преобразовываться в product state/outcome либо technical telemetry согласно их semantics; callback error нельзя терять через unobserved throw.
|
||||
|
||||
## Revalidation events
|
||||
|
||||
Event может содержать product update или только сообщать об устаревании данных.
|
||||
|
||||
**SLM-BASE-LIFE-014 - ОБЯЗАН.** Invalidation intent должен выражаться product language и не требовать import конкретной query library в public product contract.
|
||||
|
||||
## Server runtime
|
||||
|
||||
**SLM-BASE-LIFE-015 - ОБЯЗАН.** User-specific server runtime создаётся в request scope.
|
||||
|
||||
**SLM-BASE-LIFE-016 - ЗАПРЕЩЕНО.** Process singleton не может захватывать request headers, cookies, credentials, AbortSignal или user-specific cache.
|
||||
|
||||
**SLM-BASE-LIFE-017 - ОБЯЗАН.** Request cancellation должна передаваться external operations, если runtime и используемая integration поддерживают cancellation.
|
||||
|
||||
Overlay может вводить дополнительные lifecycle boundaries только внутри собственного delta.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Сегменты
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Сегменты
|
||||
|
||||
Segment группирует внутренние файлы module по устойчивой роли. Segment не является самостоятельным layer или module.
|
||||
|
||||
## Базовые segments
|
||||
|
||||
| Segment | Роль |
|
||||
|---|---|
|
||||
| `ui/` | Presentation components текущего module |
|
||||
| `parts/` | Nested modules текущего module |
|
||||
| `hooks/` | Framework hooks текущей ответственности |
|
||||
| `providers/` | Provider implementations текущего module |
|
||||
| `stores/` | Concrete state runtime текущего owner |
|
||||
| `services/` | Scenario operations и service objects |
|
||||
| `mappers/` | Transformation на границе ответственности |
|
||||
| `types/` | Types текущего module |
|
||||
| `styles/` | Styles текущего module |
|
||||
| `lib/` | Небольшие internal utilities |
|
||||
| `config/` | Constants и configuration текущего module |
|
||||
| `tests/` | Tests публичной границы или составного runtime |
|
||||
|
||||
## Правила
|
||||
|
||||
**SLM-BASE-SEG-001 - МОЖЕТ.** Module может использовать любые необходимые segments и не обязан создавать остальные.
|
||||
|
||||
**SLM-BASE-SEG-002 - ЗАПРЕЩЕНО.** Нельзя создавать полный симметричный набор segments как scaffold без реального содержимого.
|
||||
|
||||
**SLM-BASE-SEG-003 - ОБЯЗАН.** Если файл помещён в segment, роль segment должна соответствовать фактической роли файла, а не только его расширению или имени. Файлы могут оставаться в корне небольшого module.
|
||||
|
||||
**SLM-BASE-SEG-004 - ЗАПРЕЩЕНО.** Segment не имеет внешнего public API независимо от module owner.
|
||||
|
||||
Запрет deep import в segment другого module определяется base-правилом `SLM-BASE-API-002`.
|
||||
|
||||
## UI и Parts
|
||||
|
||||
`ui/` содержит presentation components без самостоятельного architectural ownership.
|
||||
|
||||
`parts/` содержит nested modules с собственной внутренней структурой и локальным public boundary.
|
||||
|
||||
**SLM-BASE-SEG-006 - ОБЯЗАН.** Сущность с самостоятельной ответственностью, внешними архитектурными dependencies или nested modules должна размещаться в `parts`, а не маскироваться как плоский component. Локальные presentation hooks/state сами по себе не требуют `parts`.
|
||||
|
||||
## Hooks
|
||||
|
||||
**SLM-BASE-SEG-007 - ОБЯЗАН.** Hook принадлежит тому module, чью ответственность и runtime он выражает.
|
||||
|
||||
Примеры:
|
||||
|
||||
- product hook - владеющий product module;
|
||||
- page-local hook - владеющая page composition;
|
||||
- reusable technical hook - соответствующий infra module;
|
||||
- product-agnostic UI hook - владеющий UI module.
|
||||
|
||||
Segments являются только внутренними организационными ролями и не вводят дополнительных архитектурных zones.
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
title: State и data
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# State и Data
|
||||
|
||||
SLM рассматривает данные и состояние через одного владельца semantics, даже если runtime использует несколько caches и projections.
|
||||
|
||||
## Ownership matrix
|
||||
|
||||
| Вид | Владелец |
|
||||
|---|---|
|
||||
| Product model и transitions | Product owner |
|
||||
| Product source integration | Product owner; technical mechanism остаётся в infra |
|
||||
| Framework projection product data | Public surface владельца product data |
|
||||
| Page-local presentation state | Composition |
|
||||
| Component-local interaction | Владеющий component/module |
|
||||
| Technical connection/cache state | Infra или runtime-specific owner |
|
||||
| Request context | Server/framework scope |
|
||||
| Universal UI state | Владеющий UI module |
|
||||
|
||||
## Product gateway
|
||||
|
||||
**SLM-BASE-DATA-001 - ОБЯЗАН.** Consumer должен получать product data через public boundary владеющего module.
|
||||
|
||||
**SLM-BASE-DATA-002 - ЗАПРЕЩЕНО.** Composition, UI или app не могут маппить transport DTO в параллельную product model, если модель уже имеет другого owner.
|
||||
|
||||
**SLM-BASE-DATA-003 - ОБЯЗАН.** Product owner владеет normalization, validation и semantics отсутствия данных.
|
||||
|
||||
## Product state
|
||||
|
||||
**SLM-BASE-DATA-004 - ОБЯЗАН.** Product state model и допустимые transitions должны определяться product owner независимо от concrete state manager.
|
||||
|
||||
**SLM-BASE-DATA-005 - ЗАПРЕЩЕНО.** Concrete mutable store implementation не может становиться public product contract без явно объявленного владельцем стабильного store access API.
|
||||
|
||||
**SLM-BASE-DATA-006 - ОБЯЗАН.** Mutable product instance должен быть привязан к явному lifecycle scope.
|
||||
|
||||
## Query cache
|
||||
|
||||
Framework или technical query cache может хранить projection результата product query.
|
||||
|
||||
**SLM-BASE-DATA-007 - ОБЯЗАН.** Query/cache consumer за пределами product owner должен использовать public boundary владельца и не может обходить его прямым вызовом private integration или SDK.
|
||||
|
||||
**SLM-BASE-DATA-008 - ЗАПРЕЩЕНО.** Query cache не может объявлять собственную product model, error taxonomy или fallback policy.
|
||||
|
||||
**SLM-BASE-DATA-009 - ОБЯЗАН.** User/session-scoped cache keys и invalidation должны изолировать данные разных identities и scopes без использования secret как публичного key contract.
|
||||
|
||||
Эта draft-версия не предписывает единственное физическое место QueryClient/SWR cache. Конкретная модель оценивается по правилам public boundary владельца, lifecycle и identity isolation.
|
||||
|
||||
**SLM-BASE-DATA-015 - ОБЯЗАН.** Cache instance должен иметь явного creator и scope owner в composition или runtime setup.
|
||||
|
||||
**SLM-BASE-DATA-016 - ОБЯЗАН.** Shared framework cache должен передаваться consumers через framework-supported runtime boundary, а не через import app-specific mutable singleton.
|
||||
|
||||
**SLM-BASE-DATA-017 - ОБЯЗАН.** Scope owner должен очищать или изолировать private cache при смене identity и завершении соответствующего scope.
|
||||
|
||||
## Presentation state
|
||||
|
||||
**SLM-BASE-DATA-010 - МОЖЕТ.** Composition или component может использовать concrete state manager для локального presentation state.
|
||||
|
||||
**SLM-BASE-DATA-011 - ЗАПРЕЩЕНО.** Presentation store не должен копировать canonical product state как второй source of truth.
|
||||
|
||||
## Serializable boundaries
|
||||
|
||||
**SLM-BASE-DATA-012 - ОБЯЗАН.** Через server/client boundary передаются только serializable product-owned data без functions, stores, clients, Context и resources.
|
||||
|
||||
**SLM-BASE-DATA-013 - ЗАПРЕЩЕНО.** Secrets, access tokens и request credentials не должны включаться в client bootstrap snapshot.
|
||||
|
||||
**SLM-BASE-DATA-014 - ОБЯЗАН.** Server и client initial snapshots должны быть согласованы, если framework выполняет hydration одного UI state.
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: Терминология
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Терминология
|
||||
|
||||
## Base SLM
|
||||
|
||||
**Base SLM** - самостоятельная минимальная архитектура, применяемая без дополнительного overlay.
|
||||
|
||||
## Overlay
|
||||
|
||||
**Overlay** - независимое опциональное нормативное расширение, применяемое непосредственно поверх base SLM. Overlay не наследует правила другого overlay.
|
||||
|
||||
## Слой
|
||||
|
||||
**Layer** - верхнеуровневая зона `src`, определяющая вид ответственности и допустимые направления зависимостей.
|
||||
|
||||
Base SLM использует слои `app`, `compositions`, `infra`, `ui` и `shared`.
|
||||
|
||||
## Модуль
|
||||
|
||||
**Module** - минимальный самостоятельный владелец ответственности с public boundary. Модуль может содержать код разных технических типов, если весь этот код принадлежит одной ответственности.
|
||||
|
||||
## Product owner
|
||||
|
||||
**Product owner** - module, владеющий product semantics, model, behavior, data boundary и public API одной ответственности.
|
||||
|
||||
## Группа
|
||||
|
||||
**Group** - навигационная папка, классифицирующая модули или другие группы. Группа не является модулем, не имеет public API и не владеет runtime.
|
||||
|
||||
## Composition
|
||||
|
||||
**Composition** - product module, связывающий public APIs и technical capabilities в page, route, layout, screen, widget или другой application flow.
|
||||
|
||||
## Scope owner
|
||||
|
||||
**Scope owner** - composition, request setup, provider setup или test setup, которое выбирает runtime instances и resources, их lifetime, activation и cleanup.
|
||||
|
||||
## Segment
|
||||
|
||||
**Segment** - внутренняя папка модуля, группирующая файлы по роли, например `hooks`, `services`, `types`, `styles` или `lib`.
|
||||
|
||||
## Компонент
|
||||
|
||||
**Component** - presentation unit внутри владеющего module. Компонент не является самостоятельным архитектурным owner и не выбирает application dependencies самостоятельно.
|
||||
|
||||
## Продуктовые данные
|
||||
|
||||
**Product data** - данные, состояние и outcomes, имеющие смысл в предметной области продукта. Transport DTO, raw SDK response и browser storage schema не являются product model автоматически.
|
||||
|
||||
## Runtime dependency
|
||||
|
||||
**Runtime dependency** - dependency, необходимая выполняемому коду: API другого объекта, external source, store, query runtime, event source, clock, environment или platform capability.
|
||||
|
||||
`import type` не создаёт runtime dependency, но может создавать статическую связанность contracts.
|
||||
|
||||
Термины, вводимые `SLM Advanced` или `SLM Pro`, определяются и имеют нормативную силу только внутри соответствующего overlay.
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Тестирование и соответствие
|
||||
status: draft
|
||||
normative: true
|
||||
---
|
||||
|
||||
# Тестирование и Соответствие
|
||||
|
||||
Тесты проверяют public boundaries и runtime risks каждого owner. Base SLM не требует создавать неиспользуемые архитектурные конструкции ради тестовой формы.
|
||||
|
||||
## Risk-based tests
|
||||
|
||||
**SLM-BASE-TEST-018 - ОБЯЗАН.** Tests изменённого module должны покрывать применимые риски его public behavior, data boundaries и lifecycle.
|
||||
|
||||
Типичные риски:
|
||||
|
||||
- public behavior;
|
||||
- malformed external data;
|
||||
- rejected dependencies;
|
||||
- state transitions;
|
||||
- lifecycle activation и cleanup;
|
||||
- request и identity isolation;
|
||||
- client/server boundary;
|
||||
- отсутствие import-time I/O.
|
||||
|
||||
**SLM-BASE-TEST-008 - ОБЯЗАН.** Client/server import boundary должна проверяться инструментом, понимающим реальный framework module graph, если application имеет раздельные environment entries. DOM unit test не заменяет production build probe.
|
||||
|
||||
Mode-specific test suites принадлежат overlay, который вводит соответствующие конструкции.
|
||||
|
||||
## Architecture conformance
|
||||
|
||||
Типичные mechanically enforceable checks:
|
||||
|
||||
- направление imports;
|
||||
- deep imports;
|
||||
- public entrypoints;
|
||||
- runtime cycles;
|
||||
- заявленный overlay и его rule set;
|
||||
- unique rule IDs документации;
|
||||
- generated artifacts, если они используются.
|
||||
|
||||
**SLM-BASE-TEST-011 - ЗАПРЕЩЕНО.** Документированное правило не считается mechanically enforced, если repository tooling его фактически не проверяет.
|
||||
|
||||
## Единица соответствия
|
||||
|
||||
**SLM-BASE-TEST-014 - ОБЯЗАН.** Application соответствует base SLM, если выполняет все base-правила. Соответствие заявленному overlay оценивается как base-правила с учётом точного scope каждой замены плюс полный rule set выбранного overlay.
|
||||
|
||||
**SLM-BASE-TEST-015 - ОБЯЗАН.** Изменение соответствует заявленной архитектуре, если новые и изменённые modules не создают новых нарушений применимых base-правил или правил выбранного overlay и проходят существующие checks.
|
||||
|
||||
**SLM-BASE-TEST-016 - ОБЯЗАН.** Отступление от правила `СЛЕДУЕТ` должно быть зафиксировано в архитектурном review или принятом decision с указанием причины и scope.
|
||||
|
||||
**SLM-BASE-TEST-017 - ОБЯЗАН.** Manual conformance и mechanical enforcement должны различаться явно; отсутствие автоматической проверки не отменяет применимое нормативное правило.
|
||||
|
||||
## Completion gate
|
||||
|
||||
**SLM-BASE-TEST-012 - ОБЯЗАН.** Изменение считается завершённым только после выполнения ближайших tests, typecheck, lint, build и architecture checks, существующих в repository.
|
||||
|
||||
**SLM-BASE-TEST-013 - ОБЯЗАН.** Невыполненная проверка и остаточный риск должны быть явно указаны в результате работы.
|
||||
Reference in New Issue
Block a user