Skip to content

ADR-11: Versionamento por snapshot imutável

ADR-11: Versionamento por snapshot imutável

Status: Aceito Data: 2026-04-17

Contexto

A Trilha Pedagógica da HÉLICO é configurável e pode ser alterada a qualquer momento pelo Admin. No entanto, Alunos ativos trabalham com um Plano do Aluno derivado de uma versão específica da Trilha. Sem versionamento explícito, alterações na Trilha poderiam afetar silenciosamente Alunos em execução, comprometendo a integridade pedagógica e dificultando rastreabilidade.

O ciclo de vida em 4 fases (ADR-02) exige artefatos estáticos entre as fases de Compilação e Execução.

Decisão

Adotar estratégia de versionamento por snapshot imutável para os artefatos pedagógicos compilados.

Plano de Estudo

  • É o artefato estático gerado pelo CompilationEngine a partir da configuração da Trilha (Fase 2 do ADR-02).
  • Cada compilação gera um novo Plano de Estudo com status ativo.
  • O Plano de Estudo anterior (se existir) recebe status arquivado, mas mantém vínculo com os Alunos que já o utilizam.
  • Um Plano de Estudo nunca é modificado após a compilação — é imutável.

Plano do Aluno

  • É uma cópia executável do Plano de Estudo ativo no momento da instanciação (Fase 3 do ADR-02).
  • Contém o estado de execução do Aluno: progresso, posição atual, métricas acumuladas.
  • Vinculado ao Plano de Estudo de origem para rastreabilidade.

Snapshots de Unidade

  • O Snapshot de Unidade é resolvido durante a geração do Fluxo de Estudo, combinando a Versão Ativa da Unidade com a configuração efetiva herdada pelo Plano do Aluno.
  • O sistema reutiliza Snapshot compatível por ID da Unidade + hash do conteúdo ativo + hash semântico normalizado da configuração, inclusive entre Planos de Estudo; qualquer divergência gera Snapshot distinto. A versão ou o identificador de publicação é preservado apenas como proveniência.
  • Alterações no conteúdo-fonte não modificam Snapshots já vinculados a acionamentos. O acionamento ocorre na geração do Fluxo de Estudo e não altera o ciclo atual.

Fluxo de republicação

  1. Admin altera configuração da Trilha → Fase 1 (Configuração)
  2. Publicação dispara compilação → Fase 2 (Compilação)
  3. Novo Plano de Estudo gerado (status ativo), anterior arquivado
  4. Alunos existentes continuam com seu Plano do Aluno original
  5. Novos alunos recebem Plano do Aluno baseado no Plano de Estudo mais recente

Consequências

  • Alunos ativos não são afetados por republicação da Trilha.
  • Novos alunos sempre recebem a versão mais recente.
  • Rastreabilidade completa: Configuração → Plano de Estudo → Plano do Aluno.
  • Snapshots imutáveis permitem auditoria e comparação entre versões.
  • Custo de armazenamento: múltiplas versões de Planos e snapshots coexistem.
  • Possibilidade futura de migração controlada de Alunos entre versões de Plano.

ADRs relacionados

  • ADR-02 — Ciclo de vida em 4 fases — detalha a Fase 2 e Fase 3.
  • ADR-10 — Persistência EAV e critérios de uso — define a infraestrutura de persistência.
  • ADR-04 — Eventos para minimizar acoplamento — transições de versão disparam eventos (TrilhaPublicada, PlanoCompilado).

Histórico

Renumerado de ADR-109.

Refinamento registrado em 2026-10-13: a reutilização de Snapshots é determinada pela equivalência da Unidade, do hash do conteúdo ativo e do hash da configuração, e o acionamento passa a ocorrer durante a geração do Fluxo de Estudo. A regra detalhada vigente está alinhada ao termo canônico Snapshot de Unidade.

Decisão (2026-10-16): itens aprovados são aplicados ao Snapshot

O epic moodle-local_helico#118 (relatório de alterações do Gestor) passa a aplicar a aprovação de um item (tópico, questão, informações gerais, vídeo) pelo Gestor Pedagógico ao conteúdo base de todos os Snapshots da Unidade que contêm o item. Isso muda a regra acima de imutabilidade. O contrato vigente é:

  • Um Snapshot só muda por aplicação de item aprovado, feita pelo content_item_application_service, uma chave por vez, sempre auditada (helico_content_item_application: Snapshot, item, hash anterior e novo, desfecho, autor, data). Nenhum outro caminho altera o conteúdo de um Snapshot; a exceção anterior, a narração de áudio e as relações atualizadas no lugar, continua como está.
  • O que o Snapshot preserva: o id inteiro que ele deu a cada item, o recorte de escopo com que foi criado, o content_hash e o config_hash de criação e as ativações dos Alunos. Questão ou tópico removido no Word permanece.
  • content_hash é proveniência, não identidade do conteúdo atual. is_consistent aceita o hash de criação ou o hash do conteúdo que o Snapshot carrega depois das aplicações (este só para Snapshot sem recorte). A ativação reaproveita o Snapshot cujo conteúdo, depois das aplicações, já é o conteúdo vivo, sem criar duplicata para Aluno novo.
  • Quem estuda de um Snapshot recebe a mudança de uma vez, inclusive quem já fez simulado. Por isso a revisão do simulado lê tudo do Snapshot ativo e a nota só é recalculada quando o gabarito muda (ver 02-content.md).
  • O Caderno Online do Aluno não é reescrito pela aprovação: o artefato dele só recebe o texto novo se ele aceitar a oferta, e a versão anterior é preservada.

Ainda em aberto: uma ação de reverter aprovação (o hash anterior fica na auditoria, mas não há como desfazer pela interface) e a propagação do recálculo de nota ao gradebook do Moodle.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close