Локальная разработка

Пакетный менеджер: npm · Задачи: Nx · Node 22

Установка

npm ci
npx prisma generate --schema=./apps/core-api/prisma/schema.prisma

Нужен доступ к PostgreSQL, а для части сервисов — Redis / RabbitMQ / S3 / SMTP. Заполни .env (см. environment).

Запуск сервисов (dev)

В package.json есть шорткаты; в общем случае — через Nx:

# через npm-скрипты
npm run dev:auth-api
npm run dev:user-api

# напрямую через Nx (любой сервис)
npx nx serve auth-api
npx nx serve user-api
npx nx serve project-api
npx nx serve admin-api
npx nx serve ai-agent-service

nx serve использует конфигурацию development (см. apps/<name>/project.json).

Сборка (prod-бандл)

npm run build:auth-api          # или: npx nx build <name>

Результат — dist/apps/<name>/main.js (запускается через node/pm2-runtime).

База данных (Prisma)

Все команды — с явным путём к схеме:

# сгенерировать клиент
npx prisma generate --schema=./apps/core-api/prisma/schema.prisma

# применить миграции (dev)
npx prisma migrate dev --schema=./apps/core-api/prisma/schema.prisma

# применить миграции (prod)
npx prisma migrate deploy --schema=./apps/core-api/prisma/schema.prisma

# посмотреть данные
npx prisma studio --schema=./apps/core-api/prisma/schema.prisma

Сиды (apps/core-api/prisma/seeds/) — см. seeds.

Тесты и линтинг

npx nx test <project>          # unit-тесты (jest), *.spec.ts
npx nx lint <project>          # eslint + границы модулей Nx
npx nx run-many -t test        # все проекты

e2e-проекты apps/*-e2e исключены из инференса jest-таргета (см. nx.json). Многие unit-таргеты настроены passWithNoTests.

Тесты по настоящей базе

Инварианты схемы, констрейнты и guard’ы авторизации проверяются не моками, а живой PostgreSQL: для этого в корне лежит docker-compose.test.yml — отдельный контейнер на порту 55432, с данными в tmpfs (контейнер поднят заново = чистая база).

npm run test:db:up             # поднять тестовую БД и дождаться healthcheck
npx nx run core-api-e2e:integration    # инварианты схемы: Restrict, CHECK, частичные индексы, сиды
npx nx run admin-api-e2e:integration   # платформенные роли и админ-поверхность команд по HTTP
npx nx run user-api-e2e:integration    # команды: доступ, жизненный цикл, приглашения, гонки
npm run test:db:down           # остановить и снести том

Строка подключения берётся из POSTGRES_URL, а при её отсутствии — из дефолта в apps/*-e2e/src/support/integration-db.ts. Если база не поднята, прогон падает с прямым указанием запустить npm run test:db:up, а не с ECONNREFUSED.

Таргет integration намеренно не входит в nx affected -t lint,test,build: обычный прогон не должен требовать Docker. Гонять его нужно отдельно — и обязательно перед сдачей работы, которая трогает схему, миграции или авторизацию.

Перед прогоном база должна содержать актуальный baseline и сиды:

export POSTGRES_URL="postgresql://crewsforge:crewsforge@localhost:55432/crewsforge_test"
npx prisma migrate deploy --schema=./apps/core-api/prisma/schema.prisma
APP_ENV=development npx nx run core-api:prisma:seed:run

⚠️ apps/core-api/.env.development указывает на удалённую базу. nx run core-api:prisma:seed:run без явно экспортированного POSTGRES_URL засеет её, а не локальную.

Полезные команды Nx

npx nx graph                   # граф зависимостей проектов
npx nx show project <name>     # доступные таргеты проекта
npx nx affected -t build       # собрать только затронутые изменениями проекты

Соответствие имён

Имя проекта Nx = последний сегмент пути. Приложения: auth-api, user-api, project-api, admin-api, ai-agent-service, core-api. Библиотеки импортируются по алиасам @crewsforge-back/... (см. conventions).