Setup do Projeto — Backend

Pré-requisitos:

Node.js v20 ou superior
npm v10+
Docker Desktop instalado e rodando
Git

1. Clonar o repositório

git clone <url-do-repositorio>
cd hub-marketplace-backend

2. Subir a infraestrutura local (Docker)

O projeto usa PostgreSQL 15 e Redis como dependências. O jeito mais rápido de tê-los rodando é via Docker Compose, cujo arquivo está na pasta docker/ na raiz do monorepo:

# Da raiz do monorepo (pasta Fonte/)
docker compose -f docker/docker-compose.yml up -d

Isso sobe dois containers:

Container	Imagem	Porta	Credenciais padrão
`hub_postgres`	postgres:15	`5432`	user: `hub_user` / pass: `hub_pass` / db: `hub_db`
`hub_redis`	redis:latest	`6379`	sem senha (desenvolvimento local)

Para parar os containers sem apagar os dados: docker compose -f docker/docker-compose.yml stopPara apagar tudo (incluindo volumes): docker compose -f docker/docker-compose.yml down -v

3. Instalar dependências

npm install

4. Configurar variáveis de ambiente

Copie o arquivo de exemplo:

cp .env.example .env

Edite o .env com os valores corretos para seu ambiente:

# ─── Banco de dados ───────────────────────────────────────
DB_HOST=localhost
DB_PORT=5432
DB_USER=hub_user
DB_PASS=hub_pass
DB_NAME=hub_db

# ─── Aplicação ────────────────────────────────────────────
APP_PORT=3000

# ─── Redis ────────────────────────────────────────────────
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=                  # Deixar vazio em desenvolvimento local

# ─── Segurança ────────────────────────────────────────────
JWT_SECRET=algum_segredo_forte_aqui
TOKEN_ENCRYPTION_KEY=chave_de_32_caracteres_aqui

# ─── Mercado Livre OAuth ───────────────────────────────────
MERCADO_LIVRE_API_URL=https://api.mercadolibre.com
ML_REDIRECT_URI=http://localhost:3000/integrations/mercadolivre/callback
ML_CLIENT_ID=
ML_CLIENT_SECRET=

# ─── CORS ─────────────────────────────────────────────────
FRONTEND_URL=http://localhost:3001

# ─── E-mail (Resend) ──────────────────────────────────────
RESEND_API_KEY=re_sua_chave_aqui
EMAIL_FROM=OmniDom <no-reply@send.domsoftware.com.br>

As variáveis JWT_SECRET e TOKEN_ENCRYPTION_KEY são críticas para segurança. Use valores aleatórios e longos. Nunca compartilhe os valores de produção.

Referência completa de variáveis

Variável	Obrigatória	Descrição
`DB_HOST`	✅	Host do PostgreSQL
`DB_PORT`	✅	Porta do PostgreSQL (padrão: `5432`)
`DB_USER`	✅	Usuário do banco
`DB_PASS`	✅	Senha do banco
`DB_NAME`	✅	Nome do banco de dados
`APP_PORT`	✅	Porta em que a API vai escutar (padrão: `3000`)
`REDIS_HOST`	✅	Host do Redis (filas BullMQ)
`REDIS_PORT`	✅	Porta do Redis (padrão: `6379`)
`REDIS_PASSWORD`		Senha do Redis (deixar vazio em dev local)
`JWT_SECRET`	✅	Segredo para assinar os JWT de acesso
`TOKEN_ENCRYPTION_KEY`	✅	Chave AES para criptografar tokens OAuth de terceiros
`MERCADO_LIVRE_API_URL`	✅	URL base da API do Mercado Livre
`ML_REDIRECT_URI`	✅	URI de callback OAuth do Mercado Livre
`ML_CLIENT_ID`		App ID do Mercado Livre (necessário para integração)
`ML_CLIENT_SECRET`		App Secret do Mercado Livre
`FRONTEND_URL`	✅	URL do frontend — usada na política de CORS
`RESEND_API_KEY`		API key do Resend para envio de e-mails
`EMAIL_FROM`		Remetente padrão dos e-mails transacionais

5. Executar as migrations

O banco começa vazio. As migrations criam todas as tabelas:

npm run migration:run

As migrations lêem as variáveis do .env automaticamente via dotenv. Certifique-se de que o banco está acessível antes de rodar.

6. Rodar em desenvolvimento

npm run start:dev

A API estará disponível em http://localhost:3000 (ou na porta definida em APP_PORT). O servidor reinicia automaticamente ao detectar mudanças nos arquivos (modo --watch).

7. Verificar se está funcionando

Acesse a documentação Swagger gerada automaticamente:

http://localhost:3000/api

Você verá todos os endpoints documentados e poderá testar chamadas direto pelo browser.

Comandos disponíveis

Comando	O que faz
`npm run start:dev`	Desenvolvimento com hot reload
`npm run start:debug`	Desenvolvimento com debugger Node.js em modo watch
`npm run build`	Compila o TypeScript para `dist/`
`npm run start:prod`	Roda o build compilado (produção)
`npm run migration:generate -- --name=NomeDaAlteracao`	Gera migration a partir das entities
`npm run migration:run`	Executa migrations pendentes
`npm run migration:revert`	Reverte a última migration
`npm run migration:show`	Lista o status de todas as migrations
`npm run test`	Roda testes unitários
`npm run test:e2e`	Roda testes end-to-end
`npm run test:cov`	Testes com relatório de cobertura
`npm run lint`	ESLint com auto-fix
`npm run format`	Prettier em todos os arquivos `src/`
`npm run email`	Preview dos templates de e-mail (React Email)

Migrations

O projeto usa TypeORM com migrations para controle de esquema. O synchronize está desabilitado — nunca altere o banco sem criar uma migration.

Gerar uma migration após alterar uma entity

# Gera a migration automaticamente comparando entities com o banco
npm run migration:generate -- --name=AddSkuToProduct

# Revisa o arquivo gerado em src/database/migrations/
# Execute após revisar
npm run migration:run

Sempre revise o arquivo de migration gerado antes de executar. O TypeORM às vezes gera operações destrutivas (DROP COLUMN, DROP TABLE) que precisam ser verificadas.

Endpoints principais

Método	Rota	Descrição
`POST`	`/auth/login`	Login — retorna `accessToken` + cookie
`POST`	`/auth/refresh`	Renova o access token via cookie
`POST`	`/auth/logout`	Encerra a sessão
`GET`	`/api`	Documentação Swagger
`GET`	`/catalog/products`	Lista produtos
`GET`	`/orders`	Lista pedidos
`GET`	`/integrations`	Lista integrações do tenant
`GET`	`/queue/admin`	Dashboard do Bull Board (filas)

Troubleshooting

Erro: ECONNREFUSED ao tentar conectar ao banco

O PostgreSQL não está rodando. Execute:

docker compose -f docker/docker-compose.yml up -d postgres

Aguarde alguns segundos e tente novamente.

Erro: Error: getaddrinfo ENOTFOUND redis

O Redis não está rodando. Execute:

docker compose -f docker/docker-compose.yml up -d redis

Erro: Cannot find module 'dist/...' ao rodar migrations

As migrations exigem o projeto compilado. O comando npm run migration:run faz o build automaticamente. Se o erro persistir, rode manualmente:

npm run build
npm run migration:run

Erro 403 (CORS) vindo do frontend

Verifique a variável FRONTEND_URL no .env. Ela precisa ser exatamente a origem do frontend, incluindo protocolo e porta:

FRONTEND_URL=http://localhost:3001

Erro: ConfigService: key 'DB_HOST' cannot be found

O arquivo .env não foi encontrado. Certifique-se de que ele existe na raiz do backend (não na raiz do monorepo) e que o processo está sendo iniciado no diretório correto.

Swagger em branco ou sem rotas

O Swagger só está disponível em modo de desenvolvimento. Se o build de produção estiver sendo usado, o endpoint /api não estará disponível.

Introdução

Guias Práticos (Manuais)

Para Desenvolvedores

Sistema

Funcional

Setup do Projeto — Backend

1. Clonar o repositório

2. Subir a infraestrutura local (Docker)

3. Instalar dependências

4. Configurar variáveis de ambiente

Referência completa de variáveis

5. Executar as migrations

6. Rodar em desenvolvimento

7. Verificar se está funcionando

Comandos disponíveis

Migrations

Gerar uma migration após alterar uma entity

Endpoints principais

Troubleshooting

​1. Clonar o repositório

​2. Subir a infraestrutura local (Docker)

​3. Instalar dependências

​4. Configurar variáveis de ambiente

​Referência completa de variáveis

​5. Executar as migrations

​6. Rodar em desenvolvimento

​7. Verificar se está funcionando

​Comandos disponíveis

​Migrations

​Gerar uma migration após alterar uma entity

​Endpoints principais

​Troubleshooting

1. Clonar o repositório

2. Subir a infraestrutura local (Docker)

3. Instalar dependências

4. Configurar variáveis de ambiente

Referência completa de variáveis

5. Executar as migrations

6. Rodar em desenvolvimento

7. Verificar se está funcionando

Comandos disponíveis

Migrations

Gerar uma migration após alterar uma entity

Endpoints principais

Troubleshooting