> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patrimonion.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Infraestrutura & Setup

> Stack, variáveis de ambiente, middlewares e configuração do servidor Express.

## 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.

```bash theme={null}
# ── 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=
```

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

### 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.

```http theme={null}
GET /health
```

```json Resposta 200 theme={null}
{
  "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

```json theme={null}
{
  "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.

```bash theme={null}
# 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`.