- Интеграция 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>
225 lines
13 KiB
Markdown
225 lines
13 KiB
Markdown
# Слои 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`, страницы берут его из барреля модуля.
|