Files
it-smi/docs/50-developing/02-web-layers.md
T
arswarog 7c60482467
CI / Сборка (push) Failing after 5s
CI / Деплой на стейджинг (push) Skipped
CI / Проверка кода (push) Skipped
CI / Документация (push) Skipped
speckit: внедрение Spec Kit и фиксация архитектуры в конституции JT4D v1.0.0
- Интеграция Spec Kit для pi: команды `/speckit.*`, bash-скрипты и шаблоны в `.specify`
- Конституция JT4D v1.0.0 вместо шаблона: принципы WELD для слоёв web и api, публичный API
  директории
- Слои web описаны по методологии WELD и проверяются `eslint-plugin-weld`
- Vitest в api запускает `*.test.ts` рядом с `*.spec.ts`, тесты исключены из сборки приложения
- `yarn.lock` пересобран через `yarn deduplicate`

## Мотивация

Нужно зафиксировать архитектуру проекта в конституции JT4D v1.0.0 и подключить Spec Kit, чтобы
планировать фичи до написания кода.

## Ключевые моменты реализации

- `eslint-plugin-weld` настроен только в `apps/web`: схема слоёв API описана конституцией и
  документацией, но линтером пока не проверяется

Reviewed-on: jt4d/jt4d#4
Co-authored-by: Arswarog <arswarog@yandex.ru>
2026-11-10 16:37:50 +03:00

13 KiB

Слои 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. Поддомен — такая же рамка, вложенная внутрь модуля.

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 и только через него отдаёт содержимое наружу. Импорт внутреннего файла в обход барреля запрещён.

// 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:

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, страницы берут его из барреля модуля.