# Setup local (/docs/setup)



Como rodar o Covil do Mineiro do zero na sua máquina.

## Pré-requisitos [#pré-requisitos]

* Node.js 20+ e npm.
* Um projeto no [Supabase](https://supabase.com) (gratuito serve para dev).
* (Opcional) Para exercitar o checkout PIX: o **sandbox** do Sicoob
  (`SICOOB_ENV=sandbox`, o padrão) valida o fluxo **sem certificado** — basta uma
  `SICOOB_PIX_KEY` (o `SICOOB_CLIENT_ID` é opcional no sandbox).

## Passo a passo [#passo-a-passo]

```bash
# 1. Instale as dependências
npm install

# 2. Crie o arquivo de ambiente
cp .env.example .env.local
```

3. Preencha o `.env.local` (ver a tabela abaixo). O mínimo para o site público
   subir é o bloco do Supabase.

4. Aplique o schema no **SQL Editor** do Supabase, na ordem das migrations
   (ver [`banco-de-dados.md`](banco-de-dados.md)), começando por
   `supabase/migrations/20260407120000_initial_covil.sql`, e depois o
   `supabase/seed.sql`.

5. Após o primeiro cadastro, promova seu usuário a administrador:

   ```sql
   update public.profiles
   set role = 'super_admin'
   where id = '<auth_user_uuid>';
   ```

6. Rode o projeto:

   ```bash
   npm run dev
   ```

   Acesse `http://localhost:3000`. O admin fica em `/admin`.

> Sem as variáveis do Supabase, o site público usa **fallback local**
> (`src/data/site-fallback.ts`) e o admin redireciona ao login com aviso de
> `setup`. Ou seja: dá para ver o site sem banco, mas não para operar.

## Variáveis de ambiente [#variáveis-de-ambiente]

| Variável                               | Visibilidade        | Para que serve                                                                                 |
| -------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_SITE_URL`                 | pública             | URL base (metadata, retorno do pagamento PIX, QR da carteirinha). Dev: `http://127.0.0.1:3000` |
| `NEXT_PUBLIC_SUPABASE_URL`             | pública             | Endpoint do Supabase                                                                           |
| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | pública             | Chave publishable/anon do Supabase                                                             |
| `SUPABASE_SERVICE_ROLE_KEY`            | **secreta**         | Client admin (ignora RLS) — webhook e escrita de pedidos                                       |
| `SICOOB_ENV`                           | servidor (opcional) | `sandbox` (padrão) ou `production`. Sandbox valida o fluxo PIX sem certificado                 |
| `SICOOB_PIX_KEY`                       | **secreta**         | Chave PIX da conta recebedora (onde as cobranças caem). Obrigatória                            |
| `SICOOB_CLIENT_ID`                     | **secreta**         | client\_id do portal developers.sicoob.com.br (opcional no sandbox)                            |
| `SICOOB_CERT_PFX_BASE64`               | **secreta**         | Certificado ICP-Brasil A1 (`.pfx` em base64) para o mTLS — só produção                         |
| `SICOOB_CERT_PASSWORD`                 | **secreta**         | Senha do `.pfx` — só produção                                                                  |
| `GMAIL_USER`                           | **secreta**         | E-mail remetente (Gmail SMTP)                                                                  |
| `GMAIL_APP_PASSWORD`                   | **secreta**         | Senha de app do Google (espaços são removidos automaticamente)                                 |
| `CARD_SIGNING_SECRET`                  | **secreta**         | HMAC do código de autenticidade da carteirinha (cai para a service role se vazio)              |
| `NEXT_PUBLIC_GA_ID`                    | pública (opcional)  | ID do Google Analytics 4 (sem ela, o GA é no-op)                                               |

## Rodar os testes [#rodar-os-testes]

```bash
npm run typecheck   # tipos
npm run test        # unitários (Vitest)
npm run e2e         # end-to-end (Playwright; sobe o dev server sozinho)
```

## Dicas [#dicas]

* Para virar **sócio** de teste: crie o usuário, e como `super_admin` aprove em
  `/admin/usuarios` (isso ativa a associação e credita o bônus de boas-vindas).
* Assets da marca ficam em `public/brands`.