speckit: внедрение Spec Kit и фиксация архитектуры в конституции JT4D v1.0.0
CI / Сборка (push) Failing after 5s
CI / Деплой на стейджинг (push) Skipped
CI / Проверка кода (push) Skipped
CI / Документация (push) Skipped

- Интеграция 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>
This commit is contained in:
arswarog committed 2026-11-10 16:37:50 +03:00
1 parent 1d80630fb2
commit 7c60482467
55 files changed
+6070 -415

No files matched your search

+96 -22
View File
@@ -4,16 +4,32 @@
одну сторону:
```
app → pages → widgets → entities → shared
app → pages → @modules → common
```
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `shared` не знает, где
применён и по чьей воле вызван, а `entities` не знает о `widgets`.
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `common` не знает, где
применён и по чьей воле вызван, а `pages` не знает о `app`.
Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном
экземпляре, других — столько, сколько модулей.
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `entities` и `widgets` и определяет,
```
src/
├── app/
├── pages/
├── modules/
│ └── <домен>/
│ ├── widgets/
│ ├── entities/
│ └── modules/
└── common/
```
`@modules` — служебная метка места слоёв модулей в общей схеме, а не имя директории. Слои модулей
(`widgets`, `entities`) повторяются в каждом модуле на любой глубине; принадлежность к слою модуля
задаёт первое имя на пути от корня модуля.
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `widgets` и `entities` и определяет,
что из них видно снаружи, — тем же способом, каким это делает модуль в
[слоях API](01-api-layers.md). Поддомен — такая же рамка, вложенная внутрь модуля.
@@ -54,9 +70,6 @@ app → pages → widgets → entities → shared
между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является
бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит.
Как и модуль, страница бывает вложенной: лейаут с вкладками — это тоже `pages`, и он объявляет
крошки за все свои вкладки, потому что только у него есть нужные для этого данные.
**Входит:**
- Композиция виджетов и их расположение на странице
@@ -71,26 +84,26 @@ app → pages → widgets → entities → shared
- Передача сообщений между виджетами
- Работа с API
## widgets
## @modules: widgets
**Самостоятельный блок интерфейса.**
Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку,
раскрытые строки. Наружу он поставляет готовый блок, а внутрь принимает только параметры —
идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего не зная о
том, что внутри.
раскрытые строки, значения полей формы. Наружу он поставляет готовый блок, а внутрь принимает только
параметры — идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего
не зная о том, что внутри.
Один виджет — один законченный участок работы: `AdminCreditsSummary` рисует карточку баланса
платёжного аккаунта и держит диалоги лотов, броней и ручного начисления.
Один виджет — один законченный участок работы: форма входа модуля `auth` проверяет поле, держит
ошибку и статус отправки, а страница передаёт ей только различающиеся тексты.
Виджет собирается из `entities` и `shared` и о других виджетах на странице не знает: связать два
виджета — задача `pages`.
Виджет собирается из `entities` и `common` и о других виджетах на странице не знает: связать два
виджета — задача `pages`. Слои выше модуля — `pages` и `app` — виджету недоступны.
**Входит:**
- Загрузка своих данных
- Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм
- Композиция `entities` и `shared`
- Композиция `entities` и `common`
- Действия пользователя в границах блока
**Не входит:**
@@ -99,7 +112,7 @@ app → pages → widgets → entities → shared
- Знание о других виджетах
- Доменные правила
## entities
## @modules: entities
**Показ доменной сущности.**
@@ -121,19 +134,18 @@ Entity отвечает за то, как выглядит одна доменн
- Композиция нескольких сущностей
- Знание о странице и о том, где entity показана
## shared
## common
**Общий слой.**
`shared` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API (`shared/api`), типы,
утилиты форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному
сценарию.
`common` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API, типы, утилиты
форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному сценарию.
Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на
домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его
вызвал.
`shared` — нижний слой: его берут все, он не берёт никого.
`common` — нижний слой: его берут все, он не берёт никого.
**Входит:**
@@ -148,3 +160,65 @@ Entity отвечает за то, как выглядит одна доменн
- Знание о том, где и в каком сценарии он применён
- Композиция доменного интерфейса
- Решения о том, что показать и что сделать при ошибке
## Баррели: публичный 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`, страницы берут его из барреля модуля.