# AGENTS.md Инструкции для ИИ-агентов при работе с этим репозиторием: обзор, команды, архитектура и конвенции, которые нельзя вывести из кода. ## Project Overview Монорепозиторий Nx с тремя приложениями: - **api** — NestJS бэкенд (TypeORM + PostgreSQL), порт 5000, глобальный префикс `/api`, Swagger UI на `/api/docs` - **web** — React фронтенд (Vite), порт 5173, проксирует `/api/*` на бэкенд - **api-e2e** — E2E-тесты на Jest для API Package manager: **yarn** (v1 classic). Версия указана в поле `packageManager` в `package.json`. Все задачи запускаются через Nx, а не напрямую через инструменты. ## Common Commands ```bash # Все задачи через Nx (не напрямую) yarn nx run api:serve # Запуск бэкенда yarn nx run web:serve # Запуск фронтенда yarn nx run-many -t serve # Запуск всех приложений yarn nx run api:build # Сборка бэкенда (webpack) yarn nx run web:build # Сборка фронтенда (vite) yarn nx run api:test # Тесты бэкенда (vitest) yarn nx run web:test # Тесты фронтенда (vitest) yarn nx run api:test -- --testPathPattern="users" # Один тест-файл yarn nx run api-e2e:e2e # E2E-тесты yarn nx run api:lint # ESLint для api yarn nx run web:lint # ESLint для web yarn lint # ESLint + Prettier для всего (с автофиксом) yarn lint:check # Проверка без автофикса yarn nx run api:db-show # Список миграций и их статус yarn nx run api:db-migrate # Применить непримененные миграции yarn nx run api:db-migrations-list # Перегенерировать список миграций ``` ## Architecture ### Backend (apps/api) - NestJS модульная архитектура: модуль — рамка, внутри которой код разложен по слоям `Controller → Service → Data Access Layer`; наружу модуль отдаёт только то, что осознанно экспортирует. Подробности — `docs/50-developing/01-api-layers.md` - Swagger UI доступен на `/api/docs` - Сборка: `db-migrations-list` (через `dependsOn`) → `webpack-cli build` (`main.js`) → `webpack-cli build --config webpack.data-source.config.js` (`data-source.js`), последовательно (`parallel: false`). Запуск через `@nx/js:node` #### Миграции БД - Миграции лежат по модулям: `apps/api/src//migrations/` - Список миграций **генерируется статически** (`tools/buildDataSource.ts` сканирует `apps/api/src/**/migrations/` → `apps/api/src/migrations.ts`), потому что webpack не умеет runtime-glob - Имя файла обязано начинаться с **13-значного** timestamp, а имя класса — оканчиваться тем же timestamp: TypeORM берёт его как `parseInt(className.substr(-13))`. Расхождение валит сборку - **После добавления или удаления миграции список нужно перегенерировать и закоммитить** (`yarn nx run api:db-migrations-list`, либо это сделает `yarn nx run api:build` через `dependsOn`). Иначе CI упадёт на шаге `Check migrations list` - Деплой применяет миграции автоматически (`migration:run -t each` через `docker exec` на проде / `docker compose exec` на стейджинге) — на каждый тег на проде и на каждый push/PR на стейджинге. Автоматического бэкапа перед миграцией нет. Подробнее: `docs/90-deploy/10-migrations.md` - DDL пишется методами `QueryRunner` (`Table`/`TableColumn`), а не строкой SQL; вывод `migration:generate` — черновик, который переписывают. `down` обязателен. Имя таблицы — строковым литералом, а не константой `*_TABLE_NAME`: миграция не должна ломаться от удаления модуля. Data-миграции — отдельным файлом. Перед коммитом — цикл `db-migrate` → `db-revert` → `db-migrate`. Подробнее: `docs/50-developing/20-migrations.md` #### Конвенции кода и тестов Подробности — `docs/50-developing/`: - Сущности — в `entities/` внутри модуля; имя таблицы — константа `*_TABLE_NAME` рядом с сущностью (в коде приложения используется везде, в миграциях — нет); колонки — `camelCase` - Весь доступ к БД — в `*.dal.ts`: `@InjectRepository`/`Repository`/`DataSource` допустимы только там. DAL приватен для модуля (не в `exports`), наружу модуль отдаёт публичные сервисы - Тесты — рядом с тестируемым файлом, расширение `.test.ts`; DAL юнит-тестами не покрывается ### Frontend (apps/web) - React + Vite + React Router; стили — Tailwind CSS - Слои идут строго в одну сторону: `app → pages → @modules → common`; `widgets` и `entities` существуют только внутри модуля, обратные зависимости запрещены. Границы объявляются баррелями, схема слоёв — в `apps/web/weld.config.mjs`. Подробности — `docs/50-developing/02-web-layers.md` - Оболочка, шапка и тема — `docs/50-developing/04-ui-shell.md` - Тесты: Vitest с jsdom ### TypeScript Paths Определены в `tsconfig.base.json`: - `@jt4d-platform/api/*` → `apps/api/src/*` - `@jt4d-platform/web/*` → `apps/web/src/*` При переименовании воркспейса правятся и `paths`, и `customConditions`. ## Данные для разработки - `db-snapshot/*.json` — снапшоты dev-БД для локальной разработки (см. `tools/dbSnapshot.ts` / `dbRestore.ts`). ## Документация (`docs/`) - **Весь новый код должен соответствовать документации в `docs/`.** Существующий код под неё не переписывается — приводится к ней по мере того, как его всё равно затрагивают. Отдельные документы эту оговорку не повторяют - `.md`-файлы в `docs/` компилируются как MDX (Docusaurus) — в обычном тексте (вне code fence ` ``` ` и вне inline-код-спанов `` ` `` `` `) нельзя использовать `{...}` и `<` перед небуквенным/нецифро-небуквенным символом или сразу перед словом (например, `<=`, ``, ``), иначе сборка падает с `MDX compilation failed`. Внутри code fence и inline-код-спанов такие символы безопасны — MDX не парсит их содержимое как JSX/выражения. Сравнения вида `<= N` замените на `≤ N` (аналогично `>=` → `≥`), а плейсхолдеры вроде `` — переносите в backtick-код (`` `` ``) или переформулируйте текст ## Code Quality - ESLint 9 flat config (корневой `eslint.config.mjs`) - Prettier для форматирования - Husky + lint-staged: автоформатирование при коммите - `@nx/enforce-module-boundaries` включён ## General Guidelines for working with Nx - For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns for querying projects, targets, and dependencies - When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly - Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`, `npm exec nx test`) - avoids using globally installed CLI - You have access to the Nx MCP server and its tools, use them to help the user - For Nx plugin best practices, check `node_modules/@nx//PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable. - NEVER guess CLI flags - always check nx_docs or `--help` first when unsure ## Scaffolding & Generators - For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the `nx-generate` skill FIRST before exploring or calling MCP tools ## When to use nx_docs - USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases - DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you already know - The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look up generator syntax