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

# desenvolvimento local

> configure o ambiente de desenvolvimento para trabalhar com nossa API

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

  * Node.js versão 19 ou superior
  * Wrangler CLI instalado
  * Acesso ao Cloudflare Workers
  * Repository com `wrangler.toml` configurado
</Info>

este guia te ajuda a configurar o ambiente de desenvolvimento para trabalhar com nossa API do dashboard backend.

<Steps>
  <Step title="configure o ambiente backend">
    ```bash theme={null}
    # clone o repositório
    git clone [REPO_URL]
    cd dashboard-backend

    # instale dependências
    npm install
    ```
  </Step>

  <Step title="configure as variáveis de ambiente">
    você precisará configurar as seguintes variáveis no `wrangler.toml`:

    ```toml theme={null}
    [vars]
    JWT_SECRET = "seu_jwt_secret"
    BEEHIIV_API_KEY = "sua_api_key"
    GEMINI_API_KEY = "sua_gemini_key"
    RESEND_API_KEY = "sua_resend_key"
    # ... outras variáveis
    ```

    <Warning>
      nunca commite secrets reais no repositório. use `wrangler secret put` para secrets sensíveis.
    </Warning>
  </Step>

  <Step title="execute o servidor de desenvolvimento">
    ```bash theme={null}
    # inicia o servidor local conectado ao ambiente remoto
    npm run dev
    ```

    sua API estará disponível em `http://localhost:8787`.
  </Step>

  <Step title="teste os endpoints">
    você pode testar os endpoints usando curl ou Postman:

    ```bash theme={null}
    # teste um endpoint público
    curl http://localhost:8787/referrals/count

    # teste um endpoint autenticado
    curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
         http://localhost:8787/referrals
    ```
  </Step>
</Steps>

## estrutura do projeto

nossa API é organizada da seguinte forma:

```
dashboard-backend/
├── src/
│   ├── routes/          # definições de rotas
│   ├── handlers/        # lógica de negócio
│   ├── services/        # integrações externas
│   ├── middleware/      # autenticação e cache
│   ├── schema/          # schemas do banco
│   └── types/           # tipos TypeScript
├── drizzle/             # migrações do banco
└── wrangler.toml        # configuração do Workers
```

## bancos de dados

ossa arquitetura utiliza múltiplos bancos D1 especializados:

<CardGroup cols={2}>
  <Card title="📊 DB" icon="database">
    dados principais, métricas e newsletters
  </Card>

  <Card title="🎯 STREAKS" icon="fire">
    gamificação, leituras e engagement
  </Card>

  <Card title="👥 CRM" icon="users">
    gestão de relacionamento com clientes
  </Card>

  <Card title="📝 FORMS" icon="file-text">
    formulários dinâmicos e submissions
  </Card>
</CardGroup>

## migrações do banco

para aplicar migrações localmente:

```bash theme={null}
# gerar nova migração
npm run generate

# aplicar migrações localmente
npm run migrate
```

## deploy para produção

quando estiver pronto para fazer deploy:

```bash theme={null}
# deploy com minificação e source maps
npm run deploy
```

<Note>
  o deploy inclui automaticamente integração com Sentry para monitoramento de erros.
</Note>

## ferramentas recomendadas

para melhor experiência de desenvolvimento:

* **VSCode** com extensões TypeScript
* **Drizzle Kit** para gestão do banco
* **Postman** ou **Insomnia** para teste de APIs
* **Wrangler** para gestão do Cloudflare Workers

## solução de problemas

<AccordionGroup>
  <Accordion title="erro: &#x22;wrangler not found&#x22;">
    instale o wrangler CLI globalmente:

    ```bash theme={null}
    npm install -g wrangler
    ```

    ou use via npx:

    ```bash theme={null}
    npx wrangler dev --remote
    ```
  </Accordion>

  <Accordion title="erro de autenticação com Cloudflare">
    faça login no Cloudflare:

    ```bash theme={null}
    wrangler login
    ```

    verifique se o `account_id` está correto no `wrangler.toml`.
  </Accordion>

  <Accordion title="erro: banco de dados não encontrado">
    verifique se os database IDs estão corretos no `wrangler.toml` e se os bancos existem no painel do Cloudflare.
  </Accordion>

  <Accordion title="endpoints retornando 500">
    verifique os logs do Sentry ou use `wrangler tail` para debug em tempo real:

    ```bash theme={null}
    wrangler tail
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  **dica**: use `console.log()` liberalmente durante desenvolvimento - os logs aparecerão no terminal com `npm run dev`.
</Tip>