Data Foundation — Fundação de Dados da SDUH
Código: HORUS-ARQ-DF-001 Versão: 1.0 — 2026-10-07 Escopo: Fundação de dados da SDUH: como os dados são estruturados, armazenados, movidos, catalogados, protegidos e operados, e quais tecnologias sustentam cada função. A aplicação (frontend, backend transacional, autenticação de usuários) está fora do escopo. Documentos relacionados: Doc 02, Doc 03, Doc 04, Doc 05 e Doc 06.
1. Objetivo e Escopo
Este documento descreve a fundação de dados (data foundation) da SDUH em uma única visão: o que existe, como os componentes se relacionam e quais regras valem para eles. Ele não repete o detalhe dos demais documentos; indica onde cada regra é definida.
| Pergunta | Onde está a resposta |
|---|---|
| Quais são os princípios e as fronteiras da fundação? | Seções 2 e 3 |
| Quais dados existem e como são modelados? | Seção 4 e Docs 03, 05 e 06 |
| Que tecnologia faz o quê? | Seção 5 |
| Como a API de Cadastro Mestre é mantida disponível? | Seção 6 |
| Quem decide e como a mudança é aprovada? | Seção 7 e Docs 04, 05 e 07 |
| Como o banco é protegido, recuperado e operado? | Seção 8 e Docs 04 e 08 |
2. Princípios da Fundação
| Princípio | Regra |
|---|---|
| Plataforma única e gerenciada | 100% Google Cloud Platform (GCP), somente serviços gerenciados. Nenhuma ferramenta de ETL, orquestração, streaming ou mensageria fora do GCP. |
| Soberania dos dados | Todos os dados, réplicas e backups ficam exclusivamente em southamerica-east1 (São Paulo). A soberania prevalece sobre a redução de RPO e RTO em desastre de região. |
| Separação operacional e analítico | O PostgreSQL é o banco operacional. O BigQuery é somente leitura para os sistemas operacionais. O fluxo é sempre PostgreSQL → pipeline → Bronze → Silver → Gold. |
| Dado mestre com dono único | Cada entidade mestre tem um sistema dono, vive no schema mdm do banco do dono e é consumida por API. Uma entidade mestre nunca é duplicada em um domínio. |
| Domínios de negócio | Cada domínio tem schema próprio no PostgreSQL e datasets próprios no BigQuery (_bronze, _silver, _gold). |
| Segurança e LGPD por desenho | Classificação de toda coluna sensível, mascaramento fora de produção, acesso por identidade de serviço e auditoria obrigatória. |
| Mudança sob rito | Toda mudança de schema passa por proposta, revisão e promoção HOM → PROD, com scripts versionados e imutáveis após a promoção para PROD. |
3. Arquitetura da Fundação
3.1 Fluxo de dados
3.2 Nuvem e ambientes
- Região única:
southamerica-east1para todos os serviços. - Ambientes: HOM e PROD em projetos GCP separados (
{projeto}-home{projeto}-prod). HOM não contém PII real (Doc 05, Seção 5.3). - Hospedagem dos serviços de dados: Cloud Run (API de Cadastro Mestre e API de dados), contêineres gerenciados com escala automática.
- Premissas de conformidade: os dados seguem a LGPD e são acessados por camadas autenticadas; o BigQuery não é exposto diretamente aos usuários finais.
4. Domínios e Modelo de Dados
4.1 Domínios
A tabela abaixo é uma referência preliminar, derivada do Doc 03, que é esboço e não é autoritativo. Cada domínio tem um schema no PostgreSQL e três datasets no BigQuery.
| Domínio | Sistema de origem | Schema PG | Datasets BQ |
|---|---|---|---|
| Regularização Fundiária | Cidade Legal | regularizacao | regularizacao_bronze/silver/gold |
| Aprovação e Certificação | GRAPROHAB | aprovacao | aprovacao_bronze/silver/gold |
| Subsídio Habitacional | CPADM (Casa Paulista) | subsidio | subsidio_bronze/silver/gold |
| Habitação Popular | Nossa Casa | habitacao | habitacao_bronze/silver/gold |
| Comunicação Institucional | Site SHCDHU + Newsletter | comunicacao | comunicacao_bronze/silver/gold |
| Corporativo / Administrativo | Segurança (IAM) + RH | banco corporativo | corporativo_bronze/silver/gold |
| Solicitações Municipais | Sistema de solicitações municipais | solicitacao | solicitacao_bronze/silver/gold |
4.2 Entidades mestres (MDM)
As entidades mestres previstas são Pessoa, Município (chave canônica id_municipio, com cd_ibge de 7 dígitos como chave natural), Programa Habitacional, Empresa/Construtora e Arquivo/Mídia. A unificação de Empreendimento em uma entidade mestre está em definição. Todas residem no schema mdm do banco do sistema dono.
Quem consome dado mestre de outro banco usa a API de Cadastro Mestre do sistema dono, com FK lógica, conciliação de órfãos e fusão de duplicidades com aprovação e registro (Doc 06, REG-CM-17 a 26). A API é dependência crítica; a resiliência está na Seção 6.
4.3 Padrões de modelagem
- Schemas e tabelas em
snake_case; chave primária UUIDv7. - Colunas obrigatórias de auditoria e de soft delete, com índice único parcial para chave de negócio.
- Prefixo de coluna obrigatório quando a coluna se enquadra em um termo do catálogo; glossário de vocabulário controlado mantido no Knowledge Catalog.
- BigQuery com
fato_*,dim_*e{sistema}_{tabela}_raw; semSELECT *na camada Gold e sem nomes genéricos.
As regras completas estão nos Docs 05 e 06.
5. Componentes e Tecnologias por Função
5.1 Cadastro Mestre
| Tecnologia | Função e regra de uso |
|---|---|
| API de Cadastro Mestre (Cloud Run) | Serviço do sistema dono, dono exclusivo do schema mdm. Consulta por id, em lote e por chave de negócio (CPF, CNPJ, IBGE); escrita por upsert idempotente; resolução de ids fundidos; evento de fusão publicado no Pub/Sub. Ingress interno, autenticação entre serviços por identidade de serviço do GCP (OIDC) e contrato OpenAPI versionado. "API de Cadastro Mestre" é um papel: cada sistema que origina dado mestre expõe a sua (Doc 06, Seção 3.7). |
5.2 Armazenamento
| Tecnologia | Função e regra de uso |
|---|---|
| Cloud SQL for PostgreSQL | Banco operacional padrão, em instância regional de alta disponibilidade, com IP privado e SSD com autoscale. Organiza os dados em schemas por domínio. Versão major mais recente com suporte vigente. |
| PgBouncer | Pool de conexões em transaction pooling na frente do PostgreSQL. Conexões diretas só para o Arquiteto de Dados e pipelines de ETL. |
| Cloud SQL Auth Proxy | Acesso humano seguro ao banco, com MFA, sem IP público. |
| IAM Database Authentication | Autenticação no banco por identidade de serviço. Dispensa senha armazenada. |
| Papéis de banco | {sistema}_app, _readonly, _etl, _admin e _audit; concessão sempre por role (Doc 04, Seção 3). |
postgres_fdw | Leitura entre bancos, restrita a ETL e ao Arquiteto de Dados. Nunca em aplicação. |
| Google Cloud Storage (GCS) | Armazenamento de arquivos e objetos. Cada arquivo é registrado em mdm.arquivos. |
| Google BigQuery | Data warehouse analítico em medalhão (Bronze, Silver e Gold). Somente leitura para os sistemas operacionais; description obrigatória nas tabelas Gold e Policy Tags nas colunas PII. |
5.3 Ingestão, transformação e orquestração (somente GCP gerenciado)
| Tecnologia | Função e regra de uso |
|---|---|
| BigQuery Scheduled Queries | SQL agendado que carrega e transforma as camadas Silver e Gold. Dispensa orquestrador quando a etapa é isolada. |
| Dataform | Transformação SQL com versionamento e dependências entre tabelas. Alternativa às consultas agendadas. |
| Cloud Run Jobs | Contêineres em lote, agendados ou por evento, para ingestão e transformação em código (Python). |
| Cloud Functions | Funções sob demanda para rotinas reativas, como reconciliações e verificações entre cargas. |
| Cloud Composer (Apache Airflow) | Único orquestrador permitido, para pipelines com várias etapas dependentes. O DAG cobre a cadeia ponta a ponta. |
| Dataflow (Apache Beam) | Processamento em streaming, só quando a latência baixa é requisito. Alimentado pelo Pub/Sub. |
| Pub/Sub | Única mensageria permitida. Transporta eventos, como o de fusão de duplicidades do cadastro mestre. |
| CDC (Change Data Capture) | Captura de mudanças do PostgreSQL por log lógico (wal_level = logical) para cargas incrementais. Alternativa: carga por marca d'água em dh_atualizacao. |
Toda falha de pipeline gera alerta e nunca é silenciada; cargas incrementais são idempotentes (Doc 05, Seção 10). Dados vindos de sistemas legados chegam ao PostgreSQL com a coluna id_legado e mapeamento de tipos; o legado é só fonte, sem escrita de volta (Doc 04, Seção 6).
5.4 Catálogo, metadados e governança
| Tecnologia | Função e regra de uso |
|---|---|
| Knowledge Catalog (Google Cloud, Dataplex) | Catálogo institucional de dados do BigQuery e do PostgreSQL. Reúne metadados, classificação LGPD (Tag Templates de PII), glossário corporativo (fonte de verdade), indicadores de qualidade e confiança, e linhagem. |
| Policy Tags e Data Policies (BigQuery) | Restringem o acesso a colunas com dados pessoais por perfil e mascaram o dado para quem tem menos privilégio. |
COMMENT ON TABLE/COLUMN (PostgreSQL) | Documentação no banco, com o prefixo LGPD: nas colunas sensíveis e o nível de maturidade (Bronze, Silver ou Gold) no comentário da tabela. |
Campo description (BigQuery) | Documentação de datasets e tabelas. |
| Gemini (documentação assistida) | Gera descrições de tabelas e colunas do BigQuery pelo scan de documentação do Knowledge Catalog. A revisão é humana. |
5.5 Consumo
| Tecnologia | Função e regra de uso |
|---|---|
| Looker (LookML) | Camada semântica e dashboards sobre a camada Gold. Define cada métrica de negócio uma única vez. |
| Looker Studio Pro | Visualização de painéis sobre os dados do BigQuery. |
| API de dados (FastAPI, Python) | Serve a camada Gold, com cache em memória: TTL padrão de 15 minutos, renovação sob demanda por endpoint administrativo restrito e meta de latência p95 abaixo de 200 ms nas consultas cacheadas. Endpoints /public/ e /admin/, com perfis reader e maintainer; rotinas batch autenticam com segredo guardado no Secret Manager. |
| CKAN | Repositório de dados abertos. A catalogação e a governança ficam no Knowledge Catalog. |
5.6 Segurança, auditoria e observabilidade dos dados
| Tecnologia | Função e regra de uso |
|---|---|
| Cloud IAM | Controle de acesso por papéis e contas de serviço, sem login interativo. Base de todas as permissões. |
| Secret Manager | Segredos de integração e chaves de API. Nenhum segredo fica em código ou imagem. |
Schema auditoria | log_operacao e acesso_emergencia, com trilha de eventos de segurança. Retenção de 2 anos no PostgreSQL e 5 anos no BigQuery (Doc 04, Seção 7). |
| Cloud Logging | Centraliza os logs de pipelines, banco e serviços. Base da investigação de falhas. |
| Cloud Monitoring | Métricas e alertas obrigatórios: CPU, disco, conexões, lag de replicação, consultas lentas, logins falhos, retenção de WAL, wraparound, órfãos de mestre e SLO da API de Cadastro Mestre (Doc 04, Seção 5.1). |
5.7 Origem dos dados
| Origem | Descrição |
|---|---|
| SQL Server (legado) | Banco dos sistemas legados. Funciona só como fonte, sem escrita de volta. |
| Bancos dos sistemas (PostgreSQL) | Bancos operacionais dos sistemas, fonte da camada Bronze. |
| Planilhas Excel | Cargas manuais, validadas antes de entrar no pipeline. |
| Fontes públicas (IBGE, TSE, S2ID) | Dados externos de referência territorial, eleitoral e de desastres, usados no enriquecimento. |
6. Resiliência da API de Cadastro Mestre
Os demais módulos dependem da API de Cadastro Mestre do sistema dono para gravar vínculos com o dado mestre; por isso o serviço é tratado como dependência crítica.
Metas de referência (valores iniciais, a revisar com a medição real):
| Indicador | Meta |
|---|---|
| Disponibilidade mensal (consultas), medida no horário de operação (dias úteis) | 99,9% |
| Latência p95 — consulta por id | < 100 ms |
| Latência p95 — consulta em lote (até 100 ids) | < 300 ms |
| Latência p95 — escrita (upsert) | < 500 ms |
O orçamento de erro decorrente da meta de disponibilidade orienta a decisão entre novas funcionalidades e trabalho de confiabilidade. Os indicadores são medidos no Cloud Monitoring (Doc 04, Seção 5.1).
Implantação: instância mínima maior que zero (sem cold start no caminho crítico), distribuição entre zonas e banco do sistema dono em instância regional de alta disponibilidade (Doc 04, Seção 2.1). O serviço é stateless e se recupera por novo deploy; a recuperação de dados segue o Doc 04, Seção 4.
Comportamento dos consumidores quando a API falha (Doc 06, REG-CM-22):
| Operação | Comportamento |
|---|---|
| Ler dado já vinculado, para exibição | Pode usar cache em memória do processo com TTL curto; sem cache persistente |
| Validar e gravar vínculo com o mestre | Falha explícita (HTTP 503), sem gravação; repetição posterior idempotente |
| Operações que não dependem do mestre | Seguem normalmente |
Padrões nos consumidores: timeout por operação, retry com backoff exponencial e jitter (no máximo 3 tentativas, só em operação idempotente), circuit breaker e limite de concorrência por consumidor.
Contrato: OpenAPI versionado. Acréscimo de campo opcional não quebra o contrato; remoção ou mudança de significado exige nova versão (/v2) com período de convivência. Testes de contrato rodam no CI do produtor e dos consumidores.
Validação: a indisponibilidade da API é simulada em HOM antes de cada mudança relevante de contrato ou de infraestrutura, para confirmar o comportamento da tabela acima.
7. Governança dos Dados
| Papel | Responsabilidade |
|---|---|
| Arquiteto de Dados | Responsável pelo dado mestre, pelo banco e pelos pipelines; presidência técnica do Comitê de Dados. |
| Comitê de Dados | Reunião mensal, com Arquiteto, Coordenação de TI, representantes dos domínios e DPO. Decide dono de dado mestre, novo schema, classificação LGPD, política de backup e retenção, acesso de terceiros e desativação de sistema legado. |
| Gestor técnico e de negócio por schema | O gestor técnico aprova DDL; o gestor de negócio valida as regras do domínio. |
| DPO (Encarregado LGPD) | Aprova mudanças que envolvam dados pessoais e a classificação das colunas. |
7.1 Classificação LGPD
PÚBLICO, INTERNO, RESTRITO e SIGILOSO. Dado RESTRITO é mascarado em HOM e pseudonimizado no BigQuery; dado SIGILOSO nunca é replicado nem exposto no BigQuery (Doc 05, Seção 3.4).
7.2 Mudança de schema
Fluxo: solicitante (PR) → Arquiteto de Dados → Gestor do Domínio → Tech Lead → merge em HOM → validação → merge em PROD. Nova tabela, novo schema, mudança de PK ou FK, remoção de coluna ou tabela e alteração de tipo exigem os três revisores; novo schema e mudança em entidade mestre exigem, além disso, a homologação do Comitê de Dados. Antes de aprovar uma tabela, o Arquiteto verifica que ela não recria uma entidade mestre (Doc 05, Seção 1).
7.3 Maturidade dos dados
| Nível | Critério | Uso permitido |
|---|---|---|
| Bronze | Dado bruto, sem validação. | Apenas ETL interno. |
| Silver | Dado limpo, tipado e deduplicado, sem lógica de negócio. | Pipelines analíticos e joins internos. |
| Gold | Dado validado, com lógica de negócio aprovada pelos gestores. | Dashboards, APIs e relatórios oficiais. |
8. Operação e Continuidade
8.1 Backup e recuperação
| Tipo | Frequência | Retenção |
|---|---|---|
| Backup automático (Cloud SQL) | Diário (janela 02h–04h BRT) | 30 dias |
| Point-in-Time Recovery (PITR) | Contínuo (arquivamento de WAL) | 7 dias |
Export manual (pg_dump) | Semanal | 90 dias |
| Export pré-mudança de risco | Antes de qualquer migração de risco | Indefinida |
| Cenário | RTO | RPO |
|---|---|---|
| Falha de zona (HA) | < 1 minuto | < 5 segundos |
| Corrupção de dados (PITR) | < 4 horas | Segundos a poucos minutos; recuperação possível até 7 dias atrás |
| Desastre de região | < 24 horas | Último backup diário |
Não há réplica nem backup fora de southamerica-east1. O restore de teste é trimestral, em ambiente isolado (Doc 04, Seção 4.3).
9. Documentos Relacionados
| Documento | Conteúdo |
|---|---|
| Doc 02 | Requisitos funcionais e não funcionais. |
| Doc 03 | Modelo corporativo de dados (esboço): domínios, entidades mestres, mapeamento para BigQuery Gold, glossário. |
| Doc 04 | Organização, acesso, backup, monitoramento, estratégia de carga de legados, auditoria e governança. |
| Doc 05 | Mudança de schema, nomenclatura, versionamento, BigQuery e diretrizes de ETL/ELT. |
| Doc 06 | Padrão de cadastro mestre (MDM): regras REG-CM, DDL do schema mdm, consumo. |
Histórico de revisões
| Versão | Alterações |
|---|---|
| 1.0 | Criação a partir do antigo Doc 01 (Arquitetura Técnica, ARQ-AT-001 v2.0) e dos documentos Data Foundation — Estrutura e Ferramentas e Data Foundation — Tecnologias Utilizadas. O conteúdo de aplicação (frontend, backend transacional, autenticação de usuários, fluxo de sessão e esteira de desenvolvimento) foi retirado. A seção de resiliência da API de Cadastro Mestre, antes na Seção 5.3, passou a ser a Seção 6. |