title: Conceito: Revision description: A Revision como snapshot imutável e histórico estrutural do estado de um Item.

Revision¶

A Revision representa um retrato fiel e imutável de um Item em um ponto específico da linha do tempo. Enquanto o Item foca no "agora", a Revision foca no "como estava".

O que é¶

Uma Revision é um snapshot estruturado que preserva todos os dados de um Item (colunas estruturais e metadados) no momento em que uma alteração significativa foi persistida. Ela não é um log de texto, mas sim uma cópia dos dados que permite reconstruir o estado exato do objeto no passado.

Toda Revision pertence obrigatoriamente a um Item e possui um número sequencial (revisionnumber) que identifica sua ordem cronológica dentro daquele item.

Por que existe¶

Em sistemas complexos de gestão, saber o estado atual não é suficiente. É necessário: 1. Auditoria de Valores: Comparar o que mudou entre duas versões. 2. Recuperação de Desastres: Restaurar um Item para um estado anterior estável. 3. Fidelidade Histórica: Garantir que relatórios de matrículas de "6 meses atrás" reflitam os dados reais de 6 meses atrás, mesmo que o Item tenha sido alterado desde então.

A escolha de separar Revision de Item permite que a tabela de Items permaneça leve e performática para operações do dia a dia, enquanto o peso do histórico é movido para a família de tabelas de revisão.

Como se relaciona com outros conceitos¶

Revision vs Item: O Item é a fonte de verdade operacional (mutável). A Revision é a fonte de verdade histórica (imutável).
Revision vs Audit: A Revision responde "Como o dado estava?" (Snapshot). O Audit responde "O que aconteceu e quem fez?" (Fato). Embora relacionados, um Audit pode apontar para uma Revision para fornecer contexto.
Revision vs Signal: A criação de uma Revision é geralmente uma consequência de um Signal de alteração (ex: item_updated).

Decisões de design¶

Snapshots, não Diffs: Diferente do Audit (que foca no que mudou), a Revision armazena o estado completo. Isso facilita a reconstrução imediata do objeto sem precisar processar uma cadeia de alterações.
Imutabilidade Estrita: Uma vez criada, uma Revision nunca é editada ou removida (exceto por políticas de expurgo/GDPR). Isso garante a integridade da trilha histórica.
Schema Espelhado: A estrutura de middag_item_revision e middag_item_revision_meta espelha a estrutura do Item, facilitando o uso dos mesmos Mappers e Entities para ler dados históricos.

O que não é¶

Não é um Log de Erros: Revisions são para dados de sucesso persistidos, não para rastrear falhas de software.
Não é a Fonte Próxima: Services e Controllers devem sempre consumir o Item para operações de tempo real. Consumir Revisions é um caso de uso específico para relatórios, dashboards de histórico ou rollback.
Não é Obrigatória: Nem toda alteração de Item precisa gerar uma Revision. O framework permite configurar políticas para decidir quando um "salvamento" é importante o suficiente para virar um snapshot histórico.

Perspectiva para builders de extensions¶

Como desenvolvedor de extension, você raramente interagirá com a lógica de criação de revisões. O framework, através de Decorators no item_repository, detecta alterações e cria a Revision automaticamente conforme a política definida para o seu TYPE.

Se precisar exibir um histórico de alterações para o usuário, você utilizará o revision_repository para listar os snapshots vinculados ao ID do Item.

Exemplo ilustrativo¶

Visualizando a linhagem de um Item:

ID	Item (Estado Atual)	Revision (Histórico)	Data
45	Status: Active	-	Agora
45	-	Revision 2 (Status: Pending)	Ontem
45	-	Revision 1 (Status: Draft)	Anteontem

No código, para recuperar a versão de "Ontem":

$revision = $revision_repository->find_by_item_and_number(45, 2);
$old_item_state = $revision->get_payload(); // Retorna a Entity com dados da época