nexus-core-v3 3.0.0

package/knowledge/architecture/distributed-patterns-cheatsheet.md

@@ -0,0 +1,201 @@
+---
+id: distributed-patterns-cheatsheet
+domain: architecture
+agents: [architect]
+when: "ao escolher protocolos, comunicação e padrões de resiliência num sistema distribuído"
+---
+
+# Distributed Patterns — cheatsheet de decisão "use X quando Y"
+
+## O problema
+
+A maioria das arquiteturas distribuídas erra não por falta de conhecimento, mas por **default não justificado**: escolhe-se REST porque é o que se conhece, retry porque "é seguro", blue-green porque soa robusto — sem amarrar a escolha ao critério que a justifica. O resultado é previsível: gRPC interno que ninguém consegue debugar no browser, retries que amplificam um incidente em vez de absorvê-lo, rate limiter que deixa passar o dobro do limite na virada da janela, deploy que custa 2x sem precisar.
+
+Este pack é uma **régua de decisão**. Cada item tem o **critério de escolha** (o "quando Y") e o **trade-off** que você está aceitando. Se você não consegue nomear o Y, não escolha o X — o default está te traindo.
+
+## Os princípios / o conhecimento
+
+### 1. Estilo de API — REST vs GraphQL vs gRPC vs WebSocket
+
+A confusão comum é tratá-los como concorrentes. **São complementos.** O mapa mental sólido: REST para API pública, gRPC para serviço interno, GraphQL para necessidade de dados orientada ao cliente, WebSocket para tempo real bidirecional.
+
+| Estilo | Transporte / formato | Use quando | Trade-off que você aceita |
+|---|---|---|---|
+| **REST** | HTTP/1.1 + JSON | API pública, integração externa, recursos CRUD, quando cache de infra (CDN/proxy) importa | Over/under-fetching; múltiplos round-trips para dados relacionados |
+| **GraphQL** | HTTP + schema/query | Cliente decide o shape dos dados; agrega N fontes num gateway; payloads onde se pega só o necessário | Cache HTTP fraco (POST único); complexidade de servidor; risco de query cara N+1 |
+| **gRPC** | HTTP/2 + Protobuf (binário, IDL) | Comunicação serviço-a-serviço interna, baixa latência, contratos fortes, streaming | **Não roda no browser** (XHR não fala HTTP/2 puro); binário não é human-readable; sem cache HTTP nativo |
+| **WebSocket** | TCP full-duplex, conexão longa | Tempo real bidirecional (chat, presença, dados ao vivo) entre muitos clientes e o servidor | Conexão persistente consome recurso do servidor; escala horizontal exige sticky session / estado distribuído |
+
+**Números reais para calibrar:**
+- gRPC é tipicamente **5 a 10x mais rápido que REST** em benchmarks — vem do HTTP/2 (multiplexing de várias requests numa conexão) + Protobuf binário.
+- WebSocket ganha em **latência para mensagens pequenas e frequentes** porque elimina o handshake repetido — exatamente onde REST sangra.
+
+**Tells de escolha errada:**
+- gRPC exposto direto ao browser → precisa de gRPC-Web/proxy; sinal de que REST ou GraphQL era o certo na borda.
+- WebSocket para request-response pontual → você pagou conexão persistente por nada.
+- GraphQL numa API com 3 endpoints estáveis → complexidade sem retorno; REST resolvia.
+
+### 2. API Gateway — a borda única
+
+O gateway é o ponto de entrada que faz o que cada serviço não deve repetir: **autenticação/autorização, rate limiting, roteamento, agregação de respostas, terminação TLS, observabilidade**. Use quando há múltiplos serviços atrás de uma fachada e você quer cross-cutting concerns num lugar só.
+
+| Responsabilidade | Por que no gateway, não no serviço |
+|---|---|
+| AuthN / AuthZ | Não duplicar verificação de token em N serviços |
+| Rate limiting | Proteger o backend inteiro de um cliente abusivo |
+| Roteamento / versionamento | Desacoplar URL pública da topologia interna |
+| Agregação | Compor resposta de vários serviços (BFF) numa chamada |
+| TLS termination / observabilidade | Ponto único de métricas, logs, tracing |
+
+**Trade-off:** o gateway é um **single point of failure** e ponto de latência — exige HA e cuidado para não virar monolito disfarçado. Não coloque lógica de negócio nele.
+
+### 3. Síncrono vs Assíncrono
+
+| Critério | Síncrono (request-response) | Assíncrono (mensagem/evento) |
+|---|---|---|
+| Acoplamento temporal | Forte — chamador espera | Fraco — fire-and-forget |
+| Use quando | Precisa da resposta agora para continuar (consulta, validação) | Pode processar depois; desacoplar produtor e consumidor; absorver picos |
+| Falha do downstream | Propaga imediatamente ao chamador | Absorvida pela fila; reprocessa depois |
+| Trade-off | Cascata de latência e de falha entre serviços | Complexidade: eventual consistency, ordenação, idempotência obrigatória |
+
+Regra prática: **toda cadeia síncrona longa é uma cascata de falha esperando acontecer.** Se a operação não precisa do resultado em linha, torne-a assíncrona.
+
+### 4. Message Queue vs Event Streaming
+
+Ambos são assíncronos, mas resolvem coisas diferentes. Confundir os dois é um erro clássico.
+
+| Dimensão | Message Queue (ex.: RabbitMQ, SQS) | Event Streaming (ex.: Kafka) |
+|---|---|---|
+| Modelo | Fila: mensagem **consumida e removida** | Log append-only: evento **retido e re-lido** |
+| Consumidores | Tipicamente 1 consumidor por mensagem (work queue) | N consumidores independentes, cada um com seu offset |
+| Replay | Não (mensagem some após ack) | Sim (re-processa do offset, retém por tempo/tamanho) |
+| Ordem | Por fila | Por partição |
+| Use quando | Distribuir tarefas/jobs, desacoplar work, balancear carga | Pipeline de eventos, event sourcing, múltiplos consumidores, auditoria/replay, alto throughput |
+| Trade-off | Sem histórico; difícil ter múltiplas views do mesmo evento | Mais operacional (partições, offsets, retenção); ordem só dentro da partição |
+
+**Por que Kafka é rápido (para citar):** escrita sequencial em disco (append-only), zero-copy no envio ao consumidor, e batching — evita o custo de I/O aleatório.
+
+### 5. Idempotência
+
+Idempotência é a **pré-condição de qualquer retry seguro**. Operação idempotente = executá-la N vezes tem o mesmo efeito de executá-la uma vez. Sem isso, retry vira cobrança duplicada.
+
+**Top casos onde aplicar idempotência:**
+1. **Pagamentos / cobrança** — retry não pode cobrar duas vezes.
+2. **Criação de recurso** (POST que cria pedido) — request duplicado não cria dois pedidos.
+3. **Consumo de mensagem** (at-least-once delivery) — a mesma mensagem pode chegar 2x.
+4. **Webhooks** — provedores reenviam em caso de timeout.
+5. **Retries automáticos** entre serviços.
+6. **Operações disparadas por usuário** (double-click no "Comprar").
+
+**Como implementar:** **idempotency key** — o cliente envia um ID único (header `Idempotency-Key`); o servidor guarda o resultado da primeira execução e, em requests repetidos com a mesma key, retorna o resultado cacheado em vez de re-executar.
+
+### 6. Retries — estratégias
+
+Retry resolve **falha transitória** (timeout momentâneo, blip de rede). Não resolve serviço caído — para isso é circuit breaker.
+
+| Estratégia | Comportamento | Risco |
+|---|---|---|
+| **Retry imediato** | Tenta de novo na hora | Pode martelar serviço já estressado |
+| **Intervalo fixo** | Espera X ms entre tentativas | Retries sincronizados de N clientes = thundering herd |
+| **Exponential backoff** | Atraso cresce a cada tentativa (1s, 2s, 4s, 8s…) | Reduz pressão, mas ainda sincroniza se todos começam juntos |
+| **Backoff + jitter** | Backoff exponencial **com aleatoriedade** no intervalo | **Recomendado** — espalha os retries, evita retry storm / thundering herd |
+
+**Regras invioláveis do retry:**
+- **Limite o número** de tentativas (bounded) — retry infinito amplifica incidente.
+- **Só retentar operação idempotente** — senão duplica efeito colateral.
+- **Instrumente** — sem métrica, retries escondem o incidente em vez de absorvê-lo.
+- **Só para transitório** — se a falha é persistente, retry só piora.
+
+### 7. Resiliência — Circuit Breaker
+
+O circuit breaker protege contra **falha não-transitória** (serviço down): para de chamar o downstream para não desperdiçar recurso e dar fôlego pra ele se recuperar. Três estados:
+
+| Estado | Comportamento | Transição |
+|---|---|---|
+| **CLOSED** | Operação normal; todas as requests passam | Falhas acima do threshold → OPEN |
+| **OPEN** | Bloqueia tudo; **falha imediata** sem chamada de rede | Após timeout configurado (tipicamente 30s a poucos minutos) → HALF-OPEN |
+| **HALF-OPEN** | Deixa passar **1 ou poucas** requests de teste | Sucesso → CLOSED; falha → volta a OPEN e reinicia o timer |
+
+**Circuit breaker vs Retry — quando cada um:**
+
+| | Retry | Circuit Breaker |
+|---|---|---|
+| Trata | Falha **transitória** (blip momentâneo) | Falha **persistente** (serviço provavelmente down) |
+| Efeito | Tenta de novo | Para de tentar para não piorar |
+| Juntos | Retry **dentro** do CLOSED; o breaker corta o retry quando vira OPEN | Complementares, não substitutos |
+
+Combine com **bulkhead** (isolar thread pools para que um downstream lento não consuma todas as threads) e **timeout** (toda chamada remota tem prazo).
+
+### 8. Resiliência — Rate Limiting (os 5 algoritmos)
+
+Escolher o algoritmo errado custa caro: ou você deixa passar burst que derruba o backend (boundary exploit), ou gasta memória demais para precisão que não precisa.
+
+| Algoritmo | Como funciona | Use quando | Trade-off |
+|---|---|---|---|
+| **Token Bucket** | Bucket enche tokens a taxa fixa; cada request consome 1; bucket = capacidade de burst | **Default para API pública** — modela burst separado da taxa sustentada; permite picos controlados reais | Precisa afinar tamanho do bucket vs taxa de refill |
+| **Leaky Bucket** | Fila drena a taxa **constante**; request entra na fila, rejeitado se cheia | Saída suave e constante, independente do burst de entrada (proteger downstream que odeia picos) | Enfileira → adiciona latência; descarta na fila cheia |
+| **Fixed Window Counter** | Conta requests por janela fixa (ex.: por minuto) | Simplicidade máxima; throttle de login, limites básicos, serviço interno onde aproximação serve | **Boundary exploit**: na virada da janela pode passar até 2x o limite |
+| **Sliding Window Log** | Guarda timestamp **exato** de cada request recente | Precisão máxima e auditoria — pagamento, autenticação, endpoint que exige contagem exata | Maior custo de memória e operação (guarda cada timestamp) |
+| **Sliding Window Counter** | Aproxima a janela deslizante ponderando janela atual + anterior | **Melhor compromisso em escala distribuída** — reduz o boundary burst com custo baixo, alto throughput | Aproximação (não tão exato quanto o log), mas bom o suficiente |
+
+**Regra de bolso:** API pública → **token bucket**. Precisa de exatidão/auditoria → **sliding window log**. Escala distribuída com eficiência → **sliding window counter**. Saída precisa ser perfeitamente suave → **leaky bucket**. Só simplicidade e tolera burst de borda → **fixed window**.
+
+### 9. Estratégias de Deploy
+
+| Estratégia | Como | Downtime | Rollback | Risco | Custo infra | Complexidade | Use quando |
+|---|---|---|---|---|---|---|---|
+| **Rolling** | Substitui instâncias aos poucos | Não | **Lento** | Médio | 1x–1.25x | Baixa | Bug fixes de rotina; default barato |
+| **Blue-Green** | Dois ambientes idênticos; troca **todo** o tráfego de uma vez | Não | **Instantâneo** | Baixo | **2x** | Média | Patch crítico de segurança; release que exige rollback imediato |
+| **Canary** | Roteia % pequeno (ex.: 25%) pro novo, observa, então expande | Não | **Rápido** | Baixo | 1x–1.1x | **Alta** | Release de feature grande; quer validar com tráfego real antes do full rollout |
+| **A/B Testing** | Variantes para medir comportamento (experimento, não mitigação) | Não | Rápido | **Maior** (sem rollback por erro/latência automático) | 1x–1.1x | Média | Experimento de produto; ambas versões já estáveis |
+| **Shadow** | Espelha tráfego real pro novo **sem retornar resposta ao usuário** | Não | N/A | Nenhum (usuário não afetado) | 2x | Alta | Validar código novo com workload real sem impacto no usuário |
+
+**Feature flags são ortogonais:** desacoplam **deploy de release**. Você faz deploy do código com qualquer estratégia, mas mantém a feature desligada e liga via config — gradualmente, sem novo deploy.
+
+**Critério de escolha resumido:** bug fix rotineiro → rolling; feature grande → canary; patch crítico que precisa de reversão instantânea → blue-green; quer medir comportamento → A/B; quer testar sob carga real sem risco → shadow.
+
+## Checklist
+
+Antes de fechar a arquitetura, responda — cada "não" é um default não justificado a revisar:
+
+- [ ] Para cada API, eu sei nomear **por que** REST/GraphQL/gRPC/WebSocket e não o outro?
+- [ ] Tem gRPC que precisa ser consumido pelo browser? (vai precisar de proxy/gRPC-Web)
+- [ ] Cross-cutting concerns (auth, rate limit, TLS) estão no **gateway**, não duplicados nos serviços?
+- [ ] As cadeias síncronas longas foram revisadas — o que pode ser assíncrono virou assíncrono?
+- [ ] A escolha fila vs streaming bate com a necessidade de **replay / múltiplos consumidores**?
+- [ ] Toda operação retentável é **idempotente** (idempotency key onde há efeito colateral)?
+- [ ] Os retries têm **limite**, usam **backoff + jitter**, e são **só para falha transitória**?
+- [ ] Chamadas a downstream têm **timeout + circuit breaker** (e bulkhead onde compartilham pool)?
+- [ ] O algoritmo de rate limiting foi escolhido pelo critério (token bucket default; log p/ exatidão; counter p/ escala)?
+- [ ] A estratégia de deploy bate com o **custo de rollback** aceitável (instantâneo → blue-green; gradual → canary)?
+- [ ] Feature flags separam **deploy de release** onde faz sentido?
+
+## Tabela de decisão "use X quando Y"
+
+| Decisão (X) | Escolha quando (Y) | Trade-off aceito |
+|---|---|---|
+| **REST** | API pública/externa, CRUD, cache de CDN importa | Over/under-fetching, round-trips |
+| **GraphQL** | Cliente dita o shape; agrega N fontes | Cache HTTP fraco, risco N+1 |
+| **gRPC** | Serviço↔serviço interno, baixa latência, contrato forte | Sem browser nativo, binário, sem cache HTTP |
+| **WebSocket** | Tempo real bidirecional, muitas conexões vivas | Recurso por conexão, sticky sessions na escala |
+| **API Gateway** | N serviços atrás de uma borda com cross-cutting concerns | SPOF + latência; exige HA |
+| **Assíncrono** | Não precisa da resposta em linha; absorver picos | Eventual consistency, idempotência obrigatória |
+| **Message Queue** | Distribuir jobs, 1 consumidor por mensagem | Sem replay/histórico |
+| **Event Streaming** | Múltiplos consumidores, replay, auditoria, alto throughput | Ops de partição/offset/retenção |
+| **Idempotency key** | Qualquer operação com efeito colateral que pode ser retentada | Estado extra para guardar resultados |
+| **Backoff + jitter** | Retry de falha transitória sob concorrência | Latência adicional na recuperação |
+| **Circuit Breaker** | Downstream provavelmente down (falha persistente) | Falha rápida temporária enquanto OPEN |
+| **Token Bucket** | Rate limit de API pública com burst real | Afinar bucket vs refill |
+| **Sliding Window Log** | Rate limit com exatidão/auditoria (pagamento, auth) | Custo de memória por timestamp |
+| **Sliding Window Counter** | Rate limit em escala distribuída eficiente | Aproximação (não exato) |
+| **Leaky Bucket** | Saída precisa ser constante/suave pro downstream | Latência de fila; descarte na fila cheia |
+| **Fixed Window** | Throttle simples, tolera burst de borda | Boundary exploit (até 2x na virada) |
+| **Rolling deploy** | Bug fix de rotina, custo baixo | Rollback lento |
+| **Blue-Green** | Patch crítico, rollback instantâneo necessário | Custo de infra 2x |
+| **Canary** | Feature grande, validar com tráfego real | Alta complexidade de pipeline |
+| **Shadow** | Testar sob carga real sem risco ao usuário | Custo 2x, sem resposta ao usuário |
+| **Feature flags** | Separar deploy de release; rollout gradual por config | Gestão de flags / débito se não limpar |
+
+---
+
+> **Fonte de referência:** ByteByteGo — *system-design-101* (github.com/ByteByteGoHq/system-design-101), seções "SOAP vs REST vs GraphQL vs RPC", "What is gRPC?", "API Gateway 101", "Types of Message Queues", "Kafka 101 / Why is Kafka Fast?", "Top 6 Cases to Apply Idempotency", "Retry Strategies for System Failures", "Resiliency Patterns", "Top 5 Most-Used Deployment Strategies". Números e critérios consolidados com fontes públicas de engenharia (rate limiting, circuit breaker, deployment trade-offs).

