Promo Codes REST API

REST API для управления промокодами и их активацией с фокусом на целостность данных в PostgreSQL.

Стек

• Node.js + TypeScript
• Fastify
• Prisma ORM
• PostgreSQL
• Vitest

Возможности

• CRUD (реализовано: create, get by id, list) для промокодов
• Активация промокода по email
• Email может активировать конкретный промокод только один раз
• Защита от активации сверх лимита
• Проверка срока действия промокода

Архитектура

Код разделен по модулям:

• src/modules/promo - все, что относится к домену промокодов (типы, сервис, репозиторий, роуты, JSON Schema)
• src/shared - общие зависимости (например, Prisma client)

Гарантии целостности данных

На уровне БД:

• UNIQUE (promo_codes.code)
• UNIQUE (promo_activations.promo_code_id, promo_activations.email)
• CHECK (discount_percent BETWEEN 1 AND 100)
• CHECK (activation_limit > 0)
• CHECK (activated_count >= 0)

На уровне бизнес-логики:

• Активация выполняется в prisma.$transaction(...)
• Используется SELECT ... FOR UPDATE для блокировки строки промокода и защиты от race condition
• После успешной записи активации счетчик activated_count инкрементируется внутри той же транзакции

Запуск

1) Установить зависимости

npm install

2) Поднять PostgreSQL через Docker Compose

docker compose up -d

Проверить статус:

docker compose ps

3) Настроить переменные окружения

cp .env.example .env

4) Применить миграции и сгенерировать Prisma Client

npm run prisma:migrate
npm run prisma:generate

5) Запустить сервис

npm run dev

Остановить PostgreSQL

docker compose down

Тесты

npm test

API

Create promo code

POST /promo-codes

{
  "code": "SPRING15",
  "discountPercent": 15,
  "activationLimit": 100,
  "expiresAt": "2026-12-31T23:59:59.000Z"
}

Get promo code by id

GET /promo-codes/:id

List promo codes

GET /promo-codes?limit=20&offset=0

Activate promo code

POST /promo-codes/:code/activate

{
  "email": "user@example.com"
}

Основные статусы ответов

• 201 - создано / активировано
• 200 - успешный запрос
• 404 - промокод не найден
• 409 - лимит исчерпан или email уже активировал код
• 410 - промокод истек
• 400 - ошибка валидации