Arquitetura Técnica: Monitor SEFAZ

1. Visão Geral da Arquitetura

O Monitor SEFAZ é construído seguindo os princípios da Clean Architecture (Arquitetura Limpa), garantindo separação de responsabilidades, testabilidade e manutenibilidade. A aplicação é dividida em camadas bem definidas, cada uma com responsabilidades específicas.

1.1. Estrutura de Camadas

┌─────────────────────────────────────────────────────────┐
│              SefazMonitor.Api (Presentation)            │
│  - Minimal APIs (Endpoints)                             │
│  - Middlewares                                           │
│  - Validações                                            │
│  - Extensions (Swagger, CORS, etc.)                     │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│          SefazMonitor.Application (Use Cases)           │
│  - Use Cases (Orquestração de lógica de negócio)        │
│  - DTOs e Mappers                                        │
│  - Configurações                                         │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│          SefazMonitor.Domain (Core Business)            │
│  - Entities (User, MonitorResult, Feature, SefazError)  │
│  - Value Objects (UFConfig, ServiceType, etc.)          │
│  - Interfaces (Repositórios, Serviços)                  │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│       SefazMonitor.Infrastructure (External)            │
│  - Repositórios (Redis)                                  │
│  - Serviços (Auth, Email, WhatsApp, Notifications)      │
│  - Background Services (MonitorWorker)                   │
│  - Health Checks                                         │
│  - Seeders                                               │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│           SefazMonitor.Sefaz (Domain Specific)          │
│  - Serviços SOAP (NFe, NFCe, CTe, DCe)                  │
│  - Helpers de Endpoints                                  │
│  - Certificados Digitais                                 │
│  - Configurações SEFAZ                                   │
└─────────────────────────────────────────────────────────┘

1.2. Princípios Arquiteturais

Dependency Inversion: Camadas internas não dependem de camadas externas
Single Responsibility: Cada classe tem uma única responsabilidade
Dependency Injection: Inversão de controle através de DI container
CQRS Pattern: Separação entre leitura e escrita (Use Cases)
Repository Pattern: Abstração da persistência de dados

2. Camadas Detalhadas

2.1. Presentation Layer (API)

Responsabilidades: - Expor endpoints HTTP (Minimal APIs) - Validação de entrada - Formatação de resposta - Autenticação e autorização - Middlewares (Exception Handling, CORS, Security Headers)

Tecnologias: - ASP.NET Core 9.0 - Minimal APIs (ao invés de Controllers tradicionais) - FluentValidation (via validadores customizados) - Swagger/OpenAPI

Estrutura de Endpoints:

// Exemplo: StatusEndpoints.cs
public static class StatusEndpoints
{
    public static void MapStatusEndpoints(this WebApplication app)
    {
        app.MapGet("/api/v1/status/latest", GetLatestStatus)
            .WithName("GetLatestStatus")
            .WithTags("Status")
            .WithSummary("Obter status mais recente")
            .WithOpenApi();
    }
}

Middlewares Principais: 1. GlobalExceptionHandlerMiddleware: Captura e trata exceções globalmente 2. SecurityHeadersMiddleware: Adiciona headers de segurança (CSP, HSTS, etc.) 3. SwaggerAuthMiddleware: Protege Swagger em produção

2.2. Application Layer (Use Cases)

Responsabilidades: - Orquestrar a lógica de negócio - Coordenar entre repositórios e serviços - Aplicar regras de negócio - Transformar dados entre camadas

Padrão Use Case:

Cada caso de uso é uma classe independente que implementa uma operação específica:

// Exemplo: GetLatestStatusUseCase
public class GetLatestStatusUseCase
{
    private readonly IMonitorRepository _repository;

    public async Task<IEnumerable<MonitorResultDto>> ExecuteAsync(string? service = null)
    {
        // Lógica de negócio
        // Coordenação entre repositórios
        // Transformação de dados
    }
}

