Files
it-smi/.specify/memory/constitution.md
T
arswarog 24df6221b3
CI / Сборка (push) Canceled after 0s
CI / Деплой на стейджинг (push) Canceled after 0s
CI / Проверка кода (push) Canceled after 0s
CI / Сборка (pull_request) Successful in 1m27s
Стенд master
CI / Деплой на стейджинг (pull_request) Successful in 7s
CI / Проверка кода (pull_request) Successful in 1m14s
it-smi
2026-11-10 17:08:59 +03:00

29 KiB

it-smi 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