docs: документация по архитектуре, данным и деплою
Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
This commit is contained in:
1 parent
9d5478ddeb
commit
dbd5762ecf
10 files changed
+1308
-87
No files matched your search
@@ -0,0 +1,150 @@
|
||||
# Слои web
|
||||
|
||||
`apps/web` — React-приложение. Его код разложен по слоям, и зависимости между слоями идут строго в
|
||||
одну сторону:
|
||||
|
||||
```
|
||||
app → pages → widgets → entities → shared
|
||||
```
|
||||
|
||||
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `shared` не знает, где
|
||||
применён и по чьей воле вызван, а `entities` не знает о `widgets`.
|
||||
|
||||
Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном
|
||||
экземпляре, других — столько, сколько модулей.
|
||||
|
||||
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `entities` и `widgets` и определяет,
|
||||
что из них видно снаружи, — тем же способом, каким это делает модуль в
|
||||
[слоях API](01-api-layers.md). Поддомен — такая же рамка, вложенная внутрь модуля.
|
||||
|
||||
## app
|
||||
|
||||
**Точка входа и оболочка.**
|
||||
|
||||
`app` — внешний край приложения. Он монтирует React, объявляет маршруты и их защиту, держит
|
||||
глобальные провайдеры и рисует оболочку: шапку, подвал, лейауты, общие для целой группы страниц.
|
||||
|
||||
Сюда попадает всё, что относится к приложению целиком, а не к отдельному экрану: например, баннер
|
||||
согласия на cookie. `app` — единственный слой, который видит приложение снизу доверху, и его самого
|
||||
не импортирует никто.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Точка входа приложения
|
||||
- Маршруты и их защита
|
||||
- Глобальные провайдеры
|
||||
- Оболочка и лейауты страниц
|
||||
- Элементы, относящиеся к приложению целиком
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Конкретные страницы и их содержимое
|
||||
- Доменные данные и сценарии
|
||||
- Формы, модалки и прочие блоки интерфейса
|
||||
|
||||
## pages
|
||||
|
||||
**Общий вид страницы и расстановка блоков.**
|
||||
|
||||
`pages` отвечает за то, как страница выглядит целиком, и объявляет **хлебные крошки**. Страница
|
||||
решает, какие виджеты на ней стоят, в каком они порядке и как расположены, — и задаёт каждому
|
||||
начальные данные: идентификатор из маршрута, стартовое значение фильтра, активную вкладку.
|
||||
|
||||
Собственное состояние страницы допустимо ровно одно — то, которым страница **связывает виджеты**
|
||||
между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является
|
||||
бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит.
|
||||
|
||||
Как и модуль, страница бывает вложенной: лейаут с вкладками — это тоже `pages`, и он объявляет
|
||||
крошки за все свои вкладки, потому что только у него есть нужные для этого данные.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Композиция виджетов и их расположение на странице
|
||||
- Хлебные крошки
|
||||
- Начальные данные виджетов
|
||||
- Состояние страницы как связь между виджетами
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Бизнес-логика
|
||||
- Собственное отображение доменных данных — это дело виджетов
|
||||
- Передача сообщений между виджетами
|
||||
- Работа с API
|
||||
|
||||
## widgets
|
||||
|
||||
**Самостоятельный блок интерфейса.**
|
||||
|
||||
Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку,
|
||||
раскрытые строки. Наружу он поставляет готовый блок, а внутрь принимает только параметры —
|
||||
идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего не зная о
|
||||
том, что внутри.
|
||||
|
||||
Один виджет — один законченный участок работы: `AdminCreditsSummary` рисует карточку баланса
|
||||
платёжного аккаунта и держит диалоги лотов, броней и ручного начисления.
|
||||
|
||||
Виджет собирается из `entities` и `shared` и о других виджетах на странице не знает: связать два
|
||||
виджета — задача `pages`.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Загрузка своих данных
|
||||
- Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм
|
||||
- Композиция `entities` и `shared`
|
||||
- Действия пользователя в границах блока
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Хлебные крошки и общая раскладка страницы
|
||||
- Знание о других виджетах
|
||||
- Доменные правила
|
||||
|
||||
## entities
|
||||
|
||||
**Показ доменной сущности.**
|
||||
|
||||
Entity отвечает за то, как выглядит одна доменная сущность или одно значение: `TokenValue`
|
||||
показывает значение токенов, `SummaryRow` — строку сводки. Данные приходят пропсами; entity ничего
|
||||
не загружает и ничего не меняет. Она отвечает только за вид и форматирование того, что ей передали:
|
||||
числа, даты, статусы.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Показ одной доменной сущности или значения
|
||||
- Форматирование значения: числа, даты, статусы
|
||||
- Локальное состояние отображения
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Загрузка данных
|
||||
- Действия над сущностью: создание, изменение, удаление
|
||||
- Композиция нескольких сущностей
|
||||
- Знание о странице и о том, где entity показана
|
||||
|
||||
## shared
|
||||
|
||||
**Общий слой.**
|
||||
|
||||
`shared` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API (`shared/api`), типы,
|
||||
утилиты форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному
|
||||
сценарию.
|
||||
|
||||
Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на
|
||||
домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его
|
||||
вызвал.
|
||||
|
||||
`shared` — нижний слой: его берут все, он не берёт никого.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- UI-примитивы
|
||||
- Вызовы API
|
||||
- Типы и утилиты
|
||||
- Переводы
|
||||
- Форматирование значений
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Знание о том, где и в каком сценарии он применён
|
||||
- Композиция доменного интерфейса
|
||||
- Решения о том, что показать и что сделать при ошибке
|
||||
Reference in new issue
Block a user