Capítulo 30 — Gestão Multi-Tenant

Camada de Identidade (Cap. 28)
  │
  └─→ Tenant Context resolvido a partir do usuário autenticado
      │
      ├─ Autorização (Cap. 29): permissões filtradas por tenant
      │
      ├─ Aplicação (Microsserviços)
      │  │
      │  ├─ Interceptor: Tenant Context injected em todo request
      │  ├─ Validação: tenant_id verificado em todo resource ID
      │  └─ Query: filtro por tenant_id adicionado automaticamente
      │
      ├─ Persistência (Banco de Dados)
      │  │
      │  ├─ Schema compartilhado, tabelas com coluna tenant_id
      │  ├─ Índices multi-coluna (tenant_id, entity_id, ...)
      │  ├─ Triggers que garantem tenant_id em INSERT/UPDATE
      │  └─ Row-level security (quando disponível no BD)
      │
      ├─ Cache Distribuído (Redis)
      │  │
      │  ├─ Chave de cache: "{tenant_id}:{entity_type}:{entity_id}"
      │  ├─ Invalidação por tenant quando políticas mudam
      │  └─ TTL por tenant_id configurável
      │
      ├─ Busca e Indexação (Elasticsearch)
      │  │
      │  └─ Índices segregados por tenant (one index per tenant)
      │     ou índice compartilhado com field tenant_id e query filter
      │
      ├─ Fila de Mensagens (RabbitMQ)
      │  │
      │  └─ Topics: "{tenant_id}.{event_type}"
      │     ou exchange + routing_key que inclui tenant_id
      │
      └─ Armazenamento de Objetos (S3/blob storage)
         │
         └─ Prefixo de chave: "{tenant_id}/{document_uuid}/{file}"
            ou bucket por tenant quando necessário

User
  id                (UUID)
  tenantId          (UUID — qual tenant este usuário pertence)
  email
  ...

Request (Solicitação)
  id                (UUID)
  tenantId          (UUID — qual tenant esta solicitação pertence)
  citizenId         (UUID — cidadão que abriu a solicitação)
  status
  ...

Document (Documento)
  id                (UUID)
  tenantId          (UUID)
  requestId         (UUID)
  filePath          (string)
  ...

Interaction (Atendimento)
  id                (UUID)
  tenantId          (UUID)
  citizenId         (UUID)
  channel           (EMAIL, SMS, WHATSAPP)
  ...

                       ┌─────────────┐
                       │   PENDING   │
                       │ (provisioning)
                       └──────┬──────┘
                              │
                       ┌──────▼──────┐
                       │   ACTIVE    │◄──────┐
                       │  (operando)  │      │
                       └──┬───────┬──┘      │
                          │       │       reativation
                    suspend│       │        │
                          │   activation   │
                          ▼       ▼        │
                       ┌──────────────┐    │
                       │  SUSPENDED   │────┘
                       └──────┬───────┘
                              │
                        offboarding
                              │
                       ┌──────▼───────┐
                       │   DELETED    │
                       │ (archived)   │
                       └──────────────┘

HTTP Request
    │
    ├─ Headers: Authorization: Bearer <token>
    │
    ▼
AuthenticationFilter
    │
    ├─ Desserializa token
    ├─ Valida assinatura
    ├─ Extrai userId
    │
    ▼
TenantContextFilter
    │
    ├─ Busca userId no IAM
    ├─ Retorna lista de tenants associados
    ├─ Se um único tenant: usa automaticamente
    ├─ Se múltiplos tenants: busca seleção no header (X-Tenant-Id)
    ├─ Valida que o tenant selecionado é válido para o usuário
    │
    ▼
ThreadLocal<TenantContext>
    │
    ├─ Armazena tenant_id na thread-local
    ├─ Disponível para toda lógica de negócio
    └─ Acessível via TenantContext.getCurrent()

// Exemplo: consultar solicitação
public Request getRequest(UUID requestId) {
    UUID currentTenant = TenantContext.getCurrent().getTenantId();
    
    // Busca a solicitação
    Request request = requestRepository.findById(requestId);
    
    // Valida que a solicitação pertence ao tenant atual
    if (!request.getTenantId().equals(currentTenant)) {
        throw new ForbiddenException(
            "Solicitação não pertence ao seu tenant"
        );
    }
    
    return request;
}

RequestService
    │
    ├─ currentTenant = TenantContext.getCurrent()
    │
    └─▶ documentService.uploadDocument(file)
          │
          ├─ Tenant Context propagado via header (X-Tenant-Id: <uuid>)
          │
          └─▶ DocumentService interceptor
              ├─ Extrai X-Tenant-Id do header
              ├─ Valida que matches header Authorization
              ├─ Estabelece novo TenantContext localmente
              └─ Processa upload com tenant context ativo

