# Слои web `apps/web` — React-приложение. Его код разложен по слоям, и зависимости между слоями идут строго в одну сторону: ``` app → pages → @modules → common ``` Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `common` не знает, где применён и по чьей воле вызван, а `pages` не знает о `app`. Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном экземпляре, других — столько, сколько модулей. ``` src/ ├── app/ ├── pages/ ├── modules/ │ └── <домен>/ │ ├── widgets/ │ ├── entities/ │ └── modules/ └── common/ ``` `@modules` — служебная метка места слоёв модулей в общей схеме, а не имя директории. Слои модулей (`widgets`, `entities`) повторяются в каждом модуле на любой глубине; принадлежность к слою модуля задаёт первое имя на пути от корня модуля. **Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `widgets` и `entities` и определяет, что из них видно снаружи, — тем же способом, каким это делает модуль в [слоях API](01-api-layers.md). Поддомен — такая же рамка, вложенная внутрь модуля. ## app **Точка входа и оболочка.** `app` — внешний край приложения. Он монтирует React, объявляет маршруты и их защиту, держит глобальные провайдеры и рисует оболочку: шапку, подвал, лейауты, общие для целой группы страниц. Сюда попадает всё, что относится к приложению целиком, а не к отдельному экрану: например, баннер согласия на cookie. `app` — единственный слой, который видит приложение снизу доверху, и его самого не импортирует никто. **Входит:** - Точка входа приложения - Маршруты и их защита - Глобальные провайдеры - Оболочка и лейауты страниц - Элементы, относящиеся к приложению целиком **Не входит:** - Конкретные страницы и их содержимое - Доменные данные и сценарии - Формы, модалки и прочие блоки интерфейса ## pages **Общий вид страницы и расстановка блоков.** `pages` отвечает за то, как страница выглядит целиком, и объявляет **хлебные крошки**. Страница решает, какие виджеты на ней стоят, в каком они порядке и как расположены, — и задаёт каждому начальные данные: идентификатор из маршрута, стартовое значение фильтра, активную вкладку. Собственное состояние страницы допустимо ровно одно — то, которым страница **связывает виджеты** между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит. **Входит:** - Композиция виджетов и их расположение на странице - Хлебные крошки - Начальные данные виджетов - Состояние страницы как связь между виджетами **Не входит:** - Бизнес-логика - Собственное отображение доменных данных — это дело виджетов - Передача сообщений между виджетами - Работа с API ## @modules: widgets **Самостоятельный блок интерфейса.** Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку, раскрытые строки, значения полей формы. Наружу он поставляет готовый блок, а внутрь принимает только параметры — идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего не зная о том, что внутри. Один виджет — один законченный участок работы: форма входа модуля `auth` проверяет поле, держит ошибку и статус отправки, а страница передаёт ей только различающиеся тексты. Виджет собирается из `entities` и `common` и о других виджетах на странице не знает: связать два виджета — задача `pages`. Слои выше модуля — `pages` и `app` — виджету недоступны. **Входит:** - Загрузка своих данных - Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм - Композиция `entities` и `common` - Действия пользователя в границах блока **Не входит:** - Хлебные крошки и общая раскладка страницы - Знание о других виджетах - Доменные правила ## @modules: entities **Показ доменной сущности.** Entity отвечает за то, как выглядит одна доменная сущность или одно значение: `TokenValue` показывает значение токенов, `SummaryRow` — строку сводки. Данные приходят пропсами; entity ничего не загружает и ничего не меняет. Она отвечает только за вид и форматирование того, что ей передали: числа, даты, статусы. **Входит:** - Показ одной доменной сущности или значения - Форматирование значения: числа, даты, статусы - Локальное состояние отображения **Не входит:** - Загрузка данных - Действия над сущностью: создание, изменение, удаление - Композиция нескольких сущностей - Знание о странице и о том, где entity показана ## common **Общий слой.** `common` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API, типы, утилиты форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному сценарию. Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его вызвал. `common` — нижний слой: его берут все, он не берёт никого. **Входит:** - UI-примитивы - Вызовы API - Типы и утилиты - Переводы - Форматирование значений **Не входит:** - Знание о том, где и в каком сценарии он применён - Композиция доменного интерфейса - Решения о том, что показать и что сделать при ошибке ## Баррели: публичный API границы Граница — модуль, слой, сложный компонент из нескольких файлов — объявляет публичный API через `index.ts` и только через него отдаёт содержимое наружу. Импорт внутреннего файла в обход барреля запрещён. ```ts // apps/web/src/common/index.ts export * from './lib'; export * from './ui'; // apps/web/src/common/lib/index.ts export { applyTheme, getTheme, subscribeToTheme, toggleTheme, type Theme } from './theme'; export { cn } from './utils'; ``` Правила барреля: - Только явный список именованных реэкспортов. `export *` допустим лишь от вложенной директории, у которой уже есть собственный `index.ts`. - Никакого исполняемого кода: ни импортов стилей, ни инициализации, ни оборачивания компонентов. - Импорт из своего или вышестоящего барреля запрещён; внутри директории файлы импортируют друг друга относительными путями. Межграничный импорт идёт через алиас `@jt4d-platform/web/*`, который объявлен в `tsconfig.base.json` и разрешается в `vite.config.ts` через `resolve.alias`: ```ts import { Button, usePageBreadcrumbs } from '@jt4d-platform/web/common'; import { AuthForm } from '@jt4d-platform/web/modules/auth'; import { HealthPage } from '@jt4d-platform/web/pages'; ``` Обход барреля ловится линтером правилом `weld/no-barrel-bypass` из `eslint-plugin-weld`; оно включено в `apps/web/eslint.config.mjs`. ## Приватность частей директории Часть директории объявляется приватной явно, а не договорённостью на словах: - публичный API директории — её баррель: файл, который баррель не реэкспортирует, наружу не отдаётся; - приватная группа файлов лежит в каталоге с точным именем `internal` вместе со всем содержимым; - приватное доступно только содержимому непосредственного родителя; - владелец может опубликовать часть реализации через свой баррель, но путь приватной директории от этого не открывается. Пример — хук формы входа: `modules/auth/widgets/auth-form/useAuthForm.ts`. Он используется компонентом `AuthForm.tsx` из той же директории и не попадает в баррель виджета. ## Модули и видимость Модули верхнего уровня лежат в `src/modules/<домен>`, вложенные — в контейнере `modules/` внутри родительского модуля. Контейнер слоем не является и собственного публичного API не имеет. Видимость определяется положением в дереве: модулю доступны его предки, братья, братья предков и непосредственные дочерние модули. Доступ к «племянникам» запрещён: он раскрывает внутреннюю структуру ветки. Дублирование логики между модулями не допускается — общая часть переносится в `common` или в модуль, доступный по дереву. Пример: `modules/auth` отдаёт наружу только `AuthForm`, страницы берут его из барреля модуля.