Files
it-smi/.specify/memory/constitution.md
T
arswarog 257c044e5f
CI / Сборка (push) Failing after 4s
CI / Деплой на стейджинг (push) Skipped
CI / Проверка кода (push) Skipped
CI / Сборка (pull_request) Successful in 1m46s
CI / Деплой на стейджинг (pull_request) Failing after 2s
CI / Проверка кода (pull_request) Successful in 1m17s
it-smi
2026-11-10 16:55:11 +03:00

284 lines
29 KiB
Markdown

# 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