Modelo Físico PostgreSQL da Máquina de Conhecimento do LAC

1. Propósito

Este documento descreve a implementação física do banco de dados da Máquina de Conhecimento. Enquanto o modelo lógico define tabelas e relações, o modelo físico acrescenta comportamento operacional, validações executáveis, automação, auditoria e dados mínimos para inicialização.

Modelo físico: materialização tecnológica do modelo lógico em um SGBD específico, incluindo tipos nativos, índices, funções, triggers, privilégios, dados iniciais e mecanismos de operação.

2. Posição na cadeia

Teoria → Modelo → Arquitetura → Modelo conceitual → Dicionário → Perfil → Modelo lógico → Modelo físico PostgreSQL

O modelo físico não altera o significado das entidades anteriores. Ele transforma as regras conceituais e lógicas em mecanismos executáveis.

3. Componentes entregues

Estrutura

Schema, tabelas, chaves, restrições, índices e views.

Comportamento

Funções e triggers para integridade, datas, versões e publicação.

Governança

Auditoria de alterações em entidades críticas.

Vocabulários

Validação dos códigos usados pelos objetos e representações.

Dados iniciais

Papéis, agente autor, domínios, jornada e objeto inicial.

Auditoria de conformidade

Views para localizar objetos ou publicações incompletas.

4. Schema físico

Todos os objetos são criados no schema:

CREATE SCHEMA IF NOT EXISTS lac_mc;
SET search_path TO lac_mc, public;

Isso separa a Máquina de Conhecimento de outros sistemas que possam usar o mesmo banco PostgreSQL.

5. Extensão utilizada

O script ativa pgcrypto, preparando o banco para geração de hashes, UUIDs e funções criptográficas. O núcleo atual usa identificadores públicos controlados, mas a extensão poderá apoiar checksums e integrações futuras.

6. Funções utilitárias

Função	Finalidade
fn_normalizar_codigo	Converte texto em código padronizado para identificadores e vocabulários.
fn_atualizar_timestamp	Atualiza automaticamente `atualizado_em`.
fn_impedir_alteracao_id_publico	Protege identificadores conceituais persistentes.
fn_codigo_vocabulario_ativo	Confirma a existência e atividade de termos controlados.
fn_registrar_auditoria	Registra inserções, alterações e exclusões.
fn_validar_publicacao	Impede publicação de produção sem versão, validação e checksum.

7. Triggers implementadas

Datas automáticas

Atualizam o momento da última alteração em entidades mutáveis.

Identificadores imutáveis

Impedem a troca de IDs públicos após a criação.

Vocabulários

Validam tipos, estados, ambientes e classificações de acesso.

Versão vigente

Desativa automaticamente a versão anterior quando uma nova versão se torna vigente.

Publicação

Exige validação aprovada, versão e checksum para produção.

Auditoria

Registra alterações nos objetos, representações, versões, decisões, validações e publicações.

8. Regra de promoção para produção

Representação + versão vigente + validação aprovada + checksum → publicação em produção

Uma inserção em publicacao com ambiente producao e estado publicado é rejeitada quando qualquer requisito estiver ausente.

Resultado: copiar um arquivo para produção não é suficiente. A promoção deve existir como evento governado no banco.

9. Auditoria

A tabela auditoria_evento registra:

schema e tabela;
operação de inserção, alteração ou exclusão;
identificador do registro;
dados anteriores e novos em JSONB;
usuário do banco;
data, hora e identificador da transação.

A auditoria técnica complementa, mas não substitui, decisões formais de governança.

10. Views de controle

View	Uso
vw_objeto_conhecimento_resumo	Consulta consolidada dos objetos e sua situação.
vw_objeto_sem_idioma	Localiza objetos sem idioma registrado.
vw_objeto_sem_representacao	Localiza objetos ainda sem representação.
vw_objeto_publicado_sem_versao_vigente	Detecta objetos publicados sem versão conceitual vigente.
vw_publicacao_producao_sem_validacao	Audita publicações de produção sem validação aprovada.
vw_conformidade_objeto	Apresenta indicadores básicos de conformidade.

11. Dados iniciais

O script instala:

vocabulários de tipos de objeto, estados, acesso, representações, ambientes e publicação;
termos controlados iniciais;
agente AGE-WD-001, correspondente ao autor Walter Dominguez;
papéis Autor, Gestor, Curador e Agente de IA;
domínios Fundação, Fundamentos e Governança;
jornada JOR-MC-001;
objeto OC-MC-0001;
versão conceitual inicial;
representação HTML inicial em desenvolvimento.

12. Estado inicial intencional

O Objeto de Conhecimento inicial é inserido como aprovado, e sua representação como nao_publicado no ambiente de desenvolvimento.

Isso evita declarar artificialmente que a página já passou pelo fluxo completo de validação e publicação em produção.

13. Instalação

createdb lac_mc

psql -d lac_mc \
  -f modelo_fisico_postgresql_maquina_conhecimento_lac.sql

Em um banco já existente:

psql -d nome_do_banco \
  -v ON_ERROR_STOP=1 \
  -f modelo_fisico_postgresql_maquina_conhecimento_lac.sql

O parâmetro ON_ERROR_STOP=1 interrompe a instalação quando ocorre erro.

14. Verificação após instalação

SET search_path TO lac_mc, public;

SELECT * FROM vw_objeto_conhecimento_resumo;
SELECT * FROM vw_conformidade_objeto;
SELECT * FROM auditoria_evento ORDER BY ocorrido_em DESC;

15. Teste controlado de publicação

Antes de publicar em produção, devem ser criados:

uma representação no ambiente de produção;
uma versão vigente dessa representação;
uma validação com resultado aprovado;
um checksum;
o registro de publicação.

Sem esses elementos, a trigger rejeitará a publicação.

16. Segurança recomendada

criar usuário proprietário do schema;
separar usuários de leitura, edição, validação e publicação;
não conceder DELETE diretamente às aplicações;
usar transações nas promoções de ambiente;
proteger a tabela de auditoria contra alteração;
usar backups e testes de restauração.

17. Limites desta versão

os vocabulários de jornada, decisão, validação e papéis ainda podem ser ampliados;
o modelo não inclui autenticação de usuários;
não há sincronização automática com Memgraph;
a validação de JSON Schema permanece na camada de aplicação;
o banco ainda não importa automaticamente os HTML existentes.

18. Próximas derivações

Produzir script de teste automatizado do banco.
Produzir modelo lógico de grafo para Memgraph.
Produzir rotina de sincronização PostgreSQL–Memgraph.
Produzir importador dos documentos HTML existentes.
Produzir API para objetos, representações e metadados.
Produzir painel de conformidade e auditoria.

19. Síntese

Conclusão: o modelo físico converte a estrutura conceitual e lógica da Máquina de Conhecimento em um banco executável, capaz de preservar identidade, rastreabilidade, evolução, validação, publicação e memória operacional.

20. Estado do documento

Versão física inicial consolidada

Apta a instalação experimental em PostgreSQL 16+, antes da adoção em produção.

PostgreSQL