Araponga Logo

Wiki Araponga

Documentação Completa

Fase 1: Segurança e Fundação Crítica

Duração: 2 semanas (14 dias úteis)
Prioridade: 🔴 CRÍTICA
Bloqueia: Deploy em produção
Estimativa Total: 112 horas
Status: ✅ COMPLETA (conforme FASE1_IMPLEMENTACAO_RESUMO.md)

🎯 Objetivo

Resolver todos os bloqueantes críticos e estabelecer base sólida para produção.

📋 Tarefas Detalhadas

Semana 1: Segurança Crítica e Configuração

1.1 JWT Secret Management ✅

Estimativa: 4 horas
Status: ✅ Completo

Tarefas:

  • Verificar que SigningKey não está em appsettings.json
  • Melhorar validação de secret (mínimo 32 caracteres)
  • Adicionar validação de valor padrão em produção
  • Adicionar rotação de secrets (ISecretRotationService) - Futuro
  • Documentar processo de configuração

Arquivos Modificados:

  • backend/Arah.Api/Program.cs (linhas 40-47)

Critérios de Sucesso:

  • ✅ Secret não está em código ou appsettings.json
  • ✅ Validação falha rápido se secret não configurado
  • ✅ Secret mínimo de 32 caracteres em produção
  • ✅ Validação de valor padrão

1.2 Rate Limiting Completo ✅

Estimativa: 6 horas
Status: ✅ Completo

Tarefas:

  • Melhorar rate limiting por endpoint (auth, feed, write)
  • Adicionar rate limiting por usuário autenticado
  • Adicionar headers X-RateLimit-* (Retry-After)
  • Aplicar limiters em todos os controllers críticos

Arquivos Modificados:

  • backend/Arah.Api/Program.cs (linhas 78-112)
  • Todos os controllers (11 controllers)

Critérios de Sucesso:

  • ✅ Rate limiting global funcionando
  • ✅ Rate limiting por endpoint (auth: 5 req/min, feed: 100 req/min, write: 30 req/min)
  • ✅ Rate limiting por usuário autenticado
  • ✅ Headers X-RateLimit-* retornados
  • ✅ Retorno 429 quando excedido

1.3 HTTPS e Security Headers ✅

Estimativa: 4 horas
Status: ✅ Completo

Tarefas:

  • Forçar HTTPS em produção
  • Configurar HSTS (HTTP Strict Transport Security)
  • Adicionar security headers (CSP, X-Frame-Options, etc.)
  • Criar SecurityHeadersMiddleware

Arquivos Criados:

  • backend/Arah.Api/Middleware/SecurityHeadersMiddleware.cs

Arquivos Modificados:

  • backend/Arah.Api/Program.cs

Critérios de Sucesso:

  • ✅ HTTPS obrigatório em produção
  • ✅ HSTS configurado (Preload, IncludeSubDomains, MaxAge: 365 dias)
  • ✅ Security headers presentes em todas as respostas
  • ✅ CSP configurado

1.4 Health Checks Completos ✅

Estimativa: 16 horas (2 dias)
Status: ✅ Completo

Tarefas:

  • Criar DatabaseHealthCheck para PostgreSQL
  • Criar StorageHealthCheck para S3/Local
  • Criar CacheHealthCheck para IMemoryCache/Redis
  • Adicionar health check de Event Bus
  • Configurar health checks no Program.cs
  • Criar endpoints /health/ready (readiness)
  • Criar endpoints /health/live (liveness)
  • Documentar health checks

Arquivos a Criar:

  • backend/Arah.Api/HealthChecks/ (novo diretório)
  • backend/Arah.Api/HealthChecks/DatabaseHealthCheck.cs
  • backend/Arah.Api/HealthChecks/StorageHealthCheck.cs
  • backend/Arah.Api/HealthChecks/CacheHealthCheck.cs
  • backend/Arah.Api/HealthChecks/EventBusHealthCheck.cs

Arquivos a Modificar:

  • backend/Arah.Api/Program.cs

Critérios de Sucesso:

  • ✅ Todos os health checks retornam status correto
  • ✅ Endpoints /health/ready e /health/live funcionando
  • ✅ Health checks verificam dependências críticas
  • ✅ Documentação completa

1.5 Connection Pooling Explícito ✅

Estimativa: 8 horas (1 dia)
Status: ✅ Completo

