Capítulo 15 — Arquitetura de Dados, Persistência e Cache

15.1 Objetivo do Capítulo

Este capítulo estabelece as diretrizes técnicas para armazenamento, isolamento, consistência, movimentação, retenção, auditoria, consulta e aceleração de dados da Plataforma de Relacionamento Digital com o Cidadão.

A arquitetura separa claramente as responsabilidades por tipo de dado:

Dados transacionais operacionais → bancos dos serviços de domínio
Dados documentais                → Document Service + GED
Dados de cache                   → Redis
Dados de busca textual           → índice de busca (projeção reconstruível)
Dados vetoriais                  → vector store segregado por tenant
Dados analíticos                 → Data Lake por tenant
Dados de auditoria               → Audit Store imutável

Nenhum componente único atende indistintamente a todas essas necessidades. A tecnologia de persistência é selecionada conforme a natureza do dado e a responsabilidade arquitetural.

15.2 Princípios da Arquitetura de Dados

1. Ownership por domínio — cada domínio é o único responsável por gravar em seu armazenamento;
2. Isolamento multi-tenant — dados de um tenant nunca são acessíveis por outro;
3. Menor privilégio — cada serviço possui credenciais próprias com permissões mínimas;
4. Consistência definida pelo caso de uso — transações locais para operações dentro de um domínio; consistência eventual entre domínios via eventos;
5. Cache como otimização — nunca como fonte implícita da verdade;
6. Separação OLTP / OLAP — dados transacionais e analíticos têm responsabilidades distintas;
7. Minimização de dados pessoais — PII apenas onde necessário, com finalidade definida;
8. Rastreabilidade — alterações sensíveis são auditadas com trilha imutável;
9. Retenção governada — cada tipo de dado tem política de retenção e exclusão;
10. Índices como projeções — índices de busca e vetores são reconstruíveis; não são fonte de verdade.

15.3 Dados Transacionais Operacionais

15.3.1 Propriedade por Serviço

Cada serviço de domínio é o único responsável por gravar em seu armazenamento operacional. Nenhum outro serviço acessa diretamente as tabelas de outro domínio. Colaboração ocorre por API síncrona ou por eventos RabbitMQ.

Request Service    → banco request-service
Workflow Service   → banco workflow-service
Citizen Service    → banco citizen-service
Document Service   → banco document-service (metadados)
Scheduling Service → banco scheduling-service

A separação física entre bancos (banco dedicado por serviço, schema por serviço ou banco compartilhado com schemas distintos) é definida por ADR-111, considerando criticidade, escala, isolamento e custo operacional.

15.3.2 Credenciais por Serviço

Cada serviço usa credenciais de banco específicas com permissões mínimas. Não existe credencial administrativa compartilhada entre serviços.

request-service-db-user       → SELECT, INSERT, UPDATE, DELETE em request.*
workflow-service-db-user      → SELECT, INSERT, UPDATE, DELETE em workflow.*

15.3.3 Isolamento Multi-Tenant

A estratégia de isolamento multi-tenant na camada de dados é uma das decisões arquiteturais mais críticas da plataforma. Três modelos são avaliados:

Banco por Tenant: isolamento máximo, backup individual, restauração individual. Custo: provisionamento, migrations e operação em escala.

Schema por Tenant: segregação lógica dentro do mesmo cluster. Custo: grande número de schemas, migrations por schema, gestão de connection pools.

Shared Schema com Tenant Discriminator: tabelas tenant-scoped incluem tenant_id. Simplicidade operacional para muitos tenants. Exige disciplina rigorosa: Tenant Context estrutural no backend, constraints e índices multi-tenant corretos.

Estratégia Híbrida: a maioria dos tenants em shared schema; tenants com requisitos específicos (volume, contratual, regulatório) em banco ou schema dedicado. O Tenant Context determina o roteamento.

A decisão definitiva é registrada como ADR-112.

15.3.4 Padrões de Dados Multi-Tenant

Quando o modelo compartilhado é adotado, as regras seguintes são obrigatórias:

Tenant Discriminator em tabelas scoped:

CREATE TABLE requests (
  id         UUID PRIMARY KEY,
  tenant_id  VARCHAR NOT NULL,
  ...
);

Constraints com tenant:

-- Incorreto: dois tenants podem usar o mesmo código
UNIQUE (protocol_code)

-- Correto: unicidade é por tenant
UNIQUE (tenant_id, protocol_code)

Índices orientados a queries reais:

-- Query comum: filtro por tenant + status + ordenação
CREATE INDEX idx_requests_tenant_status_created
ON requests (tenant_id, status, created_at DESC);