Use Cases Principais: - MonitorSefazUseCase: Executa monitoramento de uma UF específica - GetLatestStatusUseCase: Obtém status mais recente de todas as UFs - GetStatusHistoryUseCase: Obtém histórico de uma UF - GetLatencyAnalyticsUseCase: Calcula analytics de latência (percentis) - AuthenticateUserUseCase: Autentica usuário - UserPreferencesUseCase: Gerencia preferências do usuário

2.3. Domain Layer

Responsabilidades: - Entidades de negócio - Value Objects - Interfaces (contratos) - Regras de negócio puras

Entities: - User: Usuário do sistema - MonitorResult: Resultado de um monitoramento - Feature: Feature do roadmap - SefazError: Erro SEFAZ catalogado

Value Objects: - ServiceType: Enum para tipo de serviço (NFe, NFCe, CTe, DCe) - UFConfig: Configuração de uma Unidade Federativa - MonitorConfiguration: Configuração de monitoramento

Interfaces (Ports): - IMonitorRepository: Contrato para persistência de resultados - IUserRepository: Contrato para gerenciamento de usuários - IAuthRepository: Contrato para autenticação - INotificationService: Contrato para notificações - IEmailService: Contrato para envio de emails

2.4. Infrastructure Layer

Responsabilidades: - Implementação de repositórios - Integração com serviços externos - Background services - Configuração de infraestrutura

2.4.1. Persistência com Redis

O sistema utiliza Redis como principal mecanismo de persistência e cache, aproveitando diferentes estruturas de dados:

Estruturas de Dados Redis:

Estrutura	Uso	Chave Exemplo
String	Status mais recente, configurações	`sefaz:latest:SP:NFe`
Sorted Set	Histórico ordenado por timestamp	`sefaz:history:SP:NFe`
Hash	Índices (ex: email → userId)	`users:index:email`
Set	Índices de chaves	`users:index`

TTLs e Window: - Latest TTL: 2 horas - History Window: 24 horas - Cache Window: 30 segundos (proteção contra consultas simultâneas)

Estratégia de Cache:

// Inserção de resultado
await db.StringSetAsync(latestKey, payload, _latestTtl);  // Cache do mais recente
await db.SortedSetAddAsync(historyKey, payload, timestamp); // Histórico ordenado
await db.SortedSetRemoveRangeByScoreAsync(historyKey, 0, oldTimestamp); // Limpeza automática

2.4.2. Background Services

MonitorWorker - Serviço de monitoramento contínuo:

Ciclo: Executa a cada 30 segundos
Paralelismo: Máximo de 5 consultas simultâneas (MaxConcurrency = 5)
Otimização DCe: DCe usa o mesmo servidor para todos os estados, então faz apenas 1 consulta e replica para todos
Warmup: Realiza warmup do certificado digital na inicialização
Retry: Implementa retry logic com backoff exponencial

Outros Background Services: - SefazErrorsSeeder: Semeia erros SEFAZ no Redis - AdminUserSeeder: Semeia usuário admin inicial - FeaturesSeeder: Semeia features do roadmap - RedisIndexSeeder: Cria índices necessários no Redis

2.4.3. Integrações Externas

Autenticação: - AWS Cognito: Autenticação principal - JWT: Tokens para API - OTP.NET: Autenticação de dois fatores (MFA)

Notificações: - EmailService: Envio de emails (via SMTP ou AWS SES) - WhatsAppVerificationService: Verificação via WhatsApp (Twilio/WhatsApp Cloud API)

SEFAZ: - HttpClient: Comunicação SOAP direta com serviços SEFAZ - NfeStatusServicoSoapService: Consulta status NFe/NFCe - CteStatusServicoSoapService: Consulta status CTe - DceStatusServicoSoapService: Consulta status DCe

2.5. Sefaz Layer (Domain Specific)

Camada especializada para integração com SEFAZ:

