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>
This commit is contained in:
1 parent
1d80630fb2
commit
7c60482467
55 files changed
+6070
-415
No files matched your search
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"sha256": "ce7549540fa45543cca797a150201d868e64495fdff39dc38246fb17bd4024b3",
|
||||
"source": "core"
|
||||
}
|
||||
@@ -0,0 +1,283 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user