O tenant_id efetivo vem sempre do Tenant Context validado — nunca de parâmetro enviado pelo cliente como única fonte.

Row-Level Security (RLS): quando o banco suporta, RLS é avaliado como camada adicional de proteção para prevenir vazamento por query sem filtro de tenant. Registrado como ADR-114.

15.3.5 Transações

Transações permanecem locais ao serviço. A plataforma não usa transações distribuídas (2PC). Consistência entre domínios é obtida por eventos com Transactional Outbox e idempotência nos consumidores.

BEGIN TRANSACTION (banco do Request Service)
  UPDATE request SET status = 'SUBMITTED'
  INSERT INTO outbox_event (...)
COMMIT

O Workflow Service recebe o evento e atualiza seu próprio banco em transação local.

15.3.6 Controle de Concorrência

Optimistic Locking para a maioria das operações concorrentes:

UPDATE requests SET status = 'APPROVED', version = 19
WHERE id = ? AND tenant_id = ? AND version = 18
-- zero rows = conflito detectado → 409 Conflict para o cliente

Pessimistic Locking para seções críticas curtas com recurso escasso (ex.: última vaga em agendamento). Evitado em operações longas.

Distributed Locks via Redis para coordenação entre instâncias quando o banco do serviço não é suficiente (ex.: reconciliação periódica única por tenant). O lock deve ter: owner token, TTL, aquisição atômica e liberação segura pelo owner.

15.3.7 Migrações de Schema

Migrations são automatizadas (Flyway ou Liquibase — decisão padronizada na plataforma), versionadas no repositório do serviço proprietário e executadas no deploy.

Estratégia Expand-Migrate-Contract para zero-downtime:

1. EXPAND  → adicionar nova coluna nullable
2. DEPLOY  → versão nova e antiga do serviço rodam simultaneamente
3. MIGRATE → backfill dos dados existentes (em batches para grande volume)
4. SWITCH  → código migrado para usar nova estrutura
5. CONTRACT → remover coluna antiga em release posterior

Backfills de grande volume nunca são executados como migration bloqueante no startup. São jobs com checkpoint, rate control e observabilidade.

15.3.8 Temporalidade

A plataforma distingue semanticamente:

Timestamps em UTC obrigatoriamente. A interface apresenta no fuso do usuário; o backend armazena e processa em UTC.

15.3.9 Auditoria

Alterações sensíveis são registradas em trilha imutável com: data/hora UTC, tenant_id, subject_id, tipo de ação, recurso afetado e resultado. O Audit Store é segregado do banco operacional. Consultas à trilha são restritas por perfil e registradas como auditoria de segunda ordem.

Dados pessoais na trilha são minimizados — referências ao dado, não cópias completas.

15.3.10 Retenção e Exclusão

Cada tipo de dado tem política de retenção definida. Exclusão lógica (deleted_at) é avaliada por domínio — não é regra global. Dados pessoais seguem a LGPD: são anonimizados ou excluídos quando a finalidade cessa ou o titular solicita. A política é registrada por domínio e formalizada por ADR-124.

15.4 Cache — Redis

Redis é o candidato prioritário para cache distribuído e controles técnicos da plataforma.

15.4.1 Usos Candidatos do Cache

O cache não é usado como fonte de verdade. Cada dado em cache tem fonte autoritativa no banco do domínio responsável.

15.4.2 Convenção de Cache Keys

Chaves são estruturadas de forma hierárquica e sempre incluem o tenant:

platform:v1:tenant:{tenantId}:catalog:service:{serviceId}
platform:v1:tenant:{tenantId}:config:{key}
platform:v1:tenant:{tenantId}:permissions:{subjectId}
platform:v1:rate-limit:tenant:{tenantId}:subject:{subjectId}:{endpoint}

A versão da estrutura na chave (v1) permite invalidar todo o cache de uma versão sem afetar outras. O tenant no namespace garante que uma consulta de um tenant nunca retorne dados de outro, mesmo por erro de aplicação.

15.4.3 TTL e Invalidação

Cada cache tem TTL explícito definido conforme a volatilidade do dado:

TTL nunca é zero (cache eterno) nem extremamente longo sem justificativa. Jitter é aplicado ao TTL de chaves populares para evitar cache stampede.

15.4.4 Cache Stampede

Quando uma chave muito acessada expira simultaneamente em múltiplas instâncias:

10.000 requests → mesmo cache miss → 10.000 queries no banco

