Files
it-smi/AGENTS.md
T
arswarog 1420aad1ae
CI / Сборка (push) Canceled after 0s
CI / Деплой на стейджинг (push) Canceled after 0s
CI / Проверка кода (push) Canceled after 0s
CI / Сборка (pull_request) Successful in 1m33s
Стенд master
CI / Деплой на стейджинг (pull_request) Successful in 8s
CI / Проверка кода (pull_request) Successful in 1m32s
Initial commit
2026-11-10 17:22:12 +03:00

9.8 KiB

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

# Все задачи через 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/<module>/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:

  • @it-smi/api/* → apps/api/src/*
  • @it-smi/web/* → apps/web/src/*

При переименовании воркспейса правятся и paths, и customConditions.

Данные для разработки

  • db-snapshot/*.json — снапшоты dev-БД для локальной разработки (см. tools/dbSnapshot.ts / dbRestore.ts).

Документация (docs/)

  • Весь новый код должен соответствовать документации в docs/. Существующий код под неё не переписывается — приводится к ней по мере того, как его всё равно затрагивают. Отдельные документы эту оговорку не повторяют
  • .md-файлы в docs/ компилируются как MDX (Docusaurus) — в обычном тексте (вне code fence ``` и вне inline-код-спанов ` `) нельзя использовать `{...}` и `<` перед небуквенным/нецифро-небуквенным символом или сразу перед словом (например, `<=`, `<lang>`, `<repo>`), иначе сборка падает с `MDX compilation failed`. Внутри code fence и inline-код-спанов такие символы безопасны — MDX не парсит их содержимое как JSX/выражения. Сравнения вида `<= N` замените на `≤ N` (аналогично `>=` → `≥`), а плейсхолдеры вроде `<lang>` — переносите в backtick-код ( <lang> ``) или переформулируйте текст

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>/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