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

# Setup do Projeto — Backend

> Como configurar e rodar a API NestJS do OmniDom localmente do zero.

<Info>
  **Pré-requisitos:**

  * Node.js v20 ou superior
  * npm v10+
  * Docker Desktop instalado e rodando
  * Git
</Info>

## 1. Clonar o repositório

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

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

<Tip>
  Para parar os containers sem apagar os dados: `docker compose -f docker/docker-compose.yml stop`

  Para apagar tudo (incluindo volumes): `docker compose -f docker/docker-compose.yml down -v`
</Tip>

## 3. Instalar dependências

```bash theme={null}
npm install
```

## 4. Configurar variáveis de ambiente

Copie o arquivo de exemplo:

```bash theme={null}
cp .env.example .env
```

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

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

<Warning>
  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.
</Warning>

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

```bash theme={null}
npm run migration:run
```

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

## 6. Rodar em desenvolvimento

```bash theme={null}
npm run start:dev
```

A API estará disponível em **[http://localhost:3000](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

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

<Warning>
  **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.
</Warning>

***

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

<AccordionGroup>
  <Accordion title="Erro: ECONNREFUSED ao tentar conectar ao banco">
    O PostgreSQL não está rodando. Execute:

    ```bash theme={null}
    docker compose -f docker/docker-compose.yml up -d postgres
    ```

    Aguarde alguns segundos e tente novamente.
  </Accordion>

  <Accordion title="Erro: Error: getaddrinfo ENOTFOUND redis">
    O Redis não está rodando. Execute:

    ```bash theme={null}
    docker compose -f docker/docker-compose.yml up -d redis
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    npm run build
    npm run migration:run
    ```
  </Accordion>

  <Accordion title="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:

    ```env theme={null}
    FRONTEND_URL=http://localhost:3001
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>