-- Tabela de usuários
CREATE TABLE public.users (
    id                UUID PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    email             VARCHAR(255) NOT NULL,
    name              VARCHAR(255),
    password_hash     VARCHAR(255),
    status            VARCHAR(50),
    created_at        TIMESTAMP,
    updated_at        TIMESTAMP,
    
    -- Índice composto para queries por tenant
    UNIQUE(tenant_id, email),
    INDEX idx_users_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

-- Tabela de solicitações
CREATE TABLE public.requests (
    id                UUID PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    citizen_id        UUID NOT NULL,
    service_id        UUID NOT NULL,
    status            VARCHAR(50),
    created_at        TIMESTAMP,
    updated_at        TIMESTAMP,
    
    INDEX idx_requests_tenant (tenant_id),
    INDEX idx_requests_citizen_tenant (citizen_id, tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

-- Tabela de documentos
CREATE TABLE public.documents (
    id                UUID PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    request_id        UUID NOT NULL,
    file_path         VARCHAR(1024),
    file_size         BIGINT,
    content_type      VARCHAR(100),
    created_at        TIMESTAMP,
    
    INDEX idx_documents_tenant (tenant_id),
    INDEX idx_documents_request_tenant (request_id, tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id),
    FOREIGN KEY (request_id) REFERENCES requests(id)
);

// Specification Pattern com verificação de tenant
public class RequestSpecifications {
    
    public static Specification<Request> forTenant(UUID tenantId) {
        return (root, query, cb) -> 
            cb.equal(root.get("tenantId"), tenantId);
    }
    
    public static Specification<Request> withStatus(String status) {
        return (root, query, cb) -> 
            cb.equal(root.get("status"), status);
    }
    
    // Uso na aplicação
    UUID currentTenant = TenantContext.getCurrent().getTenantId();
    Specification<Request> spec = 
        Specification
            .where(RequestSpecifications.forTenant(currentTenant))
            .and(RequestSpecifications.withStatus("OPEN"));
    
    List<Request> requests = requestRepository.findAll(spec);
}

-- Trigger: previne INSERT sem tenant_id
CREATE TRIGGER trigger_requests_insert BEFORE INSERT ON public.requests
FOR EACH ROW
BEGIN
    IF NEW.tenant_id IS NULL THEN
        RAISE EXCEPTION 'tenant_id cannot be NULL';
    END IF;
END;

-- Trigger: previne UPDATE que mude tenant_id (imutável)
CREATE TRIGGER trigger_requests_update BEFORE UPDATE ON public.requests
FOR EACH ROW
BEGIN
    IF NEW.tenant_id != OLD.tenant_id THEN
        RAISE EXCEPTION 'tenant_id is immutable';
    END IF;
END;

Sem isolamento (INSEGURO):
  KEY: "user:alice@example.com"
  VALUE: {...user_data...}
  PROBLEMA: dois tenants com mesmo email conflitam

Com isolamento (SEGURO):
  KEY: "tenant:{tenantId}:user:alice@example.com"
  VALUE: {...user_data...}

String cacheKey = String.format(
    "tenant:%s:user:%s",
    TenantContext.getCurrent().getTenantId(),
    userId
);

User cachedUser = redisTemplate.opsForValue().get(cacheKey);
if (cachedUser == null) {
    // Busca do banco
    User user = userRepository.findById(userId);
    
    // Armazena em cache com tenant
    redisTemplate.opsForValue().set(
        cacheKey, 
        user, 
        Duration.ofHours(1)
    );
}

public void updateTenantPolicy(TenantPolicy policy) {
    UUID tenantId = policy.getTenantId();
    
    // Atualiza no banco
    tenantPolicyRepository.save(policy);
    
    // Invalida cache do tenant (com padrão)
    String pattern = String.format("tenant:%s:*", tenantId);
    redisTemplate.delete(
        redisTemplate.keys(pattern)
    );
}

Exchange: "platformEvents"

Routing keys por tipo de evento:
  - "tenant:{tenantId}.request.created"
  - "tenant:{tenantId}.request.approved"
  - "tenant:{tenantId}.document.uploaded"
  - "tenant:{tenantId}.interaction.closed"
  - "tenant:{tenantId}.campaign.executed"

Queue subscription:
  Q: "DocumentClassificationWorker_{tenantId}"
  Binding: exchange="platformEvents" 
           routing_key="tenant:{tenantId}.document.*"

public void publishRequestCreated(Request request) {
    String routingKey = String.format(
        "tenant:%s.request.created",
        request.getTenantId()
    );
    
    rabbitTemplate.convertAndSend(
        "platformEvents",
        routingKey,
        new RequestCreatedEvent(request)
    );
}

@RabbitListener(
    bindings = @QueueBinding(
        value = @Queue(name = "DocumentClassificationWorker_#{tenantId}"),
        exchange = @Exchange(name = "platformEvents", type = "topic"),
        key = "tenant:#{tenantId}.document.*"
    )
)
public void onDocumentEvent(DocumentUploadedEvent event) {
    // event.getTenantId() == ThreadLocal tenant automaticamente
    documentClassificationService.classify(event);
}

Queue: "DocumentClassificationWorker_tenant1_dlq"
Queue: "DocumentClassificationWorker_tenant2_dlq"

Index: "requests_tenant_<uuid_tenant1>"
Index: "requests_tenant_<uuid_tenant2>"
Index: "requests_tenant_<uuid_tenant3>"

Index: "requests"
  Document: {
    "id": "req-123",
    "tenant_id": "tenant-1",
    "content": "Solicitação de habilitação...",
    "status": "OPEN"
  }

SearchRequest searchRequest = new SearchRequest("requests");
SearchSourceBuilder sourceBuilder = new SearchSourceBuilder();

// Query do usuário
sourceBuilder.query(
    QueryBuilders.boolQuery()
        .must(QueryBuilders.multiMatchQuery(
            userSearchTerm, 
            "content", "title"
        ))
        .filter(QueryBuilders.termQuery(
            "tenant_id", 
            currentTenantId.toString()
        ))
);

searchRequest.source(sourceBuilder);

s3://prodemge-documents/
  ├─ tenant-1/
  │  ├─ request-abc/
  │  │  ├─ documento-habilitacao.pdf
  │  │  └─ foto-rosto.jpg
  │  └─ request-def/
  │     └─ comprovante.pdf
  │
  ├─ tenant-2/
  │  └─ request-xyz/
  │     └─ requerimento.docx
  │
  └─ tenant-3/
     ├─ ...

public String getPresignedDownloadUrl(UUID documentId) {
    Document doc = documentRepository.findById(documentId);
    
    // Valida que documento pertence ao tenant
    if (!doc.getTenantId().equals(TenantContext.getCurrent().getTenantId())) {
        throw new ForbiddenException();
    }
    
    // Gera URL assinada (válida por 15 minutos)
    String presignedUrl = s3Client.generatePresignedUrl(
        bucket,
        String.format(
            "%s/%s/%s/%s",
            doc.getTenantId(),
            "requests",
            doc.getRequestId(),
            doc.getFilename()
        ),
        Duration.ofMinutes(15)
    );
    
    return presignedUrl;
}

CREATE TABLE audit_log (
    id                BIGINT PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    user_id           UUID NOT NULL,
    action            VARCHAR(50),
    resource_type     VARCHAR(50),
    resource_id       UUID,
    changes           JSONB,
    ip_address        VARCHAR(45),
    user_agent        VARCHAR(1024),
    timestamp         TIMESTAMP,
    
    INDEX idx_audit_tenant (tenant_id),
    INDEX idx_audit_tenant_user (tenant_id, user_id),
    INDEX idx_audit_tenant_timestamp (tenant_id, timestamp)
);

tenant_id: "tenant-1"
timestamp: 2026-07-16 14:32:15
user_id: "user-alice"
action: "REQUEST_APPROVED"
resource_id: "req-12345"
changes: {"status": "OPEN" → "APPROVED", "approved_by": "alice"}

List<AuditLog> getAuditTrail(UUID tenantId, UUID userId) {
    return auditRepository.findAll(
        Specification
            .where((root, query, cb) -> 
                cb.equal(root.get("tenantId"), tenantId)
            )
            .and((root, query, cb) -> 
                cb.equal(root.get("userId"), userId)
            )
    );
}

CREATE TABLE communication_templates (
    id                UUID PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    name              VARCHAR(255),
    channel           VARCHAR(50),  -- EMAIL, SMS, WHATSAPP
    subject           VARCHAR(255),
    body              TEXT,
    created_by        UUID,
    created_at        TIMESTAMP,
    
    INDEX idx_templates_tenant (tenant_id),
    UNIQUE(tenant_id, name, channel)
);

CREATE TABLE campaigns (
    id                UUID PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    name              VARCHAR(255),
    template_id       UUID NOT NULL,
    segment_id        UUID,
    status            VARCHAR(50),
    scheduled_at      TIMESTAMP,
    executed_at       TIMESTAMP,
    
    INDEX idx_campaigns_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id),
    FOREIGN KEY (template_id) REFERENCES communication_templates(id)
);

public void executeCampaign(UUID campaignId) {
    Campaign campaign = campaignRepository.findById(campaignId);
    
    // Valida tenant
    if (!campaign.getTenantId().equals(TenantContext.getCurrent().getTenantId())) {
        throw new ForbiddenException();
    }
    
    // Busca template
    CommunicationTemplate template = 
        templateRepository.findById(campaign.getTemplateId());
    
    // Valida que template pertence ao mesmo tenant
    if (!template.getTenantId().equals(campaign.getTenantId())) {
        throw new DataIntegrityException();
    }
    
    // Carrega segmento de cidadãos
    List<Citizen> recipients = segmentService.getCitizens(
        campaign.getSegmentId(), 
        campaign.getTenantId()
    );
    
    // Enfileira notificações por canal
    for (Citizen citizen : recipients) {
        notificationQueue.enqueue(
            new NotificationTask(
                campaign.getTenantId(),
                template,
                citizen,
                campaign.getId()
            )
        );
    }
}

CREATE TABLE citizen_consents (
    id                UUID PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    citizen_id        UUID NOT NULL,
    consent_type      VARCHAR(50),  -- EMAIL, SMS, WHATSAPP, MARKETING
    granted           BOOLEAN,
    granted_at        TIMESTAMP,
    revoked_at        TIMESTAMP,
    
    INDEX idx_consents_tenant_citizen (tenant_id, citizen_id),
    UNIQUE(tenant_id, citizen_id, consent_type)
);

Tenant A (Secretaria de Educação):
  - citizen-123: EMAIL=true, SMS=false, MARKETING=true

Tenant B (Secretaria de Saúde):
  - citizen-123: EMAIL=true, SMS=true, MARKETING=false

boolean canSendEmail(UUID tenantId, UUID citizenId) {
    CitizenConsent consent = consentRepository.findOne(
        Specification
            .where((root, query, cb) -> 
                cb.and(
                    cb.equal(root.get("tenantId"), tenantId),
                    cb.equal(root.get("citizenId"), citizenId),
                    cb.equal(root.get("consentType"), "EMAIL")
                )
            )
    );
    
    return consent != null && consent.isGranted();
}

CREATE TABLE integration_credentials (
    id                UUID PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    integration_name  VARCHAR(100),  -- "SEI", "TRAFFIC_SYSTEM", "PROBPMS"
    api_key           VARCHAR(512),  -- encrypted
    api_secret        VARCHAR(512),  -- encrypted
    endpoint_url      VARCHAR(1024),
    status            VARCHAR(50),
    last_validated_at TIMESTAMP,
    
    INDEX idx_integrations_tenant (tenant_id),
    UNIQUE(tenant_id, integration_name)
);

public void storeIntegrationCredential(
    UUID tenantId, 
    String integrationName, 
    String apiKey, 
    String apiSecret
) {
    IntegrationCredential credential = new IntegrationCredential(
        tenantId,
        integrationName,
        encryptionService.encrypt(apiKey),
        encryptionService.encrypt(apiSecret)
    );
    
    credentialRepository.save(credential);
}

public Response callExternalAPI(
    String integrationName, 
    String endpoint, 
    String payload
) {
    UUID currentTenant = TenantContext.getCurrent().getTenantId();
    
    IntegrationCredential credential = 
        credentialRepository.findOne(
            Specification
                .where((root, query, cb) -> 
                    cb.and(
                        cb.equal(root.get("tenantId"), currentTenant),
                        cb.equal(root.get("integrationName"), integrationName)
                    )
                )
        );
    
    if (credential == null) {
        throw new NotFoundException("Integration not configured for tenant");
    }
    
    String decryptedKey = encryptionService.decrypt(credential.getApiKey());
    
    return externalApiClient.call(
        credential.getEndpointUrl(),
        endpoint,
        decryptedKey,
        payload
    );
}

CREATE TABLE integration_logs (
    id                BIGINT PRIMARY KEY,
    tenant_id         UUID NOT NULL,
    integration_name  VARCHAR(100),
    request_at        TIMESTAMP,
    request_payload   TEXT,  -- primeiros 4KB por segurança
    response_status   INT,
    response_payload  TEXT,  -- primeiros 4KB
    duration_ms       INT,
    error_message     TEXT,
    
    INDEX idx_integration_logs_tenant (tenant_id),
    INDEX idx_integration_logs_tenant_integration (tenant_id, integration_name)
);

List<IntegrationLog> getIntegrationLogs(
    UUID tenantId, 
    String integrationName, 
    LocalDateTime from, 
    LocalDateTime to
) {
    return logRepository.findAll(
        Specification
            .where((root, query, cb) -> 
                cb.and(
                    cb.equal(root.get("tenantId"), tenantId),
                    cb.equal(root.get("integrationName"), integrationName),
                    cb.between(root.get("requestAt"), from, to)
                )
            ),
        Sort.by("requestAt").descending()
    );
}

@Entity
@Table(name = "requests")
public class Request {
    
    @EmbeddedId
    private RequestId id;  // Contém UUID + tenantId
    
    @Embedded
    private TenantId tenantId;
    
    @Embedded
    private CitizenId citizenId;
    
    @Embedded
    private ServiceId serviceId;
    
    private String status;
    private LocalDateTime createdAt;
    
    // Constructor valida tenant
    public Request(
        RequestId id,
        TenantId tenantId,
        CitizenId citizenId,
        ServiceId serviceId
    ) {
        this.id = id;
        this.tenantId = tenantId;
        this.citizenId = citizenId;
        this.serviceId = serviceId;
        this.createdAt = LocalDateTime.now();
    }
    
    // Métodos de negócio validam tenant implicitamente
    public void approve() {
        if (!this.status.equals("IN_ANALYSIS")) {
            throw new InvalidStateException();
        }
        this.status = "APPROVED";
    }
}

@Embeddable
public class RequestId implements ValueObject {
    
    @Column(name = "id")
    private UUID value;
    
    @Column(name = "tenant_id")
    private UUID tenantId;
    
    // Constructor privado
    private RequestId() {}
    
    public RequestId(UUID value, UUID tenantId) {
        Objects.requireNonNull(value);
        Objects.requireNonNull(tenantId);
        this.value = value;
        this.tenantId = tenantId;
    }
    
    // Equals considera tenant
    @Override
    public boolean equals(Object o) {
        if (!(o instanceof RequestId)) return false;
        RequestId that = (RequestId) o;
        return this.value.equals(that.value) && 
               this.tenantId.equals(that.tenantId);
    }
    
    @Override
    public int hashCode() {
        return Objects.hash(value, tenantId);
    }
}

@Test
public void testCannotAccessRequestFromOtherTenant() {
    // Setup
    Tenant tenant1 = tenantRepository.save(new Tenant("Tenant 1"));
    Tenant tenant2 = tenantRepository.save(new Tenant("Tenant 2"));
    
    User user1 = createUser(tenant1);
    
    Request request2 = requestRepository.save(
        new Request(UUID.randomUUID(), tenant2.getId(), "...")
    );
    
    // Attempt
    TenantContext.setCurrent(tenant1.getId());
    
    // Assert
    assertThrows(
        ForbiddenException.class,
        () -> requestService.getRequest(request2.getId())
    );
}

@Test
public void testCacheRespectsTenantBoundary() {
    // Tenant 1 busca usuário
    TenantContext.setCurrent(tenant1.getId());
    User user1 = userService.getUser(userId);
    
    // Tenant 2 busca usuário com mesmo ID
    TenantContext.setCurrent(tenant2.getId());
    User user2 = userService.getUser(userId);
    
    // Devem ser usuários diferentes
    assertNotEquals(user1, user2);
}

@Test
public void testDatabaseConstraintEnforcesTenant() {
    // Tenta inserir documento sem tenant_id
    assertThrows(
        DataIntegrityViolationException.class,
        () -> {
            Document doc = new Document();
            doc.setId(UUID.randomUUID());
            doc.setTenantId(null);  // Violação
            documentRepository.save(doc);
        }
    );
}

@Test
public void testQueryParameterTenantBypassBlocked() {
    // Tenant 1 tenta acessar via query param fake
    TenantContext.setCurrent(tenant1.getId());
    
    // Mesmo que envie X-Tenant-Id=tenant2, será ignorado
    String result = mvc.perform(
        get("/api/requests/req-123")
            .header("X-Tenant-Id", tenant2.getId().toString())
    )
    .andExpect(status().isForbidden());
}

@Test
public void testRawSQLInjectionRespectsTenant() {
    // Tenta SQL injection para contornar filtro de tenant
    TenantContext.setCurrent(tenant1.getId());
    
    assertThrows(
        Exception.class,
        () -> requestRepository.findAllRaw(
            "SELECT * FROM requests WHERE id = '" + 
            "req-123' OR tenant_id IS NOT NULL --'"
        )
    );
}