Serviços SOAP: - NfeStatusServicoSoapService: Consulta status NFe - NfceStatusServicoSoapService: Consulta status NFCe - CteStatusServicoSoapService: Consulta status CTe - DceStatusServicoSoapService: Consulta status DCe

Helpers: - NfeEndpointHelper: Endpoints NFe por UF - NfceEndpointHelper: Endpoints NFCe por UF - CteEndpointHelper: Endpoints CTe por UF - DceEndpointHelper: Endpoint DCe (nacional) - UfHelper: Helpers gerais de UF

Certificados: - CertificateService: Gerenciamento de certificados digitais A1/A3

3. Padrões de Design

3.1. Repository Pattern

Abstrai a persistência de dados, permitindo trocar implementações facilmente:

public interface IMonitorRepository
{
    Task<MonitorResult?> GetLatestAsync(string uf, string service);
    Task<IEnumerable<MonitorResult>> GetHistoryAsync(string uf, string service, TimeSpan window);
}

// Implementação Redis
public class MonitorRepository : IMonitorRepository
{
    private readonly RedisStatusService _redisService;
    // ...
}

3.2. Dependency Injection

Todas as dependências são injetadas via construtor:

public class GetLatestStatusUseCase(
    IMonitorRepository repository,
    ILogger<GetLatestStatusUseCase> logger)
{
    // Dependências disponíveis como campos readonly
}

3.3. Use Case Pattern

Cada operação de negócio é encapsulada em um Use Case:

Entrada: Parâmetros simples (DTOs ou tipos primitivos)
Saída: DTOs específicos
Responsabilidade: Uma única operação de negócio

3.4. Value Objects

Objetos imutáveis que representam conceitos do domínio:

public class UFConfig
{
    public string UF { get; init; }
    public ServiceType ServiceType { get; init; }
    public Ambiente Ambiente { get; init; }
    // ...
}

4. Fluxo de Dados

4.1. Fluxo de Monitoramento

sequenceDiagram
    participant Worker as MonitorWorker
    participant UseCase as MonitorSefazUseCase
    participant SefazService as SefazStatusService
    participant SoapService as NfeStatusServicoSoapService
    participant Redis as Redis
    participant SEFAZ as Servidor SEFAZ

    Worker->>UseCase: ExecuteAsync(UF, Service)
    UseCase->>SefazService: GetStatusAsync(UF, Service)
    SefazService->>SoapService: ConsultarStatus(Endpoint)
    SoapService->>SEFAZ: SOAP Request
    SEFAZ-->>SoapService: SOAP Response
    SoapService-->>SefazService: SefazStatusResult
    SefazService-->>UseCase: MonitorResult
    UseCase->>Redis: InsertResultAsync(result)
    Redis-->>Redis: Salvar em String + Sorted Set
    UseCase-->>Worker: Result

4.2. Fluxo de Consulta de Status

sequenceDiagram
    participant Client as Cliente HTTP
    participant API as StatusEndpoints
    participant UseCase as GetLatestStatusUseCase
    participant Repository as IMonitorRepository
    participant Redis as Redis

    Client->>API: GET /api/v1/status/latest
    API->>API: Validar parâmetros
    API->>UseCase: ExecuteAsync(service)
    UseCase->>Repository: GetLatestAsync(uf, service)
    Repository->>Redis: GET sefaz:latest:{uf}:{service}
    Redis-->>Repository: JSON MonitorResult
    Repository-->>UseCase: MonitorResult
    UseCase->>UseCase: Filtrar por service (se necessário)
    UseCase->>UseCase: Transformar para DTO
    UseCase-->>API: IEnumerable<MonitorResultDto>
    API-->>Client: 200 OK + JSON

5. Estratégias de Performance

5.1. Caching Multi-Camada

Cache de Última Atualização (30s): Evita consultas simultâneas ao Redis
Cache de Status Latest (2h): Cache do status mais recente
Histórico em Sorted Set: Acesso O(log N) para range queries