Mitigações aplicadas: jitter no TTL; single-flight (apenas uma requisição consulta a origem enquanto outras aguardam); lock curto na recomputação; stale-while-revalidate para dados tolerantes a eventual staleness.

15.4.5 Política de Falha do Cache

A política de falha é explícita por tipo de uso:

15.4.6 Redis e Dados Pessoais

Dados pessoais em cache são minimizados. Identificadores são cacheados no lugar de dados completos quando possível. Campos sensíveis (CPF, nome, e-mail) não são indexados como chave de cache sem necessidade funcional explícita. Dados pessoais em cache seguem TTL curto.

15.4.7 Alta Disponibilidade do Redis

A topologia de Redis (Sentinel, Cluster, Replication) é definida por ambiente. Em produção, a configuração garante que a indisponibilidade de um nó não derrube o serviço. A persistência do Redis (RDB, AOF) é configurada por tipo de uso: cache puro tolera reconstrução; rate limiting e sessões podem exigir persistência.

15.5 Busca

15.5.1 Busca Textual

A plataforma avalia mecanismo especializado de busca para casos onde consultas relacionais simples não são suficientes:

• catálogo de serviços (busca por nome, categoria, órgão);
• conteúdo documental indexado;
• pesquisa administrativa em grandes volumes.

A tecnologia é selecionada após definição de requisitos de volume, relevância, idioma, filtros e modelo operacional. Decisão registrada como ADR-136.

O índice de busca é uma projeção reconstruível — não é fonte de verdade. Em caso de inconsistência, o banco operacional prevalece e o índice é reindexado.

15.5.2 Busca Vetorial (Semântica)

A busca vetorial suporta o RAG e a busca semântica dos serviços de IA. Os vetores (embeddings) são gerados a partir de conteúdo autorizado e armazenados em vector store segregado por tenant.

Isolamento obrigatório por tenant:

• cada tenant tem sua própria coleção ou namespace vetorial;
• uma query de busca semântica do tenant A nunca retorna conteúdo do tenant B;
• a segregação é estrutural, não apenas por filtro de aplicação.

Pipeline de indexação:

Documento/Conteúdo autorizado
    │
Validação de acesso e classificação
    │
Sanitização e chunking
    │
Geração de embeddings (modelo aprovado)
    │
Armazenamento no vector store do tenant
    │
Publicação de ai.knowledge-indexed.v1

O vector store não substitui o banco operacional como fonte de verdade do documento. A base vetorial é reconstruível a partir dos documentos autorizados armazenados no Document Service / GED.

15.6 Data Lake por Tenant

15.6.1 Finalidade

O Data Lake consolida dados analíticos, histórico operacional e datasets para IA. Não é banco operacional — não serve consultas transacionais em tempo real dos serviços de domínio.

Dados transacionais → banco do domínio (OLTP)
Dados analíticos    → Data Lake (OLAP)

Serviços de domínio nunca consultam o Data Lake para decisões de negócio em tempo real.

15.6.2 Ingestão por Eventos

O principal mecanismo de ingestão é o consumo de eventos RabbitMQ:

Domínio publica evento com tenantId
    │
RabbitMQ platform.events
    │
Data Lake Ingestion Consumer
    │
  Valida contrato e idempotência
    │
  Aplica regras de qualidade
    │
  Persiste na partição do tenant
    │
  Registra linhagem

A ingestão é idempotente. O campo id do evento garante deduplicação.

15.6.3 Ingestão em Lote

Para datasets históricos, migrações ou integrações que não emitem eventos, a ingestão em lote é usada com controle de checkpoint, idempotência por chave de negócio e monitoramento de progresso.

15.6.4 Zonas do Data Lake

O Data Lake é organizado em zonas de maturidade dos dados:

Raw Zone     → dados brutos como ingeridos, imutáveis
Refined Zone → dados limpos, validados e conformados
Curated Zone → datasets prontos para consumo (analytics, BI, IA)

Cada zona tem acesso controlado por perfil e finalidade.

15.6.5 Segregação por Tenant

Cada tenant tem partição própria no Data Lake. A segregação é estrutural — uma query analítica do tenant A nunca acessa partição do tenant B. O acesso ao Data Lake de um tenant é restrito a: analistas do próprio tenant com perfil autorizado, componentes de IA do tenant, jobs de qualidade com escopo de tenant.

15.6.6 Data Contracts

Cada dataset tem contrato formal descrevendo: schema, campos, tipos, semântica, produtor, frequência de atualização, nível de qualidade esperado e política de evolução. Mudanças incompatíveis nos contratos seguem o mesmo processo de versionamento dos eventos.

