🏗️ Exemplos reais ponta-a-ponta

# PLAN.md (versão final, após 3 rodadas)

## Objetivo
Adicionar expiração para links curtos com:
- distinção semântica entre "expirado" (410) e "não existe" (404)
- compatibilidade com cache de CDN
- rollback seguro
- observabilidade completa

## Decisões Técnicas
- Links existentes recebem expires_at = NULL (permanentes por backfill)
- Status HTTP: 410 Gone para expirados, 404 para inexistentes
- TTL da CDN reduzido para 5min na rota /r/:id
- Lock distribuído no job (Redis SET NX) para evitar duplicação
- Audit log em tabela separada para auditoria de compliance

## Etapas
1. **Migration up** (1h)
   - Adicionar expires_at TIMESTAMP NULL
   - Adicionar expired_at TIMESTAMP NULL (auditoria)
   - Index parcial em expires_at para query do job
2. **Migration down testada em staging** (30min)
   - Script de rollback que preserva dados (não DROP COLUMN)
3. **Endpoint GET /r/:id atualizado** (2h)
   - Lógica: SELECT, se NULL → ok; se <NOW() → 410; senão → ok
   - Retorna headers Cache-Control: max-age=300
4. **Endpoint admin POST /links/:id/renew** (2h)
   - Auth obrigatória (admin role)
   - Audit log inserido em cada chamada
5. **Job de limpeza com batch+lock** (4h)
   - Batch size 1000, lock Redis (TTL 10min)
   - Marca expired_at em vez de deletar
6. **Métricas e logs** (2h)
   - app.links.expired_served (counter)
   - app.links.expiration_check_duration (histogram)
   - Logs JSON com level, link_id, action
7. **Testes integração** (3h)
   - Inclui backfill, race conditions, rollback

## Riscos e Mitigações
- **Cache CDN servindo expirados** → TTL reduzido para 5min
- **Race em verificação** → check feito no banco no momento da request
- **Job concorrente** → Redis lock distribuído
- **Migration sem rollback** → script down testado em staging

## Rollback
1. Reverter deploy do app (versão N-1)
2. Migration down: dropar índice, NÃO dropar coluna (preserva dados)
3. CDN TTL pode permanecer em 5min sem efeito adverso

## Observabilidade
- Dashboard Datadog: links.expired_served, links.404, links.410
- Alerta: expired_served > 100/min (indica cache stale)
- Logs estruturados em JSON pra Datadog

## Critério de Aceite
- 99% das requests após expires_at retornam 410 em < 100ms
- Zero erros 500 nas próximas 24h pós-deploy
- Audit log preenchido em 100% das renovações
- Rollback executado com sucesso em staging

## Estimativa total
~14.5h (vs 6h da versão inicial — diferença é o que evita 2 semanas de retrabalho)

# PLAN.md (final)

## Objetivo
Sistema de tracking de comportamento com:
- Conformidade LGPD/GDPR (banner de consentimento)
- Capacidade para 100k eventos/min
- Reprocessamento de eventos perdidos
- Distinção entre usuários anônimos e identificados

## Decisões Técnicas
- Cliente: SDK JS injeta script após consentimento
- Identificação: cookie httpOnly + UUID anônimo (rotacionado)
- Coleta: endpoint POST /track aceita batch (max 100 eventos)
- Fila: Kafka topic events.raw com 12 partições
- Storage: ClickHouse para eventos (analytics), Postgres para metadata
- Dashboard: Metabase consultando ClickHouse

## Etapas
1. **Banner de consentimento** (1 sprint)
   - Modal LGPD com opt-in/opt-out
   - Cookie de preferência (httpOnly, secure, samesite=strict)
2. **SDK JS** (1 sprint)
   - Coleta cliques, scroll depth, tempo na página
   - Buffer local (sendBeacon ou fetch keepalive)
   - Não coleta se não houver consentimento
3. **API de ingestão** (1 sprint)
   - POST /track com validação Zod
   - Push para Kafka com retry exponencial
   - Rate limiting por IP (1k req/min)
4. **Consumer Kafka → ClickHouse** (1 sprint)
   - Worker em Go (alto throughput)
   - Reprocessamento via consumer group dedicado
5. **Dashboard Metabase** (3 dias)
   - Métricas: eventos/min, top cliques, funil
6. **Compliance** (paralelo)
   - DPO valida fluxo
   - Retenção: 90 dias para anônimos, 1 ano para identificados
   - DSR endpoint para deleção

## Riscos
- **Pico de tráfego (100k+ events/min)** → Kafka absorve, autoscaling no consumer
- **Vazamento de PII** → Sanitização no SDK (não captura inputs)
- **Cookie bloqueado** → Funciona com localStorage como fallback (sem cross-device)

## Rollback
- Feature flag: TRACKING_ENABLED. Off → SDK não carrega.
- Kafka retém 7 dias (rebobinável)

## Observabilidade
- Throughput Kafka, lag do consumer, CH insert latency
- Métricas LGPD: % consent, % opt-out, % DSR cumpridos

## Critério de Aceite
- Picos de 100k events/min processados sem perda
- 100% dos usuários no UE veem banner antes do tracking
- DSR (deleção) atendido em < 30 dias
- Dashboard atualizado em < 1 min de delay

# PLAN.md (versão final, 5 rodadas)

## Estratégia: Dual-stack com migração gradual
Não há "big bang". Sistema roda Clerk + auth antiga em
paralelo por 4 semanas. Cada usuário migra na próxima
sessão.

## Decisões Técnicas
- Clerk recebe usuários novos imediatamente
- Middleware tenta Clerk primeiro, fallback pra auth antiga
- Senhas bcrypt: usuário re-autentica no próximo login
  (Clerk re-hasha em bcrypt-clerk)
- MFA TOTP: prompt pra re-cadastrar device antes da migração
- Custom claims migrados via metadata do Clerk

## Etapas (4 semanas)
- Semana 1: Setup Clerk + middleware dual
- Semana 2: Novos usuários no Clerk; migração de devs como teste
- Semana 3: Banner de "re-login para migrar" + email outbound
- Semana 4: 95%+ migrados; corte oficial; auth antiga read-only
- Semana 5: Remoção do código antigo

## Riscos e Mitigações (resumo de 18 itens)
- **Sessão quebra ao migrar** → grace period de 24h aceita ambos
- **MFA perdido** → email com QR code pra re-cadastro
- **Sessions servidor-side** → migra em background com worker
- **Webhook do Clerk falha** → fila de retry com 3 tentativas
- **Compliance auditor** → log estruturado de cada migração

## Rollback
Se <50% migraram em 2 semanas:
1. Desabilitar Clerk no middleware (flag)
2. Auth antiga reativada
3. Usuários migrados ainda funcionam (Clerk é addon)

Se >90% migraram:
4. Não há rollback; só forward fix.

## Observabilidade
- % usuários migrados (gauge)
- Latência do middleware (histogram)
- Erros de auth por origem (clerk vs antiga)
- Re-cadastros de MFA bem-sucedidos / falhos

## Critério de Aceite
- 0 incidentes de "fui deslogado sem motivo"
- 95% migrados em 4 semanas
- 100% das migrações com audit log
- MFA preservado para 100% dos usuários que tinham
- Custom claims funcionam idênticos pré/pós-migração