5.2. Paralelismo Controlado

MaxConcurrency = 5: Limita consultas simultâneas à SEFAZ
Parallel.ForEachAsync: Processa múltiplas UFs em paralelo
Otimização DCe: 1 consulta para todos os estados

5.3. Limpeza Automática de Dados

Histórico mantido apenas 24h (configurável)
Limpeza automática via SortedSetRemoveRangeByScoreAsync
TTL em todas as chaves para evitar acúmulo

6. Segurança

6.1. Autenticação e Autorização

JWT Bearer Tokens: Para API
AWS Cognito: Autenticação de usuários
MFA (OTP): Autenticação de dois fatores para admins
Basic Auth: Para Swagger em produção (opcional)

6.2. Data Protection

ASP.NET Core Data Protection: Criptografia de dados sensíveis
Chaves persistidas em filesystem com permissões adequadas
Lifetime de 90 dias (configurável)

6.3. Headers de Segurança

HSTS: Força HTTPS em produção
CSP: Content Security Policy
X-Frame-Options: Previne clickjacking
X-Content-Type-Options: Previne MIME sniffing

6.4. Validação de Entrada

Validação de parâmetros em todos os endpoints
Validação de UF (27 estados válidos)
Validação de ServiceType (NFe, NFCe, CTe, DCe)

7. Observabilidade

7.1. Logging

Serilog: Framework de logging estruturado
AWS CloudWatch Logs: Logs centralizados em produção
In-Memory Logs: Para desenvolvimento (acessível via API)
Níveis: Debug, Information, Warning, Error, Critical

7.2. Health Checks

Redis Health Check: Verifica conectividade com Redis
Endpoint: /health/live e /health/ready
Docker Health Check: Integrado no Dockerfile

7.3. Métricas e Analytics

Latency Analytics: Percentis P50, P95, P99
Correlation IDs: Rastreamento de requisições
Structured Logging: Facilita análise e busca

8. Deploy e Infraestrutura

8.1. Containerização

Dockerfile Multi-Stage: - Stage 1: Build (.NET SDK 9.0) - Stage 2: Runtime (.NET Runtime 9.0) - Usuário não-root para segurança - Health check integrado

8.2. Docker Compose

Desenvolvimento: - Redis: Alpine image com AOF habilitado - API: Build local com hot reload - Volumes: Persistência de dados e DataProtection keys

Produção: - Redis: Cluster mode (opcional) - API: Imagem otimizada - Networks: Isolamento de rede

8.3. Variáveis de Ambiente

Configurações principais via appsettings.json e variáveis de ambiente:

ConnectionStrings: Redis, banco de dados
Authentication: Cognito, JWT secrets
SEFAZ: Certificados, timeouts
AWS: Credenciais, regiões
CORS: Origins permitidos
Logging: Níveis, destinos

9. Decisões Técnicas Importantes

9.1. Por que Redis ao invés de banco relacional?

Performance: Latência sub-milissegundo para leitura
Estruturas de Dados: Sorted Sets perfeitos para histórico temporal
Simplicidade: Não requer schema migrations
Escalabilidade: Fácil escalar horizontalmente
TTL Nativo: Expiração automática de dados

9.2. Por que Minimal APIs ao invés de Controllers?

Menos Boilerplate: Código mais enxuto
Performance: Menos overhead
Modernidade: Padrão atual do .NET
Type Safety: Melhor inferência de tipos
OpenAPI Nativo: Integração direta com Swagger

9.3. Por que Clean Architecture?

Testabilidade: Fácil mockar dependências
Manutenibilidade: Mudanças isoladas por camada
Flexibilidade: Trocar implementações sem afetar domínio
Onboarding: Estrutura clara para novos desenvolvedores

9.4. Por que Background Service para monitoramento?