package/knowledge/architecture/saas-subscription-blueprint.md

@@ -0,0 +1,355 @@
+---
+id: saas-subscription-blueprint
+domain: architecture
+agents: [architect]
+when: "ao construir um SaaS que cobra assinatura (do zero ao faturamento)"
+---
+
+# SaaS de assinatura — do zero ao primeiro faturamento
+
+Blueprint extraído do `nextjs/saas-starter` (Vercel) — o starter oficial com Next.js (App Router),
+Postgres, Drizzle, Stripe e shadcn/ui. Tudo aqui é **grounded no código real** do template, não em
+"boas práticas" abstratas. O objetivo é dar ao arquiteto o caminho concreto: schema, fluxo de cobrança,
+auth, RBAC e os pontos onde o starter falha de propósito (e você não pode copiar cego).
+
+## O problema
+
+"Fazer um SaaS" parece um épico, mas o caminho comercial mínimo é estreito e conhecido: **alguém se
+cadastra, vira dono de um team, escolhe um plano, paga no Stripe, e o estado da assinatura volta pro seu
+banco via webhook.** A maioria das tentativas erra em um de quatro lugares:
+
+1. **Modelam billing no usuário, não no team.** Aí quando o cliente quer convidar um colega, o plano não
+   acompanha — assinatura é por *conta de cobrança* (team), não por pessoa.
+2. **Confiam no redirect de sucesso do Checkout pra liberar acesso.** O redirect é cosmético e burlável;
+   a fonte de verdade do estado da assinatura é **o webhook**, não a URL de retorno.
+3. **Reinventam o portal de billing** (trocar cartão, cancelar, fazer upgrade) — quando o Stripe Customer
+   Portal já faz isso hospedado e PCI-compliant.
+4. **Esquecem o RBAC.** Qualquer membro consegue remover o dono ou convidar gente. O próprio starter tem
+   esse buraco — é o tell número 1 de SaaS copiado de template.
+
+Este pack resolve os quatro.
+
+## O conhecimento
+
+### 1. Modelagem: a unidade de cobrança é o `team`, não o `user`
+
+O schema real do starter (Drizzle / Postgres). Note onde os campos do Stripe moram — **em `teams`**:
+
+```ts
+// users — identidade e auth
+users {
+  id            serial PK
+  name          varchar(100)
+  email         varchar(255) NOT NULL UNIQUE
+  passwordHash  text NOT NULL
+  role          varchar(20) NOT NULL DEFAULT 'member'  // role GLOBAL, não de team
+  createdAt     timestamp NOT NULL DEFAULT now()
+  updatedAt     timestamp NOT NULL DEFAULT now()
+  deletedAt     timestamp                               // soft delete
+}
+
+// teams — a CONTA DE COBRANÇA. Stripe vive aqui.
+teams {
+  id                    serial PK
+  name                  varchar(100) NOT NULL
+  createdAt             timestamp NOT NULL DEFAULT now()
+  updatedAt             timestamp NOT NULL DEFAULT now()
+  stripeCustomerId      text UNIQUE      // 1 customer Stripe por team
+  stripeSubscriptionId  text UNIQUE
+  stripeProductId       text
+  planName              varchar(50)
+  subscriptionStatus    varchar(20)      // espelho do status do Stripe
+}
+
+// teamMembers — a relação N:N + a role DE TEAM (esta é a que importa pro RBAC)
+teamMembers {
+  id        serial PK
+  userId    integer NOT NULL FK -> users.id
+  teamId    integer NOT NULL FK -> teams.id
+  role      varchar(50) NOT NULL         // 'owner' | 'member'
+  joinedAt  timestamp NOT NULL DEFAULT now()
+}
+
+// invitations — convite pendente por e-mail, aceito no signup
+invitations {
+  id         serial PK
+  teamId     integer NOT NULL FK -> teams.id
+  email      varchar(255) NOT NULL
+  role       varchar(50) NOT NULL
+  invitedBy  integer NOT NULL FK -> users.id
+  invitedAt  timestamp NOT NULL DEFAULT now()
+  status     varchar(20) NOT NULL DEFAULT 'pending'  // pending | accepted
+}
+
+// activityLogs — trilha de auditoria append-only
+activityLogs {
+  id         serial PK
+  teamId     integer NOT NULL FK -> teams.id
+  userId     integer FK -> users.id        // nullable (eventos do sistema)
+  action     text NOT NULL                 // valor do enum ActivityType
+  timestamp  timestamp NOT NULL DEFAULT now()
+  ipAddress  varchar(45)                   // 45 = caber IPv6
+}
+```
+
+**Decisão concreta a internalizar:** existem **duas roles** e elas não são a mesma coisa.
+`users.role` é global (útil pra super-admin do produto). `teamMembers.role` é por team (`owner`/`member`)
+— **é esta que governa quem pode convidar, remover e gerenciar billing.** Confundir as duas é como o RBAC
+quebra silenciosamente.
+
+O enum de auditoria (`ActivityType`), com os 10 eventos que o starter rastreia:
+
+```
+SIGN_UP · SIGN_IN · SIGN_OUT · UPDATE_PASSWORD · UPDATE_ACCOUNT · DELETE_ACCOUNT
+CREATE_TEAM · INVITE_TEAM_MEMBER · REMOVE_TEAM_MEMBER · ACCEPT_INVITATION
+```
+
+### 2. Cobrança: Checkout (hospedado) → webhook (fonte de verdade) → Customer Portal
+
+O fluxo tem três peças, e cada uma tem uma responsabilidade que não se mistura.
+
+**a) `createCheckoutSession` — manda o cliente pro Checkout hospedado do Stripe.** Parâmetros reais:
+
+```ts
+stripe.checkout.sessions.create({
+  mode: 'subscription',              // assinatura, não pagamento único
+  payment_method_types: ['card'],
+  line_items: [{ price: priceId, quantity: 1 }],
+  subscription_data: { trial_period_days: 14 },  // trial sem cartão preso na hora
+  allow_promotion_codes: true,       // cupom na própria tela do Stripe
+  success_url: `${baseUrl}/api/stripe/checkout?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url:  `${baseUrl}/pricing`,
+  // ...client_reference_id / customer = vínculo com o team
+})
+```
+Se o usuário não está logado, o starter **redireciona pro sign-up antes** — não dá pra comprar anônimo
+porque a assinatura precisa de um team pra ancorar.
+
+**b) Webhook `POST /api/stripe/webhook` — a ÚNICA fonte de verdade do estado da assinatura.**
+Verificação de assinatura obrigatória (senão qualquer um forja um POST e ganha plano premium):
+
+```ts
+const payload = await request.text();                 // RAW body, não parseado
+const signature = request.headers.get('stripe-signature') as string;
+let event: Stripe.Event;
+try {
+  event = stripe.webhooks.constructEvent(
+    payload, signature, process.env.STRIPE_WEBHOOK_SECRET!
+  );
+} catch (err) {
+  return NextResponse.json(
+    { error: 'Webhook signature verification failed.' }, { status: 400 }
+  );
+}
+
+switch (event.type) {
+  case 'customer.subscription.updated':
+  case 'customer.subscription.deleted':
+    await handleSubscriptionChange(event.data.object as Stripe.Subscription);
+    break;
+  // outros eventos: loga e ignora (não falha)
+}
+return NextResponse.json({ received: true });          // 200 sempre que processou
+```
+
+`handleSubscriptionChange` traduz o status do Stripe pro seu banco:
+
+| Status do Stripe | O que grava em `teams` |
+|---|---|
+| `active` ou `trialing` | preenche `stripeSubscriptionId`, `stripeProductId`, `planName`, `subscriptionStatus` |
+| `canceled` ou `unpaid` | **zera** (`null`) `stripeSubscriptionId`, `stripeProductId`, `planName` |
+
+**Por que isto importa:** o redirect de `success_url` é só UX. O acesso premium do cliente deve ser
+decidido lendo `teams.subscriptionStatus` — que **só** é escrito pelo webhook. Em dev, o webhook chega via
+`stripe listen --forward-to localhost:3000/api/stripe/webhook` (o CLI te dá o `whsec_...` pro
+`STRIPE_WEBHOOK_SECRET`).
+
+**c) `createCustomerPortalSession` — NÃO construa telas de billing.** O starter cria uma configuração de
+portal hospedado do Stripe com:
+- upgrade/downgrade de plano (troca de price, quantidade, cupom);
+- atualização de método de pagamento;
+- cancelamento com **motivo rastreado** (5 opções: `too_expensive`, `missing_features`,
+  `switched_service`, `unused`, `other`);
+- proração habilitada.
+
+Você manda o cliente pro portal e ele volta; o webhook `customer.subscription.updated` sincroniza o
+resultado. Zero tela de cartão no seu código → zero escopo PCI no seu lado.
+
+Leitura de catálogo (pra montar a pricing page a partir do Stripe, não hardcoded):
+`getStripePrices()` retorna `{ id, productId, unitAmount, currency, interval, trialPeriodDays }`;
+`getStripeProducts()` retorna `{ id, name, description, defaultPriceId }`.
+
+### 3. Auth: JWT em cookie HttpOnly + middleware que renova a sessão
+
+Sem provider externo de auth. Sessão é um JWT assinado (`jose`, `HS256`) guardado num cookie:
+
+```ts
+// session.ts
+const SALT_ROUNDS = 10;                         // bcryptjs
+hashPassword(pw)        -> bcrypt hash
+comparePasswords(pw, h) -> bool
+
+signToken(payload)   -> new SignJWT(payload)
+                          .setProtectedHeader({ alg: 'HS256' })
+                          .setIssuedAt()
+                          .setExpirationTime('1 day from now')
+                          .sign(key)            // key = process.env.AUTH_SECRET
+verifyToken(token)   -> jwtVerify(token, key)   // valida HS256
+
+// cookie de sessão:
+cookies().set('session', token, {
+  httpOnly: true,      // JS do browser NÃO lê -> mitiga XSS roubar token
+  secure: true,
+  sameSite: 'lax',     // mitiga CSRF mantendo navegação top-level
+  expires: <24h>,
+})
+```
+
+O **middleware** protege rotas e **renova o token a cada GET** (sessão deslizante de 24h):
+
+```ts
+// middleware.ts
+const protectedRoutes = '/dashboard';
+
+const sessionCookie = request.cookies.get('session');
+const isProtectedRoute = pathname.startsWith(protectedRoutes);
+
+if (isProtectedRoute && !sessionCookie) {
+  return NextResponse.redirect(new URL('/sign-in', request.url));
+}
+
+// em GET com sessão válida: re-assina com nova expiração (+24h) e regrava o cookie
+// se verifyToken falhar: deleta o cookie e redireciona protegidas pro /sign-in
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+  runtime: 'nodejs',   // jose precisa de Node, não Edge runtime
+};
+```
+
+**Decisão concreta:** o middleware faz só o *gate grosso* (tem cookie? rota protegida?). A autorização
+fina (este usuário pode fazer *esta* ação?) **não** mora no middleware — mora na Server Action. Misturar os
+dois é o erro clássico.
+
+### 4. Server Actions: validação + autenticação como wrappers compostos
+
+O starter encapsula o boilerplate de toda action em três wrappers. Use sempre o mais restritivo que serve:
+
+```ts
+type ActionState = { error?: string; success?: string; [key: string]: any };
+
+// 1. valida FormData contra um schema zod
+validatedAction(schema, async (data, formData) => { ... })
+
+// 2. valida + EXIGE usuário autenticado (injeta `user`)
+validatedActionWithUser(schema, async (data, formData, user) => { ... })
+
+// 3. exige user + carrega o team (injeta `team`, redireciona se não logado)
+withTeam(async (formData, team) => { ... })
+```
+
+Padrão de validação real (`zod` + `safeParse`, devolve a 1ª mensagem de erro):
+
+```ts
+const result = schema.safeParse(Object.fromEntries(formData));
+if (!result.success) return { error: result.error.errors[0].message };
+```
+
+### 5. O buraco de RBAC que você NÃO pode copiar
+
+Auditando as actions reais: `removeTeamMember` e `inviteTeamMember` usam `validatedActionWithUser` e
+checam **apenas se o caller pertence a um team** — **não checam se ele é `owner`.** Isso significa que,
+no template como está, **qualquer `member` pode remover qualquer pessoa (inclusive o dono) ou convidar
+gente.** É um tell de SaaS feito de template cru.
+
+O fix concreto que o arquiteto deve impor antes de qualquer mutação sensível:
+
+```ts
+// dentro da action, depois de carregar a membership do caller:
+const callerMembership = await getTeamMembership(user.id, teamId);
+if (callerMembership?.role !== 'owner') {
+  return { error: 'Apenas o dono do time pode gerenciar membros.' };
+}
+```
+
+E toda ação sensível (convidar, remover, mudar plano) deve gravar em `activityLogs` via `logActivity`:
+
+```ts
+async function logActivity(teamId, userId, type: ActivityType, ipAddress?) {
+  if (teamId == null) return;
+  await db.insert(activityLogs).values({
+    teamId, userId, action: type, ipAddress: ipAddress ?? '',
+  });
+}
+```
+
+### 6. O fluxo de convite (signup que aceita invite)
+
+Convite é por e-mail com `status: 'pending'`. No signup, se vier `inviteId`, a action procura o convite
+**casando id + email + status pending**, e só então herda a role do convite e marca `accepted`:
+
+```ts
+const [invitation] = await db.select().from(invitations).where(and(
+  eq(invitations.id, parseInt(inviteId)),
+  eq(invitations.email, email),
+  eq(invitations.status, 'pending'),
+)).limit(1);
+
+if (invitation) {
+  userRole = invitation.role;                          // herda role do convite
+  await db.update(invitations).set({ status: 'accepted' })
+    .where(eq(invitations.id, invitation.id));
+} else {
+  // sem convite válido -> cria team novo e vira 'owner'
+}
+```
+Sem convite válido, o usuário vira `owner` de um team novo. O casamento por e-mail impede aceitar convite
+de outra pessoa.
+
+## Checklist
+
+- [ ] Os campos `stripeCustomerId / stripeSubscriptionId / planName / subscriptionStatus` estão em
+      **`teams`**, não em `users`?
+- [ ] O acesso premium é decidido lendo `teams.subscriptionStatus` (escrito pelo webhook) e **não** pelo
+      redirect de sucesso do Checkout?
+- [ ] O webhook verifica a assinatura com `stripe.webhooks.constructEvent` usando o **raw body** e
+      `STRIPE_WEBHOOK_SECRET`, retornando 400 se falhar?
+- [ ] O webhook trata `customer.subscription.updated` **e** `customer.subscription.deleted`, e
+      **zera** os campos no `canceled`/`unpaid`?
+- [ ] Trocar cartão / cancelar / upgrade vão pro **Customer Portal** hospedado (zero tela de cartão no
+      seu código)?
+- [ ] O cookie de sessão é `httpOnly: true`, `secure: true`, `sameSite: 'lax'`, e o JWT é `HS256` com
+      `AUTH_SECRET`?
+- [ ] O middleware renova o token nos GETs (sessão deslizante) e usa `runtime: 'nodejs'`?
+- [ ] A autorização **fina** mora na Server Action (não no middleware), via wrappers
+      `validatedActionWithUser` / `withTeam`?
+- [ ] Convidar / remover / mudar plano checam `teamMembers.role === 'owner'` **antes** de mutar?
+      (o starter NÃO faz — é o buraco a fechar)
+- [ ] Toda ação sensível grava `activityLogs` com `ActivityType` e IP?
+- [ ] Convite casa **id + email + status pending** antes de herdar a role?
+- [ ] Em dev, o webhook chega via `stripe listen --forward-to .../api/stripe/webhook` com `whsec_`?
+
+## Tabela de decisão
+
+| Você precisa de... | Faça assim (grounded no starter) | Não faça |
+|---|---|---|
+| Unidade de cobrança | Campos Stripe em `teams`; 1 `stripeCustomerId` por team | Billing por usuário individual |
+| Liberar acesso premium | Ler `teams.subscriptionStatus` (sync do webhook) | Confiar no `success_url` do Checkout |
+| Coletar pagamento | Stripe Checkout hospedado (`mode: 'subscription'`) | Formulário de cartão próprio (vira escopo PCI) |
+| Trocar cartão / cancelar / upgrade | Stripe Customer Portal hospedado | Construir telas de billing do zero |
+| Saber o estado real da assinatura | Webhook com `constructEvent` + `STRIPE_WEBHOOK_SECRET` | Polling da API ou estado no cliente |
+| Trial | `subscription_data: { trial_period_days: 14 }` | Lógica de trial própria no seu banco |
+| Sessão | JWT `HS256` (jose) em cookie `httpOnly`+`secure`+`sameSite:lax` | Token em `localStorage` (XSS lê) |
+| Gate de rota | Middleware: tem cookie? rota protegida? renova no GET | Checar permissão fina no middleware |
+| Permissão fina (quem pode o quê) | Na Server Action, cheque `teamMembers.role === 'owner'` | Assumir que membership == permissão |
+| Validar input de action | `validatedAction*` + `zod.safeParse(Object.fromEntries(formData))` | Validação manual espalhada |
+| Auditoria | `logActivity` append-only em `activityLogs` com `ActivityType` | Sem trilha (impossível investigar abuso) |
+| Convite de membro | `invitations` por e-mail, `pending` → `accepted` casando id+email | Adicionar membro direto sem aceite |
+| Runtime do middleware | `runtime: 'nodejs'` (jose não roda em Edge) | Edge runtime com `jose`/crypto Node |
+
+---
+
+**Fonte:** [`nextjs/saas-starter`](https://github.com/nextjs/saas-starter) (Vercel) — Next.js App Router,
+Postgres, Drizzle, Stripe, shadcn/ui. Schema, fluxo de billing, auth, middleware e actions extraídos do
+código real do template. O buraco de RBAC em `removeTeamMember`/`inviteTeamMember` é uma característica
+conhecida do starter — está aqui de propósito, como armadilha a corrigir.