Разработка

Руководство по инструментам и процессам разработки в Integ API.

Обзор инструментов

Проект использует современный стек инструментов для обеспечения качества кода и удобства разработки.

Runtime Stack

Инструмент	Версия	Назначение
NestJS	10.x	Framework
TypeScript	5.x	Язык программирования
PostgreSQL	16	База данных
TypeORM	0.3.x	ORM
Node.js	18+	Runtime

Development Tools

Инструмент	Версия	Назначение
ESLint	9	Анализ кода
Prettier	3	Форматирование
Husky	9	Git hooks
lint-staged	15	Проверка staged файлов
Jest	29	Тестирование

Authentication & Security

Инструмент	Версия	Назначение
JWT	-	Аутентификация
Passport	0.7	Стратегии аутентификации
bcryptjs	2.4	Хеширование паролей
crypto-js	4.2	Шифрование

Infrastructure

Инструмент	Назначение
Docker	Контейнеризация
Docker Compose	Оркестрация контейнеров
Doppler	Управление секретами
Sentry	Мониторинг ошибок
Redis	Кеширование

npm Scripts

Разработка

npm start              # Запуск dev сервера с hot reload
npm run build          # Сборка для production
npm run typecheck      # Проверка типов TypeScript

Линтинг и форматирование

npm run lint           # Проверка кода ESLint
npm run lint:fix       # Автоматическое исправление ошибок
npm run format         # Форматирование кода Prettier
npm run format:check   # Проверка форматирования

Удаление бойлерплейта

npm run removeComments       # Удалить комментарии
npm run removeReturnTypes    # Удалить явные return types
npm run removeComments:staged     # Для staged файлов
npm run removeReturnTypes:staged  # Для staged файлов

Тестирование

npm test              # Запустить тесты
npm run test:cov      # Запустить тесты с coverage отчетом

База данных

npm run migration:generate   # Сгенерировать миграцию
npm run migration:run        # Запустить миграции
npm run migration:revert     # Отменить последнюю миграцию
npm run typeorm              # Прямой доступ к TypeORM CLI

Docker

npm run docker:up    # Запустить контейнеры (PostgreSQL)
npm run docker:down  # Остановить контейнеры

Документация

npm run docs:dev      # Запустить VitePress dev сервер
npm run docs:build    # Собрать статическую документацию
npm run docs:preview  # Предпросмотр production build

MCP Contract Server

npm run generate:contract  # Генерировать OpenAPI контракт
npm run mcp:dev           # Запустить MCP сервер в dev режиме
npm run mcp:build         # Собрать MCP сервер для production
npm run mcp:start         # Запустить собранный MCP сервер

Утилиты

npm run depcheck       # Проверить неиспользуемые зависимости
npm run update-packages # Проверить обновления пакетов
npm run prepare        # Setup Husky hooks

Workflow разработчика

1. Подготовка

# Клонирование репозитория
git clone <repo>
cd integ-api

# Установка зависимостей
npm install

# Инициализация Husky
npm run prepare

# Запуск контейнеров (PostgreSQL, Redis)
npm run docker:up

# Генерация environment
npm run generate:env:local

# Запуск миграций
npm run migration:run

2. Разработка

# Запуск dev сервера
npm start

# Приложение доступно на http://localhost:3000
# Swagger: http://localhost:3000/api/reference
# Hot reload включен - изменения применяются автоматически

3. Перед коммитом

Автоматически (Husky pre-commit):

npm run removeComments:staged    # Удаление комментариев
npm run removeReturnTypes:staged # Удаление return types
npx pretty-quick --staged        # Prettier форматирование
npx lint-staged                  # ESLint проверка

4. Перед пушем

Автоматически (Husky pre-push):

npm run typecheck    # TypeScript проверка
npm run lint         # Полная ESLint проверка
npm run build:dev    # Тестовая сборка

5. Создание коммита

git add .
git commit -m "feat: описание изменения"
# Husky автоматически запустит pre-commit hook
# Если ошибки - исправьте и повторите git add

6. Push код

git push origin feature-branch
# Husky автоматически запустит pre-push hook
# Если ошибки - исправьте и повторите git push

Основные разделы

• Правила написания кода - Конвенции и стандарты
• Git Workflow - Husky, pre-commit, pre-push
• Линтинг - ESLint, Prettier конфигурация
• Тестирование - Jest и тесты
• MCP Contract Server - MCP сервер для интеграции с Cursor

Полезные ссылки

• Документация проекта: http://localhost:5177 (VitePress)
• API Swagger: http://localhost:3000/api/reference
• Архитектура: docs/architecture/
• API Руководство: docs/api-guide/

Troubleshooting

Приложение не запускается

# Проверить контейнеры
npm run docker:up

# Проверить миграции
npm run migration:run

# Проверить типы
npm run typecheck

# Проверить окружение
npm run generate:env:local

ESLint ошибки

# Автоматическое исправление
npm run lint:fix

# Или для staged файлов
npm run removeComments:staged
npm run removeReturnTypes:staged

Prettier конфликты

# Переформатировать все файлы
npm run format

# Или для staged файлов
npx pretty-quick --staged

Проблемы с миграциями

# Отменить последнюю
npm run migration:revert

# Выполнить заново
npm run migration:run

# Сгенерировать новую (после изменений entity)
npm run migration:generate

Следующие шаги

• Код правила - Изучить правила написания
• Git Workflow - Понять процесс коммитов
• Архитектура - Изучить архитектуру проекта