BackendTest – NestJS + Knex + PostgreSQL

API de produtos e pedidos com autenticação JWT, documentação Swagger e uma suíte de 10 testes principais.

Stack

• Node.js 18+, TypeScript, NestJS
• PostgreSQL + Knex (sem ORMs)
• Jest com suíte enxuta (10 testes principais)
• Swagger em /docs

Como rodar localmente

1. Instale dependências

npm install

2. Configure o .env (use .env.example como base)
   Valores padrão para dev:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=backendtest
DB_USER=postgres
DB_PASSWORD=postgres
JWT_SECRET=super-secret
ADMIN_USER=admin
ADMIN_PASSWORD=admin

3. Suba o banco e aplique migrations/seeds

# se já houver Postgres local rodando, pule para migrations/seeds
docker-compose up -d db
npm run migration:latest
npm run seed:run

4. Rode em modo dev

npm run dev
# ou produção
npm run build && npm run start:prod

Docker (API + Postgres)

docker-compose up --build

Expõe a API em http://localhost:3000 e o Swagger em http://localhost:3000/docs.

Scripts úteis

• npm run dev – start com reload
• npm run build / npm run start:prod
• npm run migration:latest / npm run migration:rollback
• npm run seed:run
• npm run test / npm run test:cov (suíte enxuta)
• npm run lint / npm run format

Autenticação

• Endpoint: POST /auth/login
• Payload: { "username": "admin", "password": "admin" } (ajuste conforme .env)
• Resposta: { "access_token": "..." }
• Use Authorization: Bearer <token> em todos os endpoints de produtos/pedidos.

Endpoints principais

Products

• POST /products – cria produto

  {
    "name": "Caderno",
    "category": "Papelaria",
    "description": "200 folhas",
    "price": 25.5,
    "stockQuantity": 100
  }

• GET /products – lista
• GET /products/:id – detalhe
• PUT /products/:id – atualiza
• DELETE /products/:id – remove

Orders

• POST /orders – cria pedido

  {
    "status": "Concluído",
    "items": [
      { "productId": "11111111-1111-1111-1111-111111111111", "quantity": 2 }
    ]
  }

  Regras:
  • Status aceitos: Pendente (default), Concluído, Cancelado
  • Sempre valida estoque; se Concluído, estoque é baixado na mesma transação.
  • total_amount é a soma de line_total (preço congelado no momento da compra).
• GET /orders
• GET /orders/:id

Swagger

• Acesse /docs após subir a API.
• Documentação inclui exemplos, tags (Auth, Products, Orders) e bearer auth configurado.

Banco de dados

• IDs em UUID para evitar colisão entre ambientes/seeds e facilitar replicação.
• Tabelas: products, orders, order_items (migrations em migrations/20240424120000_init_schema.ts).
• Seeds iniciais em seeds/initial_products.ts (dois produtos prontos para testar).

Arquitetura e SOLID

• Camadas: controller → service (use-case) → repository.
• DIP: services dependem de interfaces via tokens (PRODUCT_REPOSITORY, ORDER_REPOSITORY, TRANSACTION_MANAGER).
• LSP/ISP: Repositórios in-memory e Knex implementam as mesmas interfaces; contratos focados em cada agregado.
• SRP: casos de uso separados (ex.: CreateOrderService, UpdateProductService).
• OCP: políticas extensíveis (OrderStatusPolicy) isolam regras de status/estoque.

Testes

• Suíte reduzida com 10 testes principais cobrindo fluxo happy-path e validações centrais.
• npm run test roda tudo; npm run test:cov continua disponível, porém sem meta de cobertura total.

Exemplo de fluxo rápido

cp .env.example .env
docker-compose up --build   # sobe db + api
# autenticar
curl -X POST http://localhost:3000/auth/login -d '{"username":"admin","password":"admin"}' -H "Content-Type: application/json"
# usar token nas chamadas seguintes

Observações

• Middleware global de log (RequestLoggerMiddleware) registra method path -> status (ms) sem logar corpo ou credenciais.
• Migrations habilitam uuid-ossp para geração de UUID no Postgres.