15.6.7 Linhagem e Qualidade

A linhagem registra a cadeia de transformações de cada dado desde a origem. A qualidade é monitorada por dimensão (completude, validade, atualidade, consistência, unicidade). O Data Quality Service emite alertas quando thresholds são violados.

15.6.8 Integração com Data Lake MG

Quando formalmente estabelecida, a integração com o Data Lake MG compartilha datasets autorizados conforme política definida com a PRODEMGE. Cada dataset compartilhado tem finalidade, classificação e controles de acesso documentados. Dados pessoais são minimizados antes do compartilhamento.

15.7 Gestão Documental (GED)

15.7.1 Document Service

O Document Service é o único componente que acessa o armazenamento de documentos binários. Outros serviços obtêm referências — nunca manipulam o binário diretamente.

Serviço de Domínio      → usa referência (documentId)
Document Service        → armazena e recupera binários + metadados
Storage (object/GED)    → persiste bytes com identificação de tenant

15.7.2 Metadados e Integridade

Cada documento armazena: hash de integridade (checksum no recebimento), tenant_id, owner, tipo, classificação, versão, associações (solicitação, processo, cidadão), histórico de acesso e situação.

15.7.3 Versionamento

Versões de documento são imutáveis. A publicação de uma nova versão não sobrescreve a anterior. O histórico de versões é preservado conforme política de retenção do tenant.

15.7.4 Integração Assíncrona

Processamentos pesados de documentos (OCR, extração de metadados, indexação para IA) são desacoplados por RabbitMQ:

document.uploaded.v1
    │
OCR Worker           → extrai texto
Metadata Worker      → extrai metadados estruturados
AI Builder           → gera embeddings para RAG (se autorizado)

15.7.5 Documentos e IA

Nem todo documento do GED é indexado automaticamente na base de conhecimento de IA. A indexação requer autorização explícita por política do tenant. O conteúdo enviado à IA é classificado e sanitizado antes do processamento.

15.8 Backup e Recuperação

15.8.1 Princípio

Um backup sem teste de restauração não é backup — é esperança. A plataforma define: objetivo de ponto de recuperação (RPO), objetivo de tempo de recuperação (RTO), frequência de backup por componente e procedimento de restore test executado periodicamente.

15.8.2 Componentes e Estratégias

15.8.3 Backup Multi-Tenant

A estratégia permite restauração seletiva por tenant quando necessário, sem impactar dados de outros tenants. A recuperação de um tenant em ponto específico no tempo (PITR) é avaliada por ADR-145.

15.8.4 Disaster Recovery

O plano de Disaster Recovery define: RTO e RPO por componente, sequência de restauração, dependências entre componentes, procedimento de validação pós-restauração e responsáveis. É testado periodicamente com resultados documentados.

15.9 Proteção de Dados Pessoais (LGPD)

15.9.1 Minimização

PII é coletado e armazenado apenas onde necessário à finalidade declarada. Datasets derivados (cache, índices, vetores, Data Lake, Audit Store) contêm apenas o mínimo necessário — identificadores no lugar de dados pessoais quando possível.

15.9.2 Classificação

Dados são classificados por sensibilidade: público, interno, confidencial, restrito. Dados pessoais sensíveis (saúde, biometria, origem racial, orientação sexual) têm controles adicionais. A classificação orienta: criptografia em campo, mascaramento, acesso restrito e retenção.

15.9.3 Exclusão e Anonimização

Quando a finalidade do tratamento cessa ou o titular solicita exclusão:

• dados pessoais são anonimizados (tornados não identificáveis) ou excluídos;
• dados em cache são invalidados;
• embeddings de conteúdo identificável são avaliados para reembedding ou exclusão;
• a exclusão no Data Lake segue política de retenção e formato do dataset.

15.9.4 Dados de Produção em Desenvolvimento

Dados reais de produção não são copiados para ambientes de desenvolvimento ou homologação. Dados sintéticos ou mascarados são usados para testes que exijam massa representativa.

15.10 Observabilidade de Dados

15.10.1 Métricas de Banco

15.10.2 Métricas de Redis

Alta taxa de hit não é analisada isoladamente — o cache pode ter alto hit ratio e ainda armazenar dados inconsistentes após falha de invalidação.

15.10.3 Métricas do Data Lake

Volume ingerido por tenant e por evento; latência de ingestão; falhas de qualidade detectadas; datasets com freshness vencida; jobs de ingestão com duração acima do esperado.

15.10.4 Métricas do Vector Store

Taxa de indexação por tenant; latência de busca semântica; volume de chunks por base de conhecimento; falhas de geração de embedding.