Desacoplamento: Monitoramento independente de requisições HTTP
Resiliência: Continua funcionando mesmo com poucas requisições
Controle: Ciclo de execução previsível
Paralelismo: Controle fino sobre concorrência

10. Tratamento de Erros e Validação

10.1. Global Exception Handler

O middleware GlobalExceptionHandlerMiddleware captura todas as exceções não tratadas e devolve respostas JSON padronizadas:

Características: - Correlation IDs: Cada erro recebe um ID único para rastreamento - Detecção de Configuração: Identifica automaticamente erros de configuração - Mensagens Amigáveis: Diferencia mensagens entre desenvolvimento e produção - Stack Trace: Disponível apenas em desenvolvimento

Estrutura de Resposta de Erro:

{
  "message": "Mensagem amigável do erro",
  "statusCode": 500,
  "correlationId": "guid-unico",
  "timestamp": "2025-12-26T10:00:00Z",
  "details": "Detalhes técnicos (apenas desenvolvimento)",
  "stackTrace": "Stack trace completo (apenas desenvolvimento)"
}

Mapeamento de Exceções para Status Codes:

Exceção	Status Code	Descrição
`ArgumentNullException`	400	Parâmetros obrigatórios ausentes
`ArgumentException`	400	Dados inválidos
`UnauthorizedAccessException`	401	Acesso não autorizado
`KeyNotFoundException`	404	Recurso não encontrado
`NotImplementedException`	501	Funcionalidade não implementada
Outras	500	Erro interno do servidor

Detecção Automática de Erros de Configuração:

O middleware identifica automaticamente erros relacionados a configuração:

ConnectionStrings, Redis, Authentication/JWT
CORS, Swagger, CloudWatch
WhatsApp, Twilio, Email/SMTP
Certificate, SEFAZ, Settings

10.2. Validação de Entrada

Validação Manual (Padrão Atual):

O projeto utiliza validadores estáticos para validação de entrada:

// Exemplo: StatusEndpointsValidators
public static class StatusEndpointsValidators
{
    public static ValidationResult ValidateUf(string? uf)
    {
        // Valida formato e lista válida de UFs
    }

    public static ValidationResult ValidateService(string? service)
    {
        // Valida tipos de serviço aceitos
    }

    public static ValidationResult ValidateHours(double? hours)
    {
        // Valida intervalo de horas (0-168)
    }

    public static ValidationResult ValidateEndDate(DateTimeOffset? end)
    {
        // Valida período de datas (-30 dias a +1 dia)
    }
}

Regras de Validação:

UF: Exatamente 2 letras maiúsculas, deve estar na lista de 27 estados
Service: Deve ser um dos: NFeStatusServico, NFCeStatusServico, CTeStatusServico, DCeStatusServico
Hours: Entre 0 e 168 (7 dias), opcional
EndDate: Entre 30 dias no passado e 1 dia no futuro, opcional

Padrão de Validação nos Endpoints:

private static async Task<IResult> GetLatestStatus(
    [FromQuery] string? service,
    GetLatestStatusUseCase useCase,
    ILogger<Program> logger)
{
    var validation = StatusEndpointsValidators.ValidateService(service);
    if (!validation.IsValid)
    {
        return Results.BadRequest(new { error = validation.ErrorMessage });
    }

    // Continua com a lógica...
}

10.3. Pipeline de Requisições

Ordem de Execução dos Middlewares:

Correlation ID: Gera/extrai ID de correlação
Security Headers: Adiciona headers de segurança
CORS: Verifica e aplica políticas CORS
Global Exception Handler: Captura exceções
Authentication Exception Handler: Trata erros específicos de autenticação
Authentication: Autentica usuário
Authorization: Verifica permissões
Swagger Auth: Protege Swagger em produção
Endpoints: Executa handlers de endpoints

Fluxo Completo de Requisição:

sequenceDiagram
    participant Client
    participant Middleware as Middleware Pipeline
    participant Auth as Authentication
    participant Endpoint as Endpoint Handler
    participant UseCase as Use Case
    participant Repository as Repository
    participant Redis as Redis

    Client->>Middleware: HTTP Request
    Middleware->>Middleware: Correlation ID
    Middleware->>Middleware: Security Headers
    Middleware->>Middleware: CORS
    Middleware->>Auth: Authenticate
    Auth->>Auth: Validate JWT/Cognito
    Auth-->>Middleware: Authenticated User
    Middleware->>Endpoint: Route Request
    Endpoint->>Endpoint: Validate Input
    Endpoint->>UseCase: ExecuteAsync()
    UseCase->>Repository: Get/Save Data
    Repository->>Redis: Read/Write
    Redis-->>Repository: Data
    Repository-->>UseCase: Result
    UseCase-->>Endpoint: DTO
    Endpoint-->>Middleware: IResult
    Middleware-->>Client: HTTP Response

11. Configuração e Settings

11.1. Estrutura de Settings

O projeto utiliza um modelo de configuração fortemente tipado:

public class Settings
{
    public ConnectionStringsSettings ConnectionStrings { get; set; }
    public RedisSettings Redis { get; set; }
    public JwtSettings Jwt { get; set; }
    public AuthenticationSettings Authentication { get; set; }
    public GoogleAuthSettings GoogleAuth { get; set; }
    public CorsSettings Cors { get; set; }
    public SwaggerSettings Swagger { get; set; }
    public LoggingSettings Logging { get; set; }
    public CloudWatchLoggingSettings CloudWatch { get; set; }
    public SefazSettings Sefaz { get; set; }
    public CertificateSettings Certificate { get; set; }
    public EmailSettings Email { get; set; }
    public WhatsAppCloudApiSettings WhatsAppCloudApi { get; set; }
    public TwilioSettings Twilio { get; set; }
    public FrontendSettings Frontend { get; set; }
    public AdminAuthSettings AdminAuth { get; set; }
    public AdminSeedSettings AdminSeed { get; set; }
}

Carregamento de Settings:

var configs = builder.Configuration.Get<Settings>()
    ?? throw new InvalidOperationException("Settings não podem ser nulos.");

11.2. Configuração por Ambiente

Arquivos de Configuração:

appsettings.json: Configuração base
appsettings.Development.json: Configurações de desenvolvimento
appsettings.Production.json: Configurações de produção

Variáveis de Ambiente:

Configurações podem ser sobrescritas via variáveis de ambiente usando o padrão do ASP.NET Core (duplo underscore ou dois pontos):

Redis__ConnectionString=redis:6379
Jwt__SecretKey=minha-chave-secreta
Cors__AllowedOrigins__0=https://example.com

11.3. Validação de Settings

O projeto valida que Settings não sejam nulos na inicialização:

var configs = builder.Configuration.Get<Settings>()
    ?? throw new InvalidOperationException("Settings não podem ser nulos. Verifique a configuração.");

Melhorias Futuras: - Validação de configurações obrigatórias - Validação de formatos (URLs, connection strings) - Validação de intervalos (timeouts, TTLs)

12. Padrões de Código

12.1. Naming Conventions

Classes: - Endpoints: {Nome}Endpoints (ex: StatusEndpoints) - Use Cases: {Ação}{Entidade}UseCase (ex: GetLatestStatusUseCase) - Services: {Nome}Service (ex: RedisStatusService) - Repositories: {Nome}Repository (ex: MonitorRepository) - Middlewares: {Nome}Middleware (ex: GlobalExceptionHandlerMiddleware) - Validators: {Nome}Validators (ex: StatusEndpointsValidators)

Métodos: - Endpoints: Get{Nome}, Create{Nome}, Update{Nome}, Delete{Nome} - Use Cases: ExecuteAsync() - Repositories: GetAsync(), SaveAsync(), DeleteAsync()

