# 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/`. Вложенные модули лежат в контейнере `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//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