15.11 Decisões Confirmadas

1. a plataforma é multi-tenant; isolamento de dados é obrigatório em todos os componentes;
2. cada serviço de domínio é o único responsável por gravar em seu armazenamento;
3. nenhum serviço acessa diretamente os dados de outro domínio;
4. transações permanecem locais; consistência entre domínios é por eventos + idempotência;
5. o Data Lake não é banco operacional; serviços de domínio não o consultam em tempo real;
6. Redis é candidato prioritário para cache distribuído;
7. caches tenant-scoped incluem o tenant no namespace da chave;
8. o cache não é fonte implícita da verdade;
9. índices de busca são projeções reconstruíveis;
10. bases vetoriais são segregadas por tenant de forma estrutural;
11. documentos binários não trafegam pelo RabbitMQ — apenas referências;
12. dados pessoais são minimizados em bancos derivados, caches, índices, vetores e Data Lake;
13. migrations seguem Expand-Migrate-Contract para zero-downtime;
14. backup é considerado efetivo apenas quando restauração é testada;
15. observabilidade de dados inclui métricas de banco, Redis, busca, vetores e Data Lake.

15.12 Benefícios da Arquitetura

• ownership claro com fonte de verdade definida por domínio;
• isolamento multi-tenant em todas as camadas de dados;
• consistência controlada: forte dentro do domínio, eventual entre domínios;
• cache governado com TTL, invalidação e política de falha por tipo;
• dados analíticos separados dos operacionais sem acoplamento;
• bases vetoriais segregadas por tenant para RAG seguro;
• gestão documental centralizada no Document Service com versionamento;
• recuperação testável com RPO e RTO definidos;
• minimização de dados pessoais em todas as camadas derivadas;
• observabilidade integrada para banco, cache, busca, Data Lake e vetores.

15.13 Riscos e Mitigações

15.14 Decisões Arquiteturais

15.15 Rastreabilidade com o Anexo III

• Bloco 1 — Relacionamento e Atendimento: persistência transacional de solicitações, protocolos, interações e comunicações; cache de catálogo e configurações; Data Lake para métricas de atendimento.
• Bloco 2 — BPM: bancos de Workflow e Task com ownership separado; Transactional Outbox para consistência entre Request e Workflow; optimistic locking em tarefas concorrentes.
• Bloco 3 — Gestão Documental: Document Service com GED; metadados e versionamento; hash de integridade; pipeline assíncrono de processamento documental.
• Bloco 4 — Dados e Inteligência: Data Lake por tenant com ingestão por eventos; vector store segregado; bases de conhecimento RAG por tenant; Data Contracts e qualidade.
• Bloco 5 — Integração: Data Lake MG como destino de datasets autorizados; linhagem de dados compartilhados; contratos de dataset.
• Bloco 6 — Infraestrutura, Segurança e Governança: credenciais por serviço, menor privilégio, RLS, minimização de PII, auditoria imutável, backup com restore testado.

15.16 Considerações Finais

A Arquitetura de Dados não é uma decisão única — é um conjunto de decisões coordenadas sobre como cada tipo de dado é armazenado, acessado, protegido e descartado ao longo do ciclo de vida da plataforma.

O princípio central é simples: cada dado tem um dono, e somente esse dono grava nele. O restante acessa por contrato. O isolamento multi-tenant não é uma camada que se adiciona depois — é uma propriedade estrutural desde a modelagem.

O Capítulo 16 detalha a Arquitetura de Inteligência Artificial, RAG e Automação Inteligente, descrevendo como as bases vetoriais, os modelos e os guardrails definidos neste capítulo se articulam com as capacidades de IA da plataforma.

15.17 Controle de Versão

15.18 Rastreabilidade PRODEMGE

• [ANX-III] — Blocos 1 a 6 cobertos conforme seção 15.15.
• [ANX-IV] — Capacidades técnicas de isolamento multi-tenant, Data Lake, cache distribuído, busca semântica, GED, backup e observabilidade de dados.
• [ANX-V] — Sustentabilidade: ownership de dados por domínio, migrations automatizadas com Expand-Migrate-Contract, retenção governada, índices como projeções reconstruíveis, observabilidade integrada.
• [PNR] — Plano de Negócio Referencial: plataforma com capacidade analítica, Data Lake, gestão documental, IA com RAG e isolamento multi-tenant em todas as camadas.
• [EDITAL] — Edital CP001/2026: plataforma com arquitetura de dados escalável, segura, com governança e evolução contínua ao longo da vigência da parceria.