12.2. Dependency Injection

Padrão de Injeção:

Todas as dependências são injetadas via construtor usando primary constructors (C# 12):

public class GetLatestStatusUseCase(
    IMonitorRepository repository,
    ILogger<GetLatestStatusUseCase> logger)
{
    // Campos readonly implícitos
}

Lifetimes:

Singleton: Configurações, conexões (Redis), services compartilhados
Scoped: Use cases, repositories, serviços de request
Transient: Serviços efêmeros (pouco usado)

12.3. Async/Await

Padrão de Métodos Assíncronos:

Todos os métodos que fazem I/O são assíncronos:

public async Task<IEnumerable<MonitorResult>> GetLatestStatusAsync(string? service = null)
{
    // Sempre usar async/await
    await Task.Delay(100);
    return results;
}

Naming: - Métodos assíncronos terminam com Async - Evitar .Result ou .Wait() (usar await)

12.4. Logging

Structured Logging:

Sempre usar structured logging com parâmetros nomeados:

// ✅ Bom
logger.LogInformation("Status retornado para {UF}:{Service} - Status: {Status}", 
    uf, service, status);

// ❌ Ruim
logger.LogInformation($"Status retornado para {uf}:{service} - Status: {status}");

Níveis de Log:

Trace: Informações muito detalhadas (raramente usado)
Debug: Informações de debug durante desenvolvimento
Information: Informações gerais sobre fluxo da aplicação
Warning: Situações anômalas que não impedem execução
Error: Erros que impedem operações específicas
Critical: Erros críticos que podem afetar a aplicação

12.5. Tratamento de Exceções

Regras Gerais:

Capturar exceções específicas quando possível
Sempre logar antes de relançar ou tratar
Não capturar Exception genérico sem necessidade
Usar Correlation IDs em logs de erro

Padrão nos Endpoints:

try
{
    var result = await useCase.ExecuteAsync();
    return Results.Ok(result);
}
catch (ArgumentException ex)
{
    logger.LogWarning(ex, "Argumento inválido: {Message}", ex.Message);
    return Results.BadRequest(new { error = ex.Message });
}
catch (Exception ex)
{
    logger.LogError(ex, "Erro ao processar requisição");
    return Results.Problem("Erro ao processar requisição.");
}

13. Testes (Planejamento)

13.1. Estratégia de Testes

Pirâmide de Testes:

Unit Tests (base): Testar Use Cases, Services, Validators isoladamente
Integration Tests (meio): Testar repositórios com Redis em memória
E2E Tests (topo): Testar endpoints completos com TestServer

13.2. Frameworks Sugeridos

xUnit: Framework de testes
Moq/NSubstitute: Mocking de dependências
FluentAssertions: Assertions mais legíveis
Testcontainers: Redis containers para testes de integração
WebApplicationFactory: Testes de integração de API

13.3. Estrutura de Testes Proposta

SefazMonitor.Tests/
├── Unit/
│   ├── Application/
│   │   └── UseCases/
│   │       └── GetLatestStatusUseCaseTests.cs
│   ├── Api/
│   │   └── Validators/
│   │       └── StatusEndpointsValidatorsTests.cs
│   └── Domain/
│       └── ValueObjects/
│           └── UFConfigTests.cs
├── Integration/
│   ├── Infrastructure/
│   │   └── Repositories/
│   │       └── MonitorRepositoryTests.cs
│   └── Api/
│       └── Endpoints/
│           └── StatusEndpointsTests.cs
└── E2E/
    └── StatusFlowTests.cs

14. Performance e Otimizações

14.1. Otimizações Implementadas

Redis Caching: - Cache de 30 segundos para prevenir consultas simultâneas - TTL de 2 horas para status mais recente - Sorted Sets para histórico com acesso O(log N)

Paralelismo Controlado: - Máximo de 5 consultas simultâneas à SEFAZ - Evita sobrecarga nos servidores SEFAZ - Otimização especial para DCe (1 consulta para todos)

Background Service: - Monitoramento independente de requisições HTTP - Ciclo previsível de 30 segundos - Warmup de certificados na inicialização

14.2. Métricas de Performance

Latência: - P50 (Mediana): ~100-200ms (com cache) - P95: ~500-1000ms (consultas diretas à SEFAZ) - P99: ~2000-5000ms (timeouts de SEFAZ)

Throughput: - Consultas Redis: >10.000 req/s - Consultas à SEFAZ: Limitado por MaxConcurrency = 5 - Endpoints API: Depende de Redis (alta performance)

14.3. Otimizações Futuras

Circuit Breaker: Evitar consultas a SEFAZ quando instável
Response Compression: Compressão gzip/brotli para respostas grandes
Connection Pooling: Pool de conexões HTTP para SEFAZ
Batch Processing: Processar múltiplas UFs em batches maiores
Rate Limiting: Limitar requisições por IP/usuário

15. Segurança Avançada

15.1. Autenticação e Autorização

JWT (JSON Web Tokens): - Tokens assinados com chave secreta - Expiração configurável - Claims para roles (Admin, SuperAdmin)

AWS Cognito: - Gerenciamento de usuários - Federated Identity (Google OAuth) - MFA (Multi-Factor Authentication)

Authorization Policies: - Admin: Requer role de Admin - SuperAdmin: Requer role de SuperAdmin - Custom policies por recurso

15.2. Data Protection

ASP.NET Core Data Protection: - Criptografia de dados sensíveis - Chaves rotacionadas periodicamente (90 dias) - Persistência em filesystem seguro

Secrets Management: - Variáveis de ambiente para secrets - Não commit de secrets no código - Configuração via IaC (Infrastructure as Code)

15.3. Headers de Segurança

Security Headers Middleware:

// Headers aplicados automaticamente:
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'
Strict-Transport-Security: max-age=31536000 (em produção)

16. Melhorias Futuras

16.1. Arquitetura

Event Sourcing para histórico completo
CQRS completo com Read Models separados
Message Queue (RabbitMQ/SQS) para processamento assíncrono
Cache distribuído (Redis Cluster)
API Gateway para rate limiting e routing

16.2. Performance

Implementar Circuit Breaker para SEFAZ
Rate Limiting mais granular (por IP/usuário)
Compressão de respostas (gzip/brotli)
CDN para assets estáticos
Database connection pooling otimizado
Parallel processing otimizado

16.3. Observabilidade

Métricas Prometheus
Distributed Tracing (OpenTelemetry)
Alertas automatizados (CloudWatch Alarms)
Dashboard Grafana
APM (Application Performance Monitoring)
Real User Monitoring (RUM)

16.4. Segurança

Rate Limiting por IP/usuário
API Keys para integrações B2B
Auditoria completa de ações
Encriptação em repouso no Redis
Secrets rotation automático
WAF (Web Application Firewall)

16.5. Testes

Cobertura de testes unitários >80%
Testes de integração completos
Testes E2E automatizados
Testes de carga e stress
Testes de segurança automatizados

16.6. DevOps

CI/CD completo (GitHub Actions)
Infrastructure as Code (Terraform/CloudFormation)
Blue-Green deployments
Canary releases
Automated rollback
Monitoring e alerting automatizado

17. Referências e Recursos

17.1. Documentação Técnica

17.2. Bibliotecas Utilizadas

HttpClient: Comunicação SOAP direta com serviços SEFAZ
StackExchange.Redis: Cliente Redis para .NET
Serilog: Framework de logging estruturado
AWS SDK: Integração com serviços AWS

17.3. Documentação Relacionada

Última Atualização: 26 de Dezembro de 2025
Versão do Documento: 1.0
Mantido por: Equipe de Desenvolvimento Monitor SEFAZ