# bolão — backend

API do app de bolão. **NestJS 11 + PostgreSQL via Prisma 7.**

Nenhuma feature implementada ainda: este repositório contém apenas o
scaffold, a conexão com o banco e a configuração base.

## Stack

| Camada    | Escolha                                            |
| --------- | -------------------------------------------------- |
| Framework | NestJS 11 (TypeScript, CommonJS via `nodenext`)     |
| Banco     | PostgreSQL                                         |
| ORM       | Prisma 7 (generator `prisma-client`, adapter `pg`) |
| Validação | `class-validator` + `ValidationPipe` global        |
| Docs      | Swagger em `/docs`                                 |

## Rodando localmente

```bash
npm install                 # roda prisma generate no postinstall
cp .env.example .env        # ajuste DATABASE_URL
createdb bolao              # ou aponte para um Postgres existente
npm run prisma:migrate      # aplica migrations (nenhuma ainda)
npm run start:dev
```

API em `http://localhost:3000`, Swagger em `http://localhost:3000/docs`.

## Comandos

| Comando                  | O que faz                                |
| ------------------------ | ---------------------------------------- |
| `npm run start:dev`      | Sobe em watch mode                       |
| `npm run build`          | Compila para `dist/`                     |
| `npm test`               | Testes unitários                         |
| `npm run test:e2e`       | Testes end-to-end (banco próprio, ver abaixo) |
| `npm run lint`           | ESLint + Prettier                        |
| `npm run prisma:migrate` | Cria/aplica migration a partir do schema |
| `npm run prisma:studio`  | Abre o Prisma Studio                     |

## Notas de setup (não óbvias)

- **A suíte e2e usa banco próprio** (`bolao_test`, derivado do `DATABASE_URL` com
  sufixo `_test`; sobrescreva com `DATABASE_URL_TEST`). Ela **cria e migra
  sozinha** na primeira execução. Antes de 07/08 dev e teste dividiam o mesmo
  banco, e isso custava confiança no gate: apagar dado de desenvolvimento
  perturbava uma execução, e o cron do servidor de dev — que agora usa a fonte
  **real** — podia trocar um placar no meio de um teste. Com a separação, a suíte
  passou verde enquanto o servidor de dev criava bolões e sincronizava na mesma
  máquina.
- **A fonte real não entra em teste automatizado**, mesmo com
  `FOOTBALL_DATA_TOKEN` definido: `NODE_ENV=test` cai no adaptador falso, salvo
  `FONTE_REAL=true`. Suíte que depende de rede, de cota e do calendário real
  mudando debaixo dela deixa de ser gate. As verificações contra a API de verdade
  ficam em `scripts/`.

- **O client do Prisma não é versionado** (`src/generated/prisma` está no
  `.gitignore`). O `postinstall` roda `prisma generate`; se o build
  reclamar de import faltando, rode `npm run prisma:generate`.
- **`moduleFormat = "cjs"` no schema é obrigatório.** Por padrão o
  generator do Prisma 7 emite ESM (usa `import.meta.url`), que não carrega
  no build CommonJS do NestJS. Não remova essa linha.
- **A conexão usa driver adapter** (`PrismaPg`), exigência do Prisma 7 —
  por isso o `datasource` no schema não tem `url`; ela vem do
  `prisma.config.ts` (CLI) e do `PrismaService` (runtime), ambos via
  `DATABASE_URL`.
- **`npm` 11 bloqueia install scripts.** `prisma`, `@prisma/engines`,
  `fsevents` e `unrs-resolver` já estão aprovados em `allowScripts` no
  `package.json`. Ao adicionar dependência com postinstall, use
  `npm approve-scripts <pkg>`.
- O `prisma init` instalou as skills de agente do Prisma em
  `.agents/skills/`, com symlinks em `.claude/skills/` e
  `.windsurf/skills/`. São documentação do Prisma para agentes de IA —
  pode remover se não quiser.
