- Интеграция 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>
29 KiB
JT4D Constitution
Core Principles
I. Слои WELD на фронтенде (ОБЯЗАТЕЛЬНО)
Структура apps/web строится по методологии WELD (Well-Encapsulated Layered Design,
https://jt4d-lab.github.io/weld/): состав и порядок слоёв задаёт проект схемой WELD, а импорт
разрешён только из слоёв, стоящих ниже себя.
- Схема фронтенда:
layers: app, pages, @modules, common,moduleLayers: widgets, entities.@modules— служебная метка места слоёв модулей в общей схеме, а не имя директории. - Слои проекта существуют в единственном экземпляре и лежат директориями в корне
src. Слои модуля повторяются в каждом модуле на любой глубине; принадлежность к слою модуля задаёт первое имя на пути от корня модуля, глубже слой не ищется. - Назначение web-слоёв:
app— точка входа, маршруты и их защита, глобальные провайдеры, оболочка и лейауты;pages— общий вид страницы, композиция виджетов и хлебные крошки;widgets— самостоятельный блок со своими данными и состоянием;entities— показ и форматирование доменного значения;common— UI-примитивы, вызовы API, типы, утилиты, переводы без знания о домене и сценарии. commonне импортирует никого,appне импортирует никто, слои модулей не видятpagesиapp.- Новый слой вводится тогда, когда появляется самостоятельная архитектурная граница, а не потому, что такой слой есть в другой методологии. Осознанное отступление от направления записывается повтором слоя в схеме WELD и не остаётся побочным результатом правок.
Обоснование: единственное направление зависимостей делает изменение локальным, а границу слоя и модуля — проверяемой линтером и на ревью без чтения всего графа кода.
II. Слои API по WELD (ОБЯЗАТЕЛЬНО)
apps/api строится по той же методологии WELD со своей схемой: layers: app, @modules, common,
moduleLayers: controllers, services, dal, migrations, entities. Импорт разрешён только вниз по
схеме: app → controllers → services → dal → migrations → entities → common.
app— точка входа и сборка приложения: bootstrap, глобальные настройки, корневой модуль. Другие слои его не импортируют.controllers— контракт ручки;services— бизнес-правила, доменные ошибки и транзакции;dal— доступ к данным;migrations— миграции модуля;entities— описание таблиц.- Слой
migrationsмодуль не экспортирует, а его каталог сканирует генератор списка миграций. common— код, не принадлежащий ни одному домену: конфигурация, логирование, подключение к БД, типы, утилиты. Стоит ниже всех слоёв и не импортирует никого.- Контроллер тонкий: объявляет контракт ручки, проверяет формат входных данных и делегирует работу сервису. Бизнес-решения, транзакции и запросы к БД в нём отсутствуют.
- Контроль доступа на уровне HTTP декларативен: guards и декораторы ролей. Валидация формата
подключается пайпом на конкретный параметр, а не глобальным
ValidationPipe. - Бизнес-правила, доменные ошибки и транзакции живут в сервисе. Сервис вызывает DAL своего модуля и публичные сервисы чужих модулей.
- Модуль отдаёт наружу только явно перечисленное в
exports. Доступ к данным чужого домена — только через публичный сервис модуля-владельца. - Сущность описывает таблицу: колонки, типы, связи, индексы, имя таблицы. Методов доступа к данным и бизнес-валидации в ней нет; Active Record не используется.
- DTO описывает форму данных и валидацию формата. Собственных методов у него нет, кроме статической
фабрики
fromу response-моделей.
Обоснование: слои API задают место бизнес-правилу и запросу, поэтому изменение не расползается по контроллерам и не требует знания всего модуля. Схема WELD делает то же правило проверяемым: место миграции, сущности и запроса задано слоем, а не договорённостью.
III. Публичный API директории (ОБЯЗАТЕЛЬНО)
Директория, являющаяся границей — модуль, слой, сложный компонент из нескольких файлов, — объявляет
публичный API через index.ts и только через него отдаёт содержимое наружу.
- Импорт из чужой границы идёт строго через её баррель; импорт внутренних файлов в обход барреля запрещён.
- Баррель содержит явный список именованных реэкспортов.
export * from './...'в нём не пишется: разрешён только реэкспорт из вложенной директории, у которой уже есть собственныйindex.ts. - Баррель не содержит исполняемого кода: ни импортов стилей, ни инициализации, ни оборачивания компонентов.
- Импорт из своего или вышестоящего барреля запрещён. Внутри директории файлы импортируют друг друга только относительными путями.
- Модуль с одной точкой входа имеет корневой
index.ts. Модуль с несколькими точками входа корневого барреля не имеет, и его публичными точками входа становятся непосредственные файлы и каталоги — внутренние файлы и вложенные каталоги точками входа быть не могут. - Для тестов и вспомогательных файлов (сторибук, моки) импорт через баррель допустим: они сами не импортируются продуктовым кодом.
Обоснование: каждая строка барреля — обещание поддерживать имя, а любое расширение публичного API видно ревьюеру как правка одной строки в одном файле, поэтому детали реализации перестают быть публичным контрактом.
IV. Модули и видимость в дереве (ОБЯЗАТЕЛЬНО)
Модуль собирает код функциональной области и является рамкой для слоёв widgets и entities.
- Модули верхнего уровня лежат в
src/modules/<domain>. Вложенные модули лежат в контейнереmodules/внутри родительского модуля; контейнер слоем не является и собственного публичного API не имеет. - Видимость определяется положением в дереве: модулю доступны его предки, братья, братья предков и непосредственные дочерние модули. Остальные модули дерева недоступны — доступ к «племянникам» запрещён, потому что раскрывает внутреннюю структуру ветки.
- Правило порядка слоёв применяется ко всем модулям, включая вложенные. Единственное исключение: родительский модуль может обращаться к непосредственному дочернему модулю на том же слое, так как цикла по осям «модуль + слой» не образуется.
- Модуль публикует наружу только свой публичный API; внутренние файлы чужого модуля не импортируются даже внутри модуля-владельца.
- Дублирование логики между модулями не допускается: общая часть переносится в
commonили в модуль, доступный по дереву.
Обоснование: модули и слои — разные оси архитектуры. Дерево модулей ограничивает видимость, а слои задают направление зависимостей, поэтому цикл по модулям остаётся разрешённым, а по слоям — нет.
V. Приватность частей директории (ОБЯЗАТЕЛЬНО)
Часть директории объявляется приватной явно, а не договорённостью на словах.
- Публичный API директории — её баррель: файл, который баррель не реэкспортирует, наружу не отдаётся, и импорт его из чужой границы запрещён.
- Приватная группа файлов лежит в каталоге с точным именем
internal(вместе со всем содержимым). - Приватное доступно только содержимому непосредственного родителя. Соседние и вышестоящие директории доступа не получают.
- Владелец может опубликовать часть реализации через свой баррель, но путь приватной директории от этого не открывается.
- Приватные границы вкладываются: внешняя закрывает каталог целиком, внутренняя сужает доступ ещё сильнее.
Обоснование: приватность даёт место для деталей реализации, которые не должны становиться контрактом, не требуя для этого отдельного модуля.
VI. Доступ к данным только через DAL (ОБЯЗАТЕЛЬНО)
@InjectRepository,Repository,DataSource,QueryBuilderи прочие API TypeORM допустимы только в*.dal.ts.- Исключение ровно одно:
DataSourceвнедряется в сервис-владелец сценария и используется только радиdataSource.transaction(...). Репозитории иQueryBuilderиз него не берутся. - Транзакцию открывает сервис. DAL принимает
manager?: EntityManagerи работает с переданным контекстом; контекст передаётся явно,AsyncLocalStorageне вводится. - DAL приватен для модуля: не попадает в
exports,TypeOrmModule.forFeatureне реэкспортируется. - Мапперы не вводятся: DAL возвращает сущности как есть.
- Методы DAL добавляются под конкретный запрос вызывающего кода. API «на будущее» не пишется.
- Внешние вызовы — HTTP, SMTP, очереди — выполняются после коммита транзакции.
- Логика, которую необходимо выполнять на стороне БД (агрегаты, массовые
UPDATE/upsert, выборки с блокировкой, оконные функции), живёт в DAL.
Обоснование: сервис не зависит от способа выборки, поэтому замена запроса, добавление join'а или кэша остаётся в одном файле и не задевает бизнес-логику.
VII. Схема БД меняется только миграцией (ОБЯЗАТЕЛЬНО)
synchronize: false,migrationsRun: false. Единственный способ изменить схему — миграция.- Миграция лежит в слое
migrationsсвоего модуля (apps/api/src/<module>/migrations/). Имя файла начинается с 13-значного timestamp, имя класса оканчивается тем же timestamp. downпишется всегда. Необратимая операция оформляется либо броском ошибки вdown, либо откатом с потерей данных — выбор фиксируется комментарием.- DDL пишется методами
QueryRunner(Table,TableColumn), а не строкой SQL.queryRunner.query()допустим там, где API TypeORM нужную конструкцию не выражает, и сопровождается комментарием. - Имя таблицы в миграции — строковый литерал, а не константа
*_TABLE_NAME. - Изменение схемы и перенос данных — разные файлы.
- Data-миграции не переносят секреты и персональные данные литералами: SQL миграций попадает в лог job деплоя.
- После добавления или удаления миграции
apps/api/src/migrations.tsперегенерируется и коммитится вместе с ней. - Миграция считается проверенной после цикла
db-migrate→db-revert→db-migrate.
Обоснование: миграция — воспроизводимый и откатываемый снимок схемы; автозапуск и ручные правки БД оставляют прод и репозиторий в расхождении, которое следующий деплой только обостряет.
VIII. Тесты рядом с кодом
- Юнит-тест лежит рядом с тестируемым файлом, отдельной папки под тесты нет. Расширение —
.test.ts(.test.tsxдля React-компонентов). - Тестируется бизнес-логика сервиса с замоканным DAL.
- DAL не покрывается юнит-тестами: тест с замоканным репозиторием проверяет сам себя. Логика, выполняемая в БД, проверяется на реальной базе.
- Тест может импортировать тестируемую границу через её баррель: это снижает зависимость от внутреннего расположения файлов.
- Тесты запускаются через Nx:
yarn nx run api:test,yarn nx run web:test,yarn nx affected -t test.
Обоснование: тест описывает контракт поведения, а не структуру вызовов, поэтому переезд деталей выборки внутрь DAL не требует переписывать тесты.
IX. Документация — контракт
docs/— источник истины для слоёв, модулей, БД, миграций, логирования и деплоя. Новый код соответствует документации.- Концепции WELD (публичный API директории, однонаправленность зависимостей, модули, вложенные
модули) — источник истины для устройства слоёв и модулей;
docs/описывает их применение к этому проекту и не переопределяет. - Изменение поведения, расходящееся с документацией, включает её правку в ту же задачу.
- Документация в
docs/компилируется как MDX: вне code fence и inline-кода{...}и<перед словом или небуквенным символом запрещены; сравнения пишутся через≤и≥. - Комментарий в коде сообщает только существенный факт, который нельзя вывести из кода рядом, имён, типов и сигнатур. Пересказ кода и обоснование принятого решения комментарием не оформляется.
AGENTS.mdподдерживается в актуальном состоянии по командам, архитектуре и конвенциям.
Обоснование: документация и код изменяются одной задачей, иначе расхождение становится источником неверных решений у следующего автора.
X. Задачи только через Nx
- Задачи (build, test, lint, serve, миграции) запускаются через
yarn nx run,run-many,affected. Прямые вызовы jest, vitest, eslint, webpack и typeorm CLI допустимы только там, где это описано в документации (например,migration:generateс обязательными переменными окружения). - Границы слоёв и модулей проверяются правилами WELD в составе lint. Исключение не оформляется комментарием в коде и не отключается на месте: оно вносится в схему WELD как повтор слоя.
yarn lint:checkпроходит до коммита. Хуки pre-commit и pre-push не обходятся через--no-verify.- Имя ветки соответствует шаблону
i<номер>-<краткое-описание>; проверка выполняетсяvalidate-branch-nameна pre-push. - Сгенерированные файлы, от которых зависит сборка (
apps/api/src/migrations.ts), коммитятся в том виде, в котором их создал генератор.
Обоснование: Nx знает граф зависимостей и кэш, поэтому обход Nx даёт локально зелёный результат, который падает в CI.
XI. Структурное логирование с явным контекстом
- Логгер внедряется через dependency injection. Контекст задаётся явно через
setContext(). - Контекст — имя модуля (
Brands,Users); при уточнении добавляется второй уровень через двоеточие (Brands:Passport). Технические роли (Service,Controller) в контексте не употребляются. - Уровень выбирается по значимости события. В dev — человекочитаемый вывод и
debug, в prod — JSON иinfo; переопределение черезLOG_LEVELиLOG_PRETTY. - Чувствительные данные в логи не попадают.
reqIdвнутри HTTP-запроса не дублируется вdetails.
Обоснование: единый формат и стабильный контекст — условие того, что логи остаются пригодными для диагностики инцидента, а не только для отладки рядом с консолью.
Constraints
- Стек фиксирован: Nx 22, yarn 1 workspaces, TypeScript 5.9, Node 24;
api— NestJS 11 + TypeORM + PostgreSQL + webpack + Vitest;web— React 19 + Vite 7 + Tailwind 3.4 + Caddy, архитектура — WELD; e2e — Jest; логи — Pino черезnestjs-pino. - UI-примитивы фронтенда — исходники shadcn/ui на Radix (
class-variance-authority,clsx,tailwind-merge,lucide-react,tailwindcss-animate,@radix-ui/react-*), скопированные вapps/web/src/common/ui. Tailwind при этом остаётся 3.4. - Схемы слоёв WELD —
layersиmoduleLayersдля фронтенда и для API — единственное место, где объявлены состав и порядок слоёв. Списки слоёв не дублируются в конфигурации ESLint и в правилах Nx. Добавление, разделение или удаление слоя — правка схемы WELD, а не набора исключений. - Введение WELD не отменяет ранее принятых правил: слои API (
Controller → Service → DAL), доступ к данным только через DAL, миграции, тесты, документация, Nx и логирование действуют в полном объёме. Новый принцип применяется к своей части кода и не заменяет соседний. - Проверка границ: правила WELD из
eslint-plugin-weldпо схеме изapps/web/weld.config.mjs. Пока плагин не умеет проверять направление слоёв, направление держится ревью, а такое расхождение считается временным состоянием, а не альтернативной настройкой. - Замена или добавление элемента стека оформляется отдельным решением и обновлением этого раздела.
- Общие библиотеки кладутся в
packages/; дублирование логики между приложениями не допускается. - Настройки окружения читаются из
.envи переменных окружения. Секреты и реальные данные в репозиторий не коммитятся. - Схема прод-БД не синхронизируется рантаймом, автоматического бэкапа перед миграцией нет: перед рискованной операцией снимается ручной дамп, и на свежую копию при разборе инцидента не рассчитывают.
- Стейджинг и прод изменяются пайплайном (
.gitea/workflows/ci.yaml,production.yaml,cleanup.yaml). Ручные правки схемы мимо миграций запрещены. - Изменения на удалённых окружениях выполняются после явного разрешения на конкретную правку: сначала показываются команды и дифф, затем применение. Разрешение на одну правку не распространяется на соседние и на повторный запуск.
Development Workflow
- Изменение проходит путь specify → plan → tasks → implement. Соответствие конституции проверяется на шаге плана (Constitution Check).
- Готовность задачи:
yarn lint:checkзелёный (включая проверку границ WELD), затронутые тесты проходят, при изменении схемы выполнен цикл накат → откат → накат, документация обновлена. - Изменение схемы слоёв или появление модуля — событие архитектуры: схема WELD и
docs/правятся в той же задаче, что и код. - CI — обязательный шлюз.
Check migrations listиCheck data-sourceпроходят до сборки образов; ветка с падающим CI не мержится. - Деплой применяет миграции автоматически (
migration:run -t each). Ручное вмешательство в общую БД выполняется по runbook черезdocker exec, после решения о необходимости и с учётом того, что автоматического бэкапа нет. - Ревью PR включает проверку принципов; отклонение фиксируется в плане или решении с причиной и сроком устранения, а не молчаливым исключением.
Governance
- Конституция выше остальных практик. Для нового кода приоритет у конституции; существующий код приводится к ней по мере того, как его затрагивают.
- Поправка вносится так: предложение с формулировкой принципа и обоснованием → ревью владельцем
репозитория → обновление этого файла и, при необходимости,
docs/. - Версионирование по semantic versioning: MAJOR — удаление или переопределение принципа, MINOR — новый принцип или раздел, PATCH — уточнение формулировки без изменения смысла.
- Каждая поправка обновляет строку версии, дату последней правки и Sync Impact Report. Отчёт — рабочий материал ревью, перед коммитом он удаляется.
- Соответствие проверяется на ревью PR и в плане задачи. Нарушение без зафиксированного обоснования блокирует мерж.
- Неоднозначный случай трактуется в пользу ограничения, а не обхода; принятое решение фиксируется в
docs/.
Version: 1.0.0 | Ratified: 2026-11-05 | Last Amended: 2026-11-08