- Интеграция 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>
284 lines
29 KiB
Markdown
284 lines
29 KiB
Markdown
# 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
|