Tarefas:

  • Configurar connection string com pooling (MinPoolSize: 5, MaxPoolSize: 100)
  • Adicionar retry policies no EF Core (maxRetryCount: 3)
  • Configurar command timeout (30s)
  • Adicionar métricas de conexões
  • Documentar configuração

Arquivos a Modificar:

  • backend/Arah.Api/appsettings.json
  • backend/Arah.Infrastructure/Postgres/ArapongaDbContext.cs

Critérios de Sucesso:

  • ✅ Pool configurado (MinPoolSize: 5, MaxPoolSize: 100)
  • ✅ Retry policies configuradas (maxRetryCount: 3)
  • ✅ Command timeout configurado (30s)
  • ⚠️ Métricas de conexões ainda pendentes

1.6 Índices de Banco de Dados ⚠️

Estimativa: 16 horas (2 dias)
Status: ⚠️ Parcial

Tarefas:

  • Criar migration AddPerformanceIndexes
  • Adicionar índice em territory_memberships (user_id, territory_id)
  • Adicionar índice em community_posts (territory_id, status, created_at_utc)
  • Adicionar índice em moderation_reports (target_type, target_id, created_at_utc)
  • Adicionar índice em notifications (user_id, created_at_utc)
  • Adicionar índice em chat_messages (conversation_id, created_at_utc)
  • Testar performance antes/depois
  • Validar em staging

Arquivos a Criar:

  • backend/Arah.Infrastructure/Postgres/Migrations/XXXXXX_AddPerformanceIndexes.cs

Critérios de Sucesso:

  • ✅ Todos os índices criados
  • ✅ Queries críticas com latência < 100ms (P95)
  • ✅ Sem impacto negativo em writes
  • ✅ Migration testada em staging

Semana 2: Validação e Tratamento de Erros

2.1 Validação Completa de Input ✅

Estimativa: 16 horas (2 dias)
Status: ✅ Completo

Tarefas:

  • Criar validators para endpoints críticos (8 novos validators)
  • Criar CommonValidators.cs para padronizar validações
  • Criar GeoValidationRules.cs para validação de geolocalização
  • Testar todos os validators
  • Documentar validações

Validators Criados:

  1. ✅ CreateAssetRequestValidator.cs
  2. ✅ SuggestMapEntityRequestValidator.cs
  3. ✅ UpsertStoreRequestValidator.cs
  4. ✅ CreateItemRequestValidator.cs
  5. ✅ SuggestTerritoryRequestValidator.cs
  6. ✅ UpdatePrivacyPreferencesRequestValidator.cs
  7. ✅ UpdateDisplayNameRequestValidator.cs
  8. ✅ UpdateContactInfoRequestValidator.cs

Arquivos Criados:

  • backend/Arah.Api/Validators/CommonValidators.cs
  • backend/Arah.Api/Validators/GeoValidationRules.cs
  • 8 novos validators

Critérios de Sucesso:

  • ✅ Validators para endpoints críticos criados
  • ✅ Validação falha antes de chegar nos services
  • ✅ Mensagens de erro claras e em português
  • ✅ Validação de geolocalização, emails, URLs

2.2 Exception Mapping com Exceções Tipadas ⚠️

Estimativa: 24 horas (3 dias)
Status: ⚠️ Parcial

Tarefas:

  • Criar DomainException base
  • Criar ValidationException
  • Criar NotFoundException
  • Criar UnauthorizedException
  • Criar ConflictException
  • Criar ForbiddenException
  • Atualizar exception handler com mapeamento completo
  • Migrar services para usar exceções tipadas
  • Atualizar testes
  • Documentar estratégia

Arquivos a Criar:

  • backend/Arah.Application/Exceptions/DomainException.cs
  • backend/Arah.Application/Exceptions/ValidationException.cs
  • backend/Arah.Application/Exceptions/NotFoundException.cs
  • backend/Arah.Application/Exceptions/UnauthorizedException.cs
  • backend/Arah.Application/Exceptions/ConflictException.cs
  • backend/Arah.Application/Exceptions/ForbiddenException.cs

Arquivos a Modificar:

  • backend/Arah.Api/Program.cs (exception handler)
  • Todos os services (migração gradual)

Critérios de Sucesso:

  • ✅ Todas as exceções tipadas criadas
  • ✅ Exception handler mapeia todas as exceções
  • ✅ Services usam exceções tipadas
  • ⚠️ Testes ainda pendentes
  • ✅ Documentação completa

