# AGENTS.md - PlanFi BFF

## Stack

- NestJS 11 + TypeScript CommonJS.
- MongoDB/Mongoose, JWT, proxy Laravel, Pluggy/OpenFinance e mocks MSW.
- Use Yarn e mantenha `yarn.lock`.

## Estrutura

- `src/auth/`: JWT, guards, decorators e estrategias.
- `src/laravel-api/`, `src/master-api/`, `src/pluggy/`: integracoes externas.
- `src/openfinance-excluded-transactions/`, `src/transactions-classification/`: dominio.
- `src/mocks/`: MSW/dev mocks.
- `test/`: e2e; `docs/`: contratos e guias.

## Comandos

- Dev: `yarn start:dev`.
- Build/runtime: `yarn build`, `yarn start:prod`.
- Qualidade: `yarn lint`, `yarn test`, `yarn test:e2e`, `yarn test:cov`.
- Integracao: `yarn test:integration`.

## Regras

- Crie features como modulos Nest: controller fino, service com regra, DTOs com `class-validator`.
- Reuse guards/decorators de `src/auth` para manter compatibilidade do JWT com a API Laravel.
- O `ValidationPipe` global usa `whitelist` e `transform`, mas `forbidNonWhitelisted` e falso; valide explicitamente payloads sensiveis.
- CORS fica em `src/main.ts`; atualize a allowlist com cuidado.
- Configuracoes devem vir de `.env`/`@nestjs/config`, nunca hardcoded.
- Ao alterar contratos usados pelo frontend/Laravel, atualize `docs/` ou Postman quando existir.
- **E-mails de exemplo**: TODO e-mail fictício usado em seeds, fixtures, testes, mocks (MSW) ou qualquer dado de exemplo DEVE terminar com `@planfi.com.br`, SEMPRE. Nunca use domínios genéricos (`@ex.com`, `@example.com`, `@gmail.com`, `@test.com`, etc.).