🚀 Cap 06: Stack Enterprise TypeScript: NestJS (Clean Architecture) e Next.js App Router (SSR/RSC)

Arquitetura de Aplicações Full Stack

🗺️ Mapa Conceitual

flowchart LR
    NAV["🌐 Navegador"] -->|"HTML pronto + ilhas interativas"| NEXT["▲ Next.js App Router<br/>Server · Client · Route Handlers"]
    NEXT -->|"servidor → servidor"| NEST["🐈 NestJS<br/>Guard → Pipe → Controller → Service"]
    NEST --> PG[("🐘 PostgreSQL")]

    style NEXT fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px
    style NEST fill:#fce4ec,stroke:#e91e63,stroke-width:2px

🧩 O problema

• Express + React: liberdade demais para equipes grandes
• SPA entrega HTML vazio: “Carregando…” e SEO fraco
• NestJS impõe a estrutura da API; Next.js gera o HTML no servidor

🐈 NestJS em 3 peças

• Módulo: declara controllers e providers
• Controller: as rotas (@Get, @Post)
• Service com @Injectable(): a regra de negócio
• Injeção pelo construtor: o controller declara, o Nest entrega

🛂 O caminho da requisição

🛡️ ValidationPipe

new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true })

• Regras no DTO (@IsPositive(), @MinLength(3))
• whitelist: bloqueia o mass assignment ("role": "ADMIN" no cadastro)
• Todas as violações voltam juntas numa lista

▲ Server × Client Components

"use client" só nas folhas interativas.

🔐 Next.js como BFF

• Route Handler recebe o login e chama o NestJS
• JWT vai para cookie HttpOnly: o JavaScript da página não lê
• middleware.ts redireciona /admin sem cookie para /login
• O guard do NestJS continua obrigatório: a API pode ser chamada sem o Next

🔄 Next 14 → Next 15

• cookies() e headers() agora são assíncronos
• fetch não entra em cache por padrão
• Diga o que quer: next: { revalidate: 60 } ou cache: "no-store"

⚖️ Como cada página é gerada

⚠️ Armadilhas

• Serviço fora dos providers → “Nest can’t resolve dependencies” na subida
• Sem @Injectable() + dependências → sobe e quebra na 1ª chamada
• "use client" no layout → a página inteira vira JavaScript
• revalidate com dados fixos no código → a página nunca muda

🗂️ No Catálogo

• fullstack_tecloja_04_nest_nextjs (guia): Módulos 02, 03, 05 (NestJS), 06 (RSC) e 07 (BFF)
• No código: schema.prisma real; page.tsx com produtos fixos e revalidate inútil
• fullstack_tecloja_03_nest_react: ProductsService sem @Injectable(), base do exercício 06.1