nestforge-generator 0.1.0

package/templates/prisma/README.md

@@ -0,0 +1,267 @@
+# NestForge
+
+**English** | [Português](README.pt-BR.md)
+
+> Production-ready NestJS starter with Prisma, Authentication, Docker, Testing, CI/CD and Clean Architecture.
+
+[![CI](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml/badge.svg)](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![NestJS](https://img.shields.io/badge/NestJS-11-red)](https://nestjs.com)
+
+NestForge is a NestJS starter designed to accelerate the beginning of serious backend projects, with complete authentication, clean architecture, security, and observability already configured. The idea is to clone it, run `docker compose up`, and have an API ready to evolve.
+
+## ✨ Features
+
+- 🔐 **Configurable authentication** — JWT with access/refresh tokens, Prisma-backed Session/Cookies, OAuth-only, or no authentication
+- 🌐 **OAuth** — Google and GitHub, integrated with the selected token or session strategy
+- 👥 **RBAC** — Roles (Admin, Manager, User) and granular Permissions
+- 🛡️ **Security** — Helmet, CORS, Rate Limiting, validation, and serialization with Zod
+- 🗄️ **Database** — Prisma with PostgreSQL, MySQL, or SQLite
+- 📨 **Email** — queues with BullMQ + Redis, locally tested with Mailpit
+- 📄 **Automatic documentation** — Swagger
+- 🪵 **Structured logs** — Pino
+- ✅ **Tests** — unit and integration tests with Vitest
+- 🐳 **Docker** — complete environment with a single command
+- ⚙️ **CI/CD** — GitHub Actions (build, lint, test)
+
+## 🧱 Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | NestJS + TypeScript |
+| ORM | Prisma |
+| Database | PostgreSQL, MySQL, or SQLite |
+| Cache / Queues | Redis + BullMQ |
+| Authentication | JWT, Session/Cookies, or OAuth with Passport |
+| Validation | Zod + nestjs-zod (schemas automatically become DTOs + Swagger) |
+| Docs | Swagger |
+| Email (dev) | Mailpit |
+| Tests | Vitest |
+| CI | GitHub Actions |
+
+## 📁 Folder structure
+
+```
+src/
+│
+├── auth/          # login, sessions/tokens, OAuth, guards, and strategies
+├── users/         # user CRUD
+├── common/        # decorators, filters, guards, interceptors, pipes, utilities
+├── config/        # typed and validated configuration (env)
+├── database/      # PrismaService / PrismaModule
+├── modules/       # additional domain modules
+├── shared/        # code shared between modules
+├── jobs/          # queues and workers (BullMQ)
+├── mail/          # email templates and delivery
+└── main.ts
+```
+
+## 🚀 Getting started
+
+### Prerequisites
+
+- Node.js 20+
+- Docker and Docker Compose
+
+### Running with Docker (recommended)
+
+```bash
+git clone https://github.com/jeiel2013/nestforge.git
+cd nestforge
+cp .env.example .env
+docker compose up
+```
+
+This starts the API, PostgreSQL, Redis, and Mailpit (email interface at `http://localhost:8025`).
+
+### Running locally
+
+```bash
+npm install
+cp .env.example .env
+npx prisma migrate dev
+npx prisma db seed
+npm run start:dev
+```
+
+Swagger documentation is available at `http://localhost:3000/docs`.
+
+## 🔑 Roles & Permissions
+
+| Role | Description |
+|---|---|
+| `ADMIN` | full system access |
+| `MANAGER` | manages users and reports |
+| `USER` | standard access |
+
+Permissions are granular (`user:create`, `user:delete`, `report:read`, etc.) and combined with roles through decorators (`@Roles()`, `@Permissions()`).
+
+## 🗺️ Roadmap
+
+- [x] JWT authentication
+- [x] Session/Cookies authentication
+- [x] Google/GitHub OAuth
+- [x] OAuth-only strategy
+- [x] Generation without authentication
+- [x] Refresh Token
+- [x] Docker
+- [x] CI (build, lint, test)
+- [x] OAuth (Google/GitHub)
+- [x] File uploads
+- [x] Queues (BullMQ)
+- [x] Transactional email
+- [x] Complete RBAC (granular permissions)
+- [x] Complete integration tests
+- [x] Complete documentation (Swagger + architecture guide)
+
+See the detailed [ROADMAP.md](ROADMAP.md).
+
+### Configuring social login (OAuth)
+
+To enable login through Google and GitHub, create an OAuth App with each provider and fill in `.env`:
+
+```bash
+APP_URL=http://localhost:3000
+
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+```
+
+- **Google**: create credentials in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) and configure the callback URL as `{APP_URL}/auth/google/callback`.
+- **GitHub**: create an OAuth App under `Settings > Developer settings > OAuth Apps` and configure the callback URL as `{APP_URL}/auth/github/callback`.
+
+Then access `GET /auth/google` or `GET /auth/github`. On callback, the API issues access/refresh tokens or establishes a cookie-based session according to the selected strategy. On first access, an account is created and linked to the provider.
+
+### Session/Cookies authentication
+
+When the project is generated with Session/Cookies, registration and login create a session persisted in the database through `@quixo3/prisma-session-store`. The identifier is sent in the `nestforge.sid` cookie, configured with `httpOnly`, `sameSite=lax`, and `secure` in production.
+
+Configure `.env`:
+
+```bash
+SESSION_SECRET=use-a-secret-with-at-least-32-characters
+SESSION_MAX_AGE=604800000
+```
+
+### Password recovery and email verification
+
+Every registration (`POST /auth/register`) automatically sends a verification email. Emails are queued with BullMQ/Redis and processed by a worker that sends them over SMTP. In development, everything goes to Mailpit (`http://localhost:8025`), so nothing is actually sent over the internet.
+
+| Route | What it does |
+|---|---|
+| `POST /auth/forgot-password` | Receives an `email` and queues the password reset link (the response is always generic and does not reveal whether the email exists) |
+| `POST /auth/reset-password` | Receives a `token` + `password` and changes the password; it also revokes the user's active refresh tokens |
+| `GET /auth/verify-email?token=...` | Confirms the email from the received link |
+
+Reset and verification tokens expire after 1 hour and 24 hours, respectively, and can only be used once.
+
+## 🔑 Roles & Permissions
+
+| Role | Description |
+|---|---|
+| `ADMIN` | full system access |
+| `MANAGER` | manages users and reports |
+| `USER` | standard access |
+
+Each role has a fixed set of permissions mapped in `src/common/constants/role-permissions.ts`:
+
+| Permission | ADMIN | MANAGER | USER |
+|---|:---:|:---:|:---:|
+| `user:create` | ✅ | ❌ | ❌ |
+| `user:read` | ✅ | ✅ | ✅ |
+| `user:update` | ✅ | ✅ | ❌ |
+| `user:delete` | ✅ | ❌ | ❌ |
+| `report:read` | ✅ | ✅ | ❌ |
+
+On routes, use `@Permissions(Permission.UserCreate)` to require a specific permission or `@Roles(Role.ADMIN)` when role-based control is enough. Both guards (`RolesGuard` and `PermissionsGuard`) run globally and only block a route when it has the corresponding decorator.
+
+## 👥 Users: pagination, filters, and avatar
+
+`GET /users` accepts query parameters for paginating and filtering the list:
+
+```bash
+GET /users?page=2&limit=20&search=jeiel&role=ADMIN
+```
+
+| Parameter | Description |
+|---|---|
+| `page` | current page (default: 1) |
+| `limit` | items per page, up to 100 (default: 10) |
+| `search` | searches by name or email (case-insensitive) |
+| `role` | filters by `ADMIN`, `MANAGER`, or `USER` |
+
+The response uses the format `{ data, meta: { total, page, limit, totalPages } }`.
+
+To change the authenticated user's avatar:
+
+```bash
+curl -X POST http://localhost:3000/users/me/avatar \
+  -H "Authorization: Bearer <accessToken>" \
+  -F "file=@/path/to/photo.png"
+```
+
+PNG, JPEG, and WEBP files up to 2 MB are accepted. The file is saved under `./uploads/avatars` and served at `/uploads/avatars/<file>`.
+
+## 🛡️ Security: serialization and CSRF
+
+All input validation (`body`, `query`) uses **Zod** through [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod): each DTO is a `z.object({...})` transformed into a class with `createZodDto(schema)` and globally validated by `ZodValidationPipe`. During bootstrap, `patchNestJsSwagger()` teaches Swagger to read these schemas automatically, so validation (Zod) and documentation (`@ApiProperty`) do not need to be duplicated as they would with `class-validator`. Exported schemas (for example, `createUserSchema`) can also be reused and combined (such as `updateUserSchema`, which is simply `createUserSchema.partial()`).
+
+- 🪵 **Observability** — structured logs with Pino, health checks (`/health`), and Prometheus metrics (`/metrics`)
+
+The seed creates three test accounts, one for each role:
+
+| Email | Password | Role |
+|---|---|---|
+| `admin@nestforge.dev` | `admin123` | ADMIN |
+| `manager@nestforge.dev` | `manager123` | MANAGER |
+| `user@nestforge.dev` | `user1234` | USER |
+
+## 📈 Observability
+
+`GET /health` returns the aggregated status of the API — database (Prisma), Redis, memory (heap/RSS), and disk space — using `@nestjs/terminus`. Each check appears individually in the response, making it clear which component failed.
+
+`GET /metrics` exposes Prometheus-format metrics through `prom-client`: standard Node.js metrics (CPU, memory, event loop), plus `http_request_duration_seconds` (histogram) and `http_requests_total` (counter), both with `method`, `route`, and `status_code` labels. Simply point a Prometheus scrape job at this route.
+
+## 🧪 Tests
+
+```bash
+npm run test          # unit tests
+npm run test:e2e      # integration tests (E2E)
+npm run test:cov      # coverage
+```
+
+E2E tests (`test/*.e2e-spec.ts`) start the real application (Nest + Prisma + Redis) and call its endpoints with `supertest`, using an isolated database (`.env.test`, the `nestforge_test` database — never the development database). Before running them for the first time:
+
+```bash
+createdb nestforge_test   # or: psql -U nestforge -c "CREATE DATABASE nestforge_test;"
+docker compose up -d postgres redis
+npm run test:e2e
+```
+
+The `pretest:e2e` script automatically applies migrations to this database before every run. Each test cleans the tables before running (`test/utils/clean-database.ts`), so nothing needs to be reset manually between runs. Current coverage includes the complete authentication flow (registration, login, refresh, logout, duplicate email, invalid credentials) and user CRUD with RBAC (ADMIN can do everything, USER can read but cannot create, `/users/me`, and access without a token).
+
+Unit tests (`src/**/*.spec.ts`) run in isolation with Prisma and `ioredis` mocked (`vi.fn()` / `vi.mock()`), so they do not require a real database or Redis. Current coverage includes `AuthService` (registration/login), `UsersService` (complete CRUD + pagination + confirmation through `instanceToPlain` that `passwordHash` is not leaked during serialization), `RolesGuard` and `PermissionsGuard` (allowing/blocking, including multiple permissions required at the same time), and health indicators (`PrismaHealthIndicator`, `RedisHealthIndicator`).
+
+Unit tests also cover `SessionService` and `SessionAuthGuard`. When Session/Cookies is enabled, the dedicated E2E test validates cookie creation, persistence of authentication across requests, and logout.
+
+## 📚 Additional documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — how the project is organized and why certain design decisions were made (Zod vs. class-validator, code-based vs. database-based permissions, BullMQ, etc.)
+- [TESTING.md](TESTING.md) — how to validate migrations, build, unit tests, and E2E tests
+- [docs/adding-a-module.md](docs/adding-a-module.md) — step-by-step instructions for adding a new feature according to the project's conventions
+
+## 🤝 Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete guide.
+
+## 📄 License
+
+This project is licensed under the MIT License — see [LICENSE](LICENSE).
+
+---
+
+Made by [Jeiel Alves](https://github.com/jeiel2013) · [jeieldev.com.br](https://jeieldev.com.br)

package/templates/prisma/README.pt-BR.md

@@ -0,0 +1,267 @@
+# NestForge
+
+[English](README.md) | **Português**
+
+> Production-ready NestJS starter with Prisma, Authentication, Docker, Testing, CI/CD and Clean Architecture.
+
+[![CI](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml/badge.svg)](https://github.com/jeiel2013/nestforge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![NestJS](https://img.shields.io/badge/NestJS-11-red)](https://nestjs.com)
+
+NestForge é um boilerplate de NestJS pensado para acelerar o início de projetos backend sérios, com autenticação completa, arquitetura limpa, segurança e observabilidade já configuradas. A ideia é você clonar, rodar `docker compose up` e já ter uma API pronta para evoluir.
+
+## ✨ Features
+
+- 🔐 **Autenticação configurável** — JWT com access/refresh token, Session/Cookies persistida no Prisma, OAuth-only ou nenhuma autenticação
+- 🌐 **OAuth** — Google e GitHub, integrado à estratégia de token ou sessão escolhida
+- 👥 **RBAC** — Roles (Admin, Manager, User) e Permissions granulares
+- 🛡️ **Segurança** — Helmet, CORS, Rate Limiting, validação e serialização com Zod
+- 🗄️ **Banco de dados** — Prisma com PostgreSQL, MySQL ou SQLite
+- 📨 **E-mails** — filas com BullMQ + Redis, testado localmente com Mailpit
+- 📄 **Documentação automática** — Swagger
+- 🪵 **Logs estruturados** — Pino
+- ✅ **Testes** — unitários e de integração com Vitest
+- 🐳 **Docker** — ambiente completo com um comando
+- ⚙️ **CI/CD** — GitHub Actions (build, lint, test)
+
+## 🧱 Stack
+
+| Camada | Tecnologia |
+|---|---|
+| Framework | NestJS + TypeScript |
+| ORM | Prisma |
+| Banco | PostgreSQL, MySQL ou SQLite |
+| Cache / Filas | Redis + BullMQ |
+| Autenticação | JWT, Session/Cookies ou OAuth com Passport |
+| Validação | Zod + nestjs-zod (schemas viram DTO + Swagger automaticamente) |
+| Docs | Swagger |
+| E-mail (dev) | Mailpit |
+| Testes | Vitest |
+| CI | GitHub Actions |
+
+## 📁 Estrutura de pastas
+
+```
+src/
+│
+├── auth/          # login, sessões/tokens, OAuth, guards e strategies
+├── users/         # CRUD de usuários
+├── common/        # decorators, filters, guards, interceptors, pipes, utils
+├── config/        # configuração tipada e validada (env)
+├── database/      # PrismaService / PrismaModule
+├── modules/       # módulos de domínio adicionais
+├── shared/        # código compartilhado entre módulos
+├── jobs/          # filas e workers (BullMQ)
+├── mail/          # templates e envio de e-mail
+└── main.ts
+```
+
+## 🚀 Começando
+
+### Pré-requisitos
+
+- Node.js 20+
+- Docker e Docker Compose
+
+### Rodando com Docker (recomendado)
+
+```bash
+git clone https://github.com/jeiel2013/nestforge.git
+cd nestforge
+cp .env.example .env
+docker compose up
+```
+
+Isso sobe: API, PostgreSQL, Redis e Mailpit (interface de e-mail em `http://localhost:8025`).
+
+### Rodando localmente
+
+```bash
+npm install
+cp .env.example .env
+npx prisma migrate dev
+npx prisma db seed
+npm run start:dev
+```
+
+A documentação Swagger fica disponível em `http://localhost:3000/docs`.
+
+## 🔑 Roles & Permissions
+
+| Role | Descrição |
+|---|---|
+| `ADMIN` | acesso total ao sistema |
+| `MANAGER` | gerencia usuários e relatórios |
+| `USER` | acesso padrão |
+
+Permissions são granulares (`user:create`, `user:delete`, `report:read`, etc) e combinadas com roles via decorators (`@Roles()`, `@Permissions()`).
+
+## 🗺️ Roadmap
+
+- [x] Autenticação por JWT
+- [x] Autenticação por Session/Cookies
+- [x] OAuth Google/GitHub
+- [x] Estratégia OAuth-only
+- [x] Geração sem autenticação
+- [x] Refresh Token
+- [x] Docker
+- [x] CI (build, lint, test)
+- [x] OAuth (Google/GitHub)
+- [x] Upload de arquivos
+- [x] Filas (BullMQ)
+- [x] E-mails transacionais
+- [x] RBAC completo (permissions granulares)
+- [x] Testes de integração completos
+- [x] Documentação completa (Swagger + guia de arquitetura)
+
+Veja o [ROADMAP.pt-BR.md](ROADMAP.pt-BR.md) detalhado.
+
+### Configurando o login social (OAuth)
+
+Para habilitar login via Google e GitHub, crie um OAuth App em cada provedor e preencha no `.env`:
+
+```bash
+APP_URL=http://localhost:3000
+
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+```
+
+- **Google**: crie as credenciais no [Google Cloud Console](https://console.cloud.google.com/apis/credentials) e configure a URL de callback como `{APP_URL}/auth/google/callback`.
+- **GitHub**: crie um OAuth App em `Settings > Developer settings > OAuth Apps` e configure a mesma URL de callback, trocando para `{APP_URL}/auth/github/callback`.
+
+Depois é só acessar `GET /auth/google` ou `GET /auth/github`. No callback, a API emite access/refresh tokens ou estabelece uma sessão por cookie, conforme a estratégia escolhida. Se for o primeiro acesso, uma conta é criada e vinculada ao provedor.
+
+### Autenticação por Session/Cookies
+
+Quando o projeto é gerado com Session/Cookies, cadastro e login criam uma sessão persistida no banco por `@quixo3/prisma-session-store`. O identificador é enviado no cookie `nestforge.sid`, configurado com `httpOnly`, `sameSite=lax` e `secure` em produção.
+
+Configure no `.env`:
+
+```bash
+SESSION_SECRET=use-um-segredo-com-pelo-menos-32-caracteres
+SESSION_MAX_AGE=604800000
+```
+
+### Recuperação de senha e verificação de e-mail
+
+Todo cadastro (`POST /auth/register`) já dispara um e-mail de verificação automaticamente. Os e-mails são enfileirados com BullMQ/Redis e processados por um worker que envia via SMTP — em desenvolvimento, tudo cai no Mailpit (`http://localhost:8025`), então nada sai pra internet de verdade.
+
+| Rota | O que faz |
+|---|---|
+| `POST /auth/forgot-password` | Recebe um `email` e enfileira o envio do link de redefinição (resposta sempre genérica, não revela se o e-mail existe) |
+| `POST /auth/reset-password` | Recebe `token` + `password` e troca a senha; também revoga os refresh tokens ativos do usuário |
+| `GET /auth/verify-email?token=...` | Confirma o e-mail a partir do link recebido |
+
+Os tokens de reset e verificação expiram em 1 hora e 24 horas, respectivamente, e são de uso único.
+
+## 🔑 Roles & Permissions
+
+| Role | Descrição |
+|---|---|
+| `ADMIN` | acesso total ao sistema |
+| `MANAGER` | gerencia usuários e relatórios |
+| `USER` | acesso padrão |
+
+Cada role tem um conjunto fixo de permissões, mapeado em `src/common/constants/role-permissions.ts`:
+
+| Permission | ADMIN | MANAGER | USER |
+|---|:---:|:---:|:---:|
+| `user:create` | ✅ | ❌ | ❌ |
+| `user:read` | ✅ | ✅ | ✅ |
+| `user:update` | ✅ | ✅ | ❌ |
+| `user:delete` | ✅ | ❌ | ❌ |
+| `report:read` | ✅ | ✅ | ❌ |
+
+Nas rotas, use `@Permissions(Permission.UserCreate)` para exigir uma permissão específica, ou `@Roles(Role.ADMIN)` quando o controle por cargo já for suficiente. Os dois guards (`RolesGuard` e `PermissionsGuard`) rodam globalmente e só bloqueiam a rota se ela tiver o decorator correspondente.
+
+## 👥 Usuários: paginação, filtros e avatar
+
+`GET /users` aceita query params pra paginar e filtrar a listagem:
+
+```bash
+GET /users?page=2&limit=20&search=jeiel&role=ADMIN
+```
+
+| Parâmetro | Descrição |
+|---|---|
+| `page` | página atual (padrão: 1) |
+| `limit` | itens por página, até 100 (padrão: 10) |
+| `search` | busca por nome ou e-mail (case-insensitive) |
+| `role` | filtra por `ADMIN`, `MANAGER` ou `USER` |
+
+A resposta vem no formato `{ data, meta: { total, page, limit, totalPages } }`.
+
+Pra trocar o avatar do usuário autenticado:
+
+```bash
+curl -X POST http://localhost:3000/users/me/avatar \
+  -H "Authorization: Bearer <accessToken>" \
+  -F "file=@/caminho/da/foto.png"
+```
+
+Aceita PNG, JPEG e WEBP até 2MB; o arquivo fica salvo em `./uploads/avatars` e é servido em `/uploads/avatars/<arquivo>`.
+
+## 🛡️ Segurança: serialização e CSRF
+
+Toda validação de entrada (`body`, `query`) usa **Zod** via [`nestjs-zod`](https://github.com/BenLorantfy/nestjs-zod): cada DTO é um `z.object({...})` transformado em classe com `createZodDto(schema)`, validado globalmente pelo `ZodValidationPipe`. O `patchNestJsSwagger()` no bootstrap ensina o Swagger a ler esses schemas automaticamente — não precisa duplicar validação (Zod) e documentação (`@ApiProperty`) como no `class-validator`. Os schemas exportados (ex.: `createUserSchema`) também podem ser reaproveitados/combinados (como o `updateUserSchema`, que é só um `createUserSchema.partial()`).
+
+- 🪵 **Observabilidade** — logs estruturados com Pino, health checks (`/health`) e métricas Prometheus (`/metrics`)
+
+O seed cria três contas de teste, uma por role:
+
+| E-mail | Senha | Role |
+|---|---|---|
+| `admin@nestforge.dev` | `admin123` | ADMIN |
+| `manager@nestforge.dev` | `manager123` | MANAGER |
+| `user@nestforge.dev` | `user1234` | USER |
+
+## 📈 Observabilidade
+
+`GET /health` retorna o status agregado da API — banco (Prisma), Redis, memória (heap/RSS) e espaço em disco — usando `@nestjs/terminus`. Cada verificação aparece individualmente na resposta, então dá pra saber exatamente o que caiu.
+
+`GET /metrics` expõe métricas no formato do Prometheus (via `prom-client`): as métricas padrão de Node.js (CPU, memória, event loop) mais `http_request_duration_seconds` (histograma) e `http_requests_total` (contador), ambas com labels de `method`, `route` e `status_code`. Basta apontar um scrape job do Prometheus pra essa rota.
+
+## 🧪 Testes
+
+```bash
+npm run test          # unitários
+npm run test:e2e      # integração (e2e)
+npm run test:cov      # cobertura
+```
+
+Os testes e2e (`test/*.e2e-spec.ts`) sobem a aplicação real (Nest + Prisma + Redis) e batem nos endpoints com `supertest`, usando um banco isolado (`.env.test`, banco `nestforge_test` — nunca o de desenvolvimento). Antes de rodar pela primeira vez:
+
+```bash
+createdb nestforge_test   # ou: psql -U nestforge -c "CREATE DATABASE nestforge_test;"
+docker compose up -d postgres redis
+npm run test:e2e
+```
+
+O script `pretest:e2e` já aplica as migrations nesse banco automaticamente antes de cada rodada. Cada teste limpa as tabelas antes de rodar (`test/utils/clean-database.ts`), então não precisa zerar nada manualmente entre execuções. Hoje cobrem o fluxo de autenticação completo (registro, login, refresh, logout, e-mail duplicado, credenciais inválidas) e o CRUD de usuários com RBAC (ADMIN consegue tudo, USER lê mas não cria, `/users/me`, acesso sem token).
+
+Os testes unitários (`src/**/*.spec.ts`) rodam isolados, com Prisma e `ioredis` mockados (`vi.fn()` / `vi.mock()`) — não precisam de banco nem Redis de verdade. Hoje cobrem: `AuthService` (registro/login), `UsersService` (CRUD completo + paginação + confirma que o `passwordHash` não vaza na serialização via `instanceToPlain`), `RolesGuard` e `PermissionsGuard` (liberação/bloqueio, inclusive com múltiplas permissões exigidas ao mesmo tempo) e os indicadores de saúde (`PrismaHealthIndicator`, `RedisHealthIndicator`).
+
+Os testes unitários também cobrem `SessionService` e `SessionAuthGuard`. Quando Session/Cookies está habilitada, o teste e2e específico valida criação do cookie, persistência da autenticação entre requisições e logout.
+
+## 📚 Documentação adicional
+
+- [ARCHITECTURE.pt-BR.md](ARCHITECTURE.pt-BR.md) — como o projeto é organizado e por que certas decisões de design foram tomadas (Zod vs. class-validator, permissions em código vs. banco, BullMQ, etc.)
+- [TESTING.pt-BR.md](TESTING.pt-BR.md) — como validar migrations, build, testes unitários e testes E2E
+- [docs/adding-a-module.md](docs/adding-a-module.md) — passo a passo pra adicionar um recurso novo seguindo as convenções do projeto
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Veja o [CONTRIBUTING.pt-BR.md](CONTRIBUTING.pt-BR.md) para o guia completo.
+
+## 📄 Licença
+
+Este projeto está sob a licença MIT — veja [LICENSE](LICENSE).
+
+---
+
+Feito por [Jeiel Alves](https://github.com/jeiel2013) · [jeieldev.com.br](https://jeieldev.com.br)

package/templates/prisma/ROADMAP.md

@@ -0,0 +1,75 @@
+# Roadmap
+
+**English** | [Português](ROADMAP.pt-BR.md)
+
+This roadmap makes it clear what is ready and where contributions are possible. PRs for any open item are very welcome — open an issue first for large changes so the approach can be aligned.
+
+## Authentication
+
+- [x] Login
+- [x] Registration
+- [x] Logout
+- [x] Refresh Token
+- [x] Forgot Password
+- [x] Reset Password
+- [x] Email Verification
+- [x] Google OAuth
+- [x] GitHub OAuth
+
+## Users
+
+- [x] Basic CRUD
+- [x] Pagination and advanced filters
+- [x] Avatar upload
+
+## RBAC
+
+- [x] Roles (Admin, Manager, User)
+- [x] Granular permissions (`user:create`, `report:read`, etc.)
+- [x] Guard combining roles + permissions
+
+## Security
+
+- [x] Helmet
+- [x] CORS
+- [x] Rate Limit
+- [x] Validation (Zod + nestjs-zod, integrated with Swagger through `createZodDto`)
+- [x] Serialization (output interceptor)
+- [x] CSRF (when required)
+
+## Database
+
+- [x] Prisma
+- [x] PostgreSQL
+- [x] Migrations
+- [x] Complete seed (roles, permissions, administrator user)
+
+## Infrastructure
+
+- [x] Docker / docker-compose (API, Postgres, Redis, Mailpit)
+- [x] GitHub Actions CI (build, lint, test)
+- [ ] Automated deployment (Railway/Fly.io example)
+
+## Observability
+
+- [x] Structured logging with Pino
+- [x] Health checks (`/health`)
+- [x] Metrics (optional Prometheus)
+
+## Jobs & Email
+
+- [x] BullMQ queue
+- [x] Transactional email delivery (Mailpit in development)
+- [x] Email templates
+
+## Tests
+
+- [x] Unit test structure (Vitest)
+- [x] Integration tests (auth + users)
+
+## Documentation
+
+- [x] Initial README
+- [x] Complete Swagger with request/response examples
+- [x] Architecture guide (ADR / design decisions)
+- [x] “How to add a new module” guide

package/templates/prisma/ROADMAP.pt-BR.md

@@ -0,0 +1,65 @@
+# Roadmap
+
+[English](ROADMAP.md) | **Português**
+
+Este roadmap existe para deixar claro o que já está pronto e onde dá pra contribuir. PRs para qualquer item em aberto são muito bem-vindos — abra uma issue antes se for algo grande, pra alinharmos a abordagem.
+
+## Autenticação
+- [x] Login
+- [x] Cadastro
+- [x] Logout
+- [x] Refresh Token
+- [x] Forgot Password
+- [x] Reset Password
+- [x] Email Verification
+- [x] OAuth Google
+- [x] OAuth GitHub
+
+## Usuários
+- [x] CRUD básico
+- [x] Paginação e filtros avançados
+- [x] Upload de avatar
+
+## RBAC
+- [x] Roles (Admin, Manager, User)
+- [x] Permissions granulares (`user:create`, `report:read`, etc)
+- [x] Guard combinando roles + permissions
+
+## Segurança
+- [x] Helmet
+- [x] CORS
+- [x] Rate Limit
+- [x] Validação (Zod + nestjs-zod, integrado ao Swagger via `createZodDto`)
+- [x] Serialização (interceptor de output)
+- [x] CSRF (quando necessário)
+
+## Banco de dados
+- [x] Prisma
+- [x] PostgreSQL
+- [x] Migrations
+- [x] Seed completo (roles, permissions, usuário admin)
+
+## Infra
+- [x] Docker / docker-compose (API, Postgres, Redis, Mailpit)
+- [x] GitHub Actions CI (build, lint, test)
+- [ ] Deploy automatizado (exemplo com Railway/Fly.io)
+
+## Observabilidade
+- [x] Logs estruturados com Pino
+- [x] Health checks (`/health`)
+- [x] Métricas (Prometheus opcional)
+
+## Jobs & E-mail
+- [x] Fila com BullMQ
+- [x] Envio de e-mail transacional (Mailpit em dev)
+- [x] Templates de e-mail
+
+## Testes
+- [x] Estrutura de testes unitários (Vitest)
+- [x] Testes de integração (auth + users)
+
+## Documentação
+- [x] README inicial
+- [x] Swagger completo com exemplos de request/response
+- [x] Guia de arquitetura (ADR / decisões de design)
+- [x] Guia "como adicionar um novo módulo"