2.3 Completar Migração Result ⚠️

Estimativa: 16 horas (2 dias)
Status: ⚠️ Parcial

Tarefas:

  • Identificar services ainda usando tuplas
  • Migrar TerritoryService para Result
  • Migrar MembershipService para Result
  • Migrar MapService para Result
  • Migrar EventsService para Result
  • Migrar ReportService para Result
  • Migrar StoreService para Result
  • Migrar PostCreationService para Result
  • Migrar PostInteractionService para Result
  • Migrar FeedService para Result
  • Migrar InquiryService para Result
  • Migrar HealthService para Result
  • Migrar AssetService para Result
  • Atualizar controllers para usar Result
  • Atualizar testes
  • Documentar padrão

Arquivos a Modificar:

  • Todos os services que ainda usam tuplas
  • Controllers correspondentes
  • Testes correspondentes

Critérios de Sucesso:

  • ✅ Nenhum service usa tuplas
  • ✅ Todos os services retornam Result
  • ✅ Controllers atualizados
  • ✅ Testes atualizados
  • ✅ Documentação do padrão

2.4 CORS Configurado Corretamente ✅

Estimativa: 2 horas
Status: ✅ Completo

Tarefas:

  • Configurar CORS por ambiente
  • Validar origins em produção (não permite wildcard)
  • Configurar preflight cache (24 horas)
  • Permitir credentials quando necessário

Arquivos Modificados:

  • backend/Arah.Api/Program.cs (linhas 54-76)

Critérios de Sucesso:

  • ✅ CORS configurado por ambiente
  • ✅ Origins validados em produção
  • ✅ Preflight cache configurado
  • ✅ Credentials permitidos quando necessário

📊 Resumo da Fase 1

Tarefa Estimativa Status Prioridade
JWT Secret Management 4h ✅ Completo 🔴 Crítica
Rate Limiting Completo 6h ✅ Completo 🔴 Crítica
HTTPS e Security Headers 4h ✅ Completo 🔴 Crítica
Health Checks Completos 16h ✅ Completo 🔴 Crítica
Connection Pooling 8h ⚠️ Parcial 🔴 Crítica
Índices de Banco 16h ⚠️ Parcial 🔴 Crítica
Validação Completa 16h ✅ Completo 🔴 Crítica
Exception Handling 24h ⚠️ Parcial 🔴 Crítica
Migração Result 16h ⚠️ Parcial 🔴 Crítica
CORS Configurado 2h ✅ Completo 🔴 Crítica
Total 112h (14 dias)

✅ Critérios de Sucesso da Fase 1

Implementado ✅

  • ✅ JWT secret via ambiente (mínimo 32 caracteres em produção)
  • ✅ Rate limiting funcionando (global, por endpoint, por usuário)
  • ✅ HTTPS obrigatório em produção
  • ✅ Security headers presentes
  • ✅ Validators para endpoints críticos
  • ✅ Health checks com dependências críticas
  • ✅ CORS configurado por ambiente

Pendente ⚠️

  • ⚠️ Connection pooling explícito (métricas pendentes)
  • ⚠️ Índices de banco de dados (validação em staging pendente)
  • ⚠️ Exception handling completo (migração ampla + testes pendentes)
  • ⚠️ Migração Result completa (testes pendentes)

🎯 Próximos Passos

  1. Completar Connection Pooling - Adicionar métricas de conexões
  2. Completar Índices - Validar performance em staging
  3. Implementar Exception Handling - Migrar services e atualizar testes
  4. Completar Migração Result - Atualizar testes

📝 Notas de Implementação

Rate Limiting

  • Rate limiting por usuário autenticado usa o claim "sub" do JWT
  • Fallback para IP quando usuário não autenticado
  • Limites configuráveis via appsettings.json

Security Headers

  • CSP configurado para permitir recursos do mesmo origin
  • Headers aplicados em todas as respostas via middleware
  • Ordem do middleware: SecurityHeaders → CorrelationId → RequestLogging

Validators

  • Todos os validators seguem padrão FluentValidation
  • Mensagens em português para melhor UX
  • Validações específicas por tipo de request

Status: ✅ FASE 1 COMPLETA
Próxima Fase: Fase 2 - Qualidade de Código e Confiabilidade

← Voltar às Boas-VindasVer Todos os Docs →