Infraestrutura & Setup

Stack do servidor

Componente	Tecnologia	Versão mínima
Runtime	Node.js	18+
Framework	Express	4.x
Banco	Firestore (Firebase)	—
Storage	MinIO (S3-compatible)	—
Auth	Firebase Auth	—
Logs	Pino + pino-http	—
Segurança	Helmet + CORS	—

Variáveis de ambiente

Crie um arquivo .env na raiz do backend. Todas as variáveis sem valor padrão indicado são obrigatórias para a funcionalidade correspondente.

# ── Servidor ──────────────────────────────────────────────
NODE_ENV=production
PORT=3000
FRONTEND_URL=https://app.patrimonion.com.br   # obrigatório — servidor não inicia sem esta variável

# ── Sessão ────────────────────────────────────────────────
SESSION_COOKIE_NAME=imob_session
SESSION_EXPIRES_DAYS=5

# ── Firebase ──────────────────────────────────────────────
FIREBASE_API_KEY=

# ── Cron Job ──────────────────────────────────────────────
# Segredo usado pelo servidor Ubuntu para autorizar POST /notificacoes/cron/executar
CRON_SECRET=

# ── MinIO — bucket privado (documentos sensíveis) ─────────
# CPF, RG, comprovante de residência, contratos assinados
# Acesso via Presigned URL (expira em 15 min)
MINIO_ENDPOINT=
MINIO_ACCESS_KEY=
MINIO_SECRET_KEY=
MINIO_BUCKET=

# ── MinIO — bucket público (fotos e mídias) ───────────────
# Imóveis, inspeções, inventário — URLs permanentes
MINIO_BUCKET_FOTOS=

# ── Brevo (e-mail e SMS transacional) ─────────────────────
BREVO_API_KEY=
BREVO_FROM_EMAIL=naoresponda@patrimonion.com.br
BREVO_FROM_NAME=Patrimonion

# ── Evolution API (WhatsApp texto livre) ──────────────────
EVOLUTION_API_URL=
EVOLUTION_GLOBAL_KEY=

FRONTEND_URL é obrigatória — o servidor chama process.exit(1) na inicialização se ela não estiver definida.

Notas por grupo

Sessão — SESSION_COOKIE_NAME e SESSION_EXPIRES_DAYS controlam o cookie de autenticação do frontend. O padrão imob_session com 5 dias é adequado para produção. CRON_SECRET — qualquer string aleatória e longa serve (ex: resultado de openssl rand -hex 32). Ela é comparada literalmente com o header Authorization: Bearer <CRON_SECRET> no endpoint do cron. MinIO — os dois buckets são independentes e devem ser criados manualmente no MinIO antes de iniciar o servidor. O bucket de fotos (MINIO_BUCKET_FOTOS) deve ter política de leitura pública configurada no console do MinIO. Brevo — BREVO_API_KEY é a chave global usada pelo SUPER_ADMIN. Cada locador pode configurar sua própria chave em Configurações > Notificações, que sobrescreve a global para os disparos daquele tenant. Evolution API — necessário apenas se o canal evolutionAtivo estiver habilitado nas configurações de notificação. A instância por usuário é criada automaticamente com o nome imob_{userId} via POST /configuracoes/whatsapp/gerar-qr.

Middlewares globais

Os middlewares são aplicados nesta ordem em todas as requisições:

helmet          → headers de segurança (HSTS, XSS protection, etc.)
cors            → permite apenas FRONTEND_URL com credentials
cookieParser    → leitura de cookies
express.json    → limite de 10MB no body
express.urlencoded
pino-http       → log estruturado de cada requisição (método, URL, status, latência)

Rotas registradas

Prefixo	Módulo
`/auth`	Autenticação
`/imoveis`	Imóveis
`/locatarios`	Locatários
`/contratos`	Contratos
`/financeiro`	Financeiro
`/recibos`	Recibos
`/inspecoes`	Inspeções
`/inventario`	Inventário
`/upload`	Upload (MinIO)
`/notificacoes`	Notificações
`/configuracoes`	Configurações

Health check

Endpoint público para monitoramento. Não requer autenticação.

GET /health

Resposta 200

{
  "status": "ok",
  "timestamp": "2025-02-01T10:00:00.000Z"
}

Tratamento de erros global

Erros não capturados pelos handlers de rota chegam ao middleware global, que:

Loga o erro com pino incluindo método e URL
Retorna 400 para JSON malformado (entity.parse.failed)
Retorna 500 para qualquer outro erro inesperado

{
  "error": "Erro interno no servidor."
}

Logs

A stack usa Pino para logs estruturados em JSON. Em desenvolvimento, o pino-pretty formata a saída com cores no terminal.

# Desenvolvimento — logs coloridos no terminal
NODE_ENV=development npm start

# Produção — JSON puro (ideal para ingestão no Datadog, Grafana, etc.)
NODE_ENV=production npm start

O nível de log é configurável via LOG_LEVEL (padrão: info). Valores válidos: trace, debug, info, warn, error, fatal.

​Stack do servidor

​Variáveis de ambiente

​Notas por grupo

​Middlewares globais

​Rotas registradas

​Health check

​Tratamento de erros global

​Logs

Stack do servidor

Variáveis de ambiente

Notas por grupo

Middlewares globais

Rotas registradas

Health check

Tratamento de erros global

Logs