# Desenvolvimento local — Docker, MySQL e API v2

Checklist para reproduzir **listagens com dados reais** (Meus jogos, Minhas premiações, `/premios`, etc.) sem surpresas de conexão.

---

## 1. Compose e serviços

- Use o arquivo **`docker-compose.local.yml`** na raiz do repositório.
- Serviços usuais:
  - **`app`**: PHP + API em `http://app:80` (dentro da rede Docker).
  - **`db`**: MySQL 8, hostname **`db`** na rede compose (não use `localhost` de dentro do container `app`).
  - **`frontend`**: Next.js com **`API_PROXY_TARGET=http://app:80`** apontando para o PHP local.

---

## 2. MySQL: `MYSQL_HOST=db` vs banco remoto

| Cenário | `MYSQL_HOST` | Observação |
|--------|--------------|------------|
| Dados no MySQL do compose | `db` | Padrão em `docker-compose.local.yml`. Porta exposta no host: **3307** → `3306` no container. |
| MySQL no host (WSL/Linux) via túnel SSH | `host.docker.internal` | `extra_hosts: host-gateway` já está no `app`. Ex.: `MYSQL_PORT=3307` após `ssh -L 3307:127.0.0.1:3306 user@servidor`. |
| IP público do servidor | IP ou hostname | Só funciona se o MySQL aceitar conexões externas na 3306 (firewall + `bind-address` + usuário com host `%`). |

Se aparecer **`Connection refused`** na 3306:

- Em muitos servidores o MySQL escuta só em **127.0.0.1** → use **túnel SSH** e `MYSQL_HOST=host.docker.internal` + `MYSQL_PORT` da porta local do túnel.

---

## 3. Credenciais e banco

- Ajuste **`MYSQL_DB`**, **`MYSQL_USER`**, **`MYSQL_PASS`** no serviço `app` conforme o dump que você importou.
- O serviço **`db_migrate`** aplica apenas migrações em `db/migrations/`; um clone completo da produção costuma ser **dump + import** no `db` local.

---

## 4. `API_DEBUG`

- Com **`API_DEBUG=1`** (ou `APP_DEBUG=1`) no ambiente do `app`, a API pode expor mais detalhes em erros e em endpoints como **`GET /api/v2/conta/jogos`** (`debug` no JSON).
- **Produção:** mantenha desligado.

---

## 5. Frontend Next.js

- **`API_PROXY_TARGET`** (serviço `frontend`) deve ser **`http://app:80`** para refletir alterações em `api/` e `src/` montadas no container `app`.
- No browser, **`NEXT_PUBLIC_API_URL`** costuma ser vazio ou origem do Next para passar pelo proxy.

---

## 6. Smoke rápido após subir o stack

1. `GET /api/v2/health` → 200.
2. Login na v2 e **`GET /api/v2/conta/jogos?limit=5`** (com cookie de sessão) → lista ou `debug` se vazio com `API_DEBUG=1`.
3. Página **`/premios`** (lista pública de premiações).

---

## 7. Variáveis opcionais — `/api/v2/premios`

| Variável | Efeito |
|----------|--------|
| `PREMIOS_RESUMO_ACERTOS_MAX` | Máximo de **linhas da lista** que recebem cálculo de `resumo_acertos` por request (padrão **25**). Use **`0`** para calcular em **todas** as linhas (mais lento com `limit` alto). |

A listagem `/api/v2/premios` **não** aplica piso nem teto de valor de prêmio (só exclui `valor_premio = 0`).

Query string:

- **`incluir_resumo=0`** — desliga o cálculo de resumo de acertos em **todas** as linhas (resposta mais rápida; cards sem faixas de acerto).

---

## 8. Referência de arquivo

- Compose: **`docker-compose.local.yml`**
- Regras de desenvolvimento v2: **`.cursor/rules/v2-padroes-desenvolvimento.mdc`**