Skip to content

Compilação e Plano de Estudo

Especificação técnica — como a Trilha Pedagógica vira Plano de Estudo e como o conteúdo é protegido por snapshots

Compilação e Plano de Estudo

Esta página responde a uma pergunta central: como a Trilha Pedagógica — configurada, validada e publicada — se transforma em um artefato executável que o Aluno pode consumir?

A resposta se desdobra em três atos. Primeiro, o Motor de Compilação Pedagógica processa a Trilha publicada e gera o Plano de Estudo com sua Sequência resolvida. Durante a geração de um Fluxo de Estudo, o acionamento da Unidade resolve a Versão Ativa e a configuração efetiva herdada pelo Plano do Aluno, reutilizando um Snapshot compatível ou criando outro. Esse acionamento não altera o ciclo atual. Por fim, no Primeiro Acesso do Aluno, o Plano de Estudo gera o Plano do Aluno — a instância individual, isolada e estável.

O Plano de Estudo pertence ao subdomain engine.plan e é o artefato central que conecta a camada de configuração (Trilha, domínio product) à camada de execução (Motor de Execução, domínio engine).


Ato 1 — A Trilha vira Plano de Estudo

Motor de Compilação Pedagógica

Quando a Trilha é publicada (Etapa 9 da configuração), o Motor de Compilação Pedagógica assume. Essa camada interna do backend é responsável por consolidar toda a configuração da Trilha — parâmetros, montagem dos módulos, unidades, atividades e sequência — em um Plano de Estudo estruturado e reutilizável.

O Motor de Compilação:

  1. Lê a Trilha Pedagógica validada.
  2. Resolve a Sequência do Plano de Estudo — a ordem concreta de Fluxos de Estudo, Etapas, Blocos de Estudo e Atividades-base.
  3. Incorpora as Configurações do Plano de Estudo — parâmetros herdados da Trilha já processados (Tipo de Módulo, regras de progressão, revisões, CDA, etc.).
  4. Gera uma Versão do Plano de Estudo — carimbo imutável (ID ou hash) que identifica aquela publicação específica.
  5. Persiste o Plano de Estudo como artefato consumível.

O Motor de Compilação não conduz o estudo do Aluno — ele atua antes do Primeiro Acesso. A execução individual é responsabilidade do Motor de Execução do Estudo (Passo 7).

Estrutura do Plano de Estudo

O Plano de Estudo gerado contém dois componentes principais:

Plano de Estudo (version N)
  ├── Configurações do Plano de Estudo
  │     (parâmetros resolvidos: tipo_módulo, regras de CDA,
  │      revisões, progressão, atividades habilitadas, etc.)
  └── Sequência do Plano de Estudo
        ├── Etapa 1
        │     ├── Fluxo de Estudo (Módulo 1)
        │     │     ├── Bloco CDA
        │     │     ├── Bloco de Simulado Escrito
        │     │     └── Bloco de Revisão do Módulo
        │     ├── Fluxo de Estudo (Módulo 2)
        │     │     └── ...
        │     ├── Fluxo de Estudo (Módulo 3)
        │     ├── Fluxo de Estudo (Módulo 4)
        │     └── Fluxo Revisional
        │           ├── Bloco de Revisão Geral
        │           └── Bloco de Simulado Objetivo
        ├── Etapa 2
        │     └── ...
        └── ...

A Sequência é a ordem resolvida — tudo o que a Montagem dos Fluxos definiu como arquitetura e a Montagem dos Módulos distribuiu como conteúdo, agora consolidado em uma estrutura navegável.

Versionamento

Cada Publicação da Trilha gera uma nova Versão do Plano de Estudo. Antes da primeira Matrícula, publicações substituem a versão anterior livremente. Após a primeira Matrícula:

  • A nova versão vale para novas Matrículas e para Matrículas que ainda não tiveram Primeiro Acesso.
  • Planos do Aluno já criados permanecem vinculados à versão que existia no seu Primeiro Acesso.

A Versão do Plano de Estudo é armazenada no Plano do Aluno, permitindo rastrear qual publicação da Trilha controla aquele percurso individual.

Entidades envolvidas

Entidade Tipo Subdomain Papel
study_plan entity_root engine.plan O Plano de Estudo — artefato compilado
study_plan_sequence entity_child engine.plan Sequência resolvida de Fluxos, Etapas e Blocos
study_plan_settings rule engine.plan Configurações herdadas da Trilha, já processadas
study_plan_version entity_child engine.plan Carimbo imutável de cada publicação
pedagogical_compilation_engine process_domain engine.algorithm O motor que processa a Trilha → Plano

Signals emitidos neste ato

Signal Payload Emitido por
study_plan_published study_plan_id, learning_path_id, version, sequence_hash pedagogical_compilation_engine

Ato 2 — Snapshots protegem o conteúdo

O problema

A Base de Conteúdo é viva — Conteudistas atualizam documentos Word, o sistema reprocessa Unidades, versões mudam. Mas o Aluno que já está estudando precisa de estabilidade. Se o conteúdo de uma Unidade muda depois que o Aluno já a está usando, o estudo fica inconsistente.

A solução: Snapshot de Unidade

O Snapshot de Unidade é uma captura estática dos componentes de uma Unidade, resolvida durante a geração do Fluxo de Estudo. O acionamento considera a Versão Ativa mais recente disponível e a configuração efetiva herdada pelo Plano do Aluno. As Atividades consomem o Snapshot vinculado ao acionamento, não consultam livremente a Base de Conteúdo viva.

Quando o snapshot é criado

O trigger é o Acionamento de Unidade, realizado durante a geração do Fluxo de Estudo. Ele identifica a Unidade, resolve o ponteiro para sua Versão Ativa mais recente e a configuração herdada do Plano do Aluno e calcula a identidade do Snapshot. A identidade combina o ID da Unidade, o hash do conteúdo ativo e o hash da configuração semântica normalizada. O ponteiro ativo determina a recência; o identificador de versão/publicação é preservado como proveniência, e os hashes identificam equivalência. O acionamento não altera o ciclo atual.

Se já existir Snapshot com o mesmo ID de Unidade, hash do conteúdo ativo e hash de configuração, ele é reutilizado. Essa reutilização pode ocorrer entre Alunos e entre Planos de Estudo. Se o hash do conteúdo ou o hash da configuração diferir, cria-se outro Snapshot. Snapshots já vinculados permanecem imutáveis, mesmo quando uma nova versão da Unidade é publicada.

Por exemplo, dois Planos de Estudo que selecionam todo o conteúdo da mesma Unidade podem compartilhar o Snapshot quando os hashes coincidirem. Não é necessário republicar a Trilha apenas para gerar uma cópia de Snapshot para outro Plano.

O que o snapshot contém

O snapshot contém o subconjunto selecionado pelo Plano de Estudo — apenas as seções e materiais que o Plano efetivamente usa (tópicos selecionados, questões elegíveis, etc.), conforme definido na Configuração das Unidades da Trilha. Não é necessariamente uma cópia integral do unit_content.

Cada snapshot preserva:

  • source_unit_id — FK para a Unidade de origem
  • source_version ou identificador de publicação — proveniência do unit_content ativo resolvido
  • content_hash — identidade do conteúdo ativo para equivalência/deduplicação
  • config_hash — hash da configuração semântica normalizada usada na seleção
  • snapshot_data — o conteúdo selecionado (JSON nullable)

O contexto do Plano de Estudo e do Plano do Aluno fica associado ao acionamento que usa o Snapshot; o Snapshot não pertence exclusivamente a um único Plano de Estudo.

Qual Snapshot cada matrícula usa

O acionamento é registrado por Plano do Aluno — e, como cada Matrícula tem o seu Plano do Aluno, por Matrícula. O registro (unit_activation, tabela helico_unit_activation) liga o Plano do Aluno e a Unidade ao Snapshot resolvido, com a versão/publicação de origem como proveniência. Ele é gravado uma única vez, quando o Fluxo de Estudo que traz a Unidade é gerado, e nunca é resolvido de novo: uma nova publicação da Unidade não alcança um Plano do Aluno que já foi acionado. Unidades de Fluxos ainda não gerados são acionadas quando o Fluxo correspondente nasce.

Um Aluno com mais de uma Matrícula tem um acionamento por Matrícula; os acionamentos podem apontar para o mesmo Snapshot quando a identidade coincide. Como a escolha é por Plano do Aluno, uma futura atualização oferecida ao Aluno troca o Snapshot apenas daquela Matrícula, sem alterar o Snapshot compartilhado nem as demais Matrículas.

Matrículas que já estavam em andamento quando esse registro passou a existir são migradas sob demanda: as Unidades que o Aluno já alcançou (blocos atuais ou concluídos) são acionadas sobre o Snapshot que o Plano de Estudo já tinha, preservando o que ele estudou. As demais Unidades, ainda à frente do Aluno, resolvem a Versão Ativa vigente quando são acionadas, mesmo numa matrícula antiga.

Inconsistência entre Unidade e Trilha

Pode ocorrer que, no momento do acionamento, a versão atual da Unidade não contenha mais recursos esperados pela Trilha (ex: um tópico que a Trilha selecionou foi removido por reprocessamento).

Quando isso acontecer, o sistema:

  1. Gera o snapshot utilizando a versão atual da Unidade, mesmo que alguns recursos esperados não estejam presentes.
  2. Emite o signal snapshot_inconsistency_detected com detalhes da divergência.
  3. Registra um content_conflict do tipo trail — detectado no momento do acionamento, não do reprocessamento.
  4. Notifica o Gestor Pedagógico para que a Unidade seja revisada antes de ser acionada para novos Alunos.

Esse mecanismo reutiliza o modelo de conflitos do domínio content.change (descrito em Conteúdo pedagógico, Ato 3) sem criar um workflow paralelo.

Entidades envolvidas

Entidade Tipo Subdomain Papel
unit_snapshot entity_child engine.plan Captura estática do conteúdo da Unidade
unit_activation event engine.algorithm Trigger durante a geração do Fluxo de Estudo; registra qual Snapshot cada Plano do Aluno usa

Signals emitidos neste ato

Signal Payload Emitido por
unit_snapshot_created snapshot_id, unit_id, source_version, content_hash, config_hash unit_activation — só quando o Snapshot é criado, não quando é reutilizado
snapshot_inconsistency_detected snapshot_id, unit_id, missing_resources[], conflict_id unit_activation

Ato 3 — Do Plano de Estudo ao Plano do Aluno

O ciclo individual

O Plano de Estudo é reutilizável — vários Alunos compartilham o mesmo plano. A execução individual só nasce quando três condições se encontram:

  1. Existe Matrícula no Produto.
  2. Existe um Plano de Estudo vigente para aquele Produto.
  3. Ocorre o Primeiro Acesso — o Aluno conclui o Onboarding e acessa o ambiente de estudos.

No Primeiro Acesso, o sistema cria o Plano do Aluno: uma instância individual que herda a Sequência do Plano de Estudo e a partir daí passa a registrar estado, progresso, conclusões e histórico próprios.

Plano de Estudo vs. Plano do Aluno

Aspecto Plano de Estudo Plano do Aluno
Natureza Estrutura publicada, geral e reutilizável Instância individual, isolada e acompanhada
Pertence a Estrutura do Produto Estrutura de Execução do Aluno
Criado quando Na Publicação da Trilha No Primeiro Acesso do Aluno
Afetado por republicação Sim — novas publicações geram novo Plano Não — blindado contra mudanças retroativas
Armazena Configurações + Sequência + Snapshots Cópia herdada + estado + progresso + histórico

Congelamento no Primeiro Acesso

O Plano do Aluno é congelado permanentemente no momento do Primeiro Acesso. A partir desse marco:

  • O Aluno está vinculado à Versão do Plano de Estudo que existia naquele momento.
  • Republicações da Trilha não afetam esse Aluno.
  • Mudanças na Base de Conteúdo são absorvidas pelos snapshots (Ato 2), não pelo Plano.

Essa imutabilidade protege a coerência do estudo individual sem impedir a evolução da Trilha para novos entrantes.

Migração de Plano de Estudo

Em cenários excepcionais — quando a simples republicação não resolve a necessidade — existe a Migração de Plano de Estudo: um processo que transfere Alunos de um percurso individual para outro. Esse processo:

  • É excepcional e controlado (não automático).
  • Preserva o Histórico Diagnóstico quando possível.
  • Pode resultar em novo Plano do Aluno vinculado a uma versão diferente.
  • Deve considerar o estado do Travamento Estrutural da Trilha.

Ciclo completo

Trilha Pedagógica
  └── Publicação da Trilha
        └── Motor de Compilação Pedagógica
              └── Plano de Estudo (version N)
                    ├── Configurações do Plano
                    ├── Sequência do Plano
                    └── Snapshots de Unidade (lazy, sob demanda)
                          │
                    Matrícula + Onboarding + Primeiro Acesso
                          │
                    └── Plano do Aluno (congelado)
                          ├── Herda Sequência do Plano
                          ├── Registra estado + progresso
                          └── Consome Snapshots de Unidade

Entidades envolvidas

Entidade Tipo Subdomain Papel
student_plan process engine.plan Instância individual — estado, progresso, histórico
first_access event engine.onboarding Trigger da criação do Plano do Aluno
study_plan_migration process engine.plan Transferência excepcional entre versões

Signals emitidos neste ato

Signal Payload Emitido por
student_plan_created student_plan_id, study_plan_id, version, enrolment_id first_access

Modelo de dados

Entities (EAV)

# Identifier Tipo Subdomain Gera
1 study_plan entity_root engine.plan model + service + DTO + repository
2 study_plan_sequence entity_child engine.plan model + DTO
3 study_plan_version entity_child engine.plan model + DTO
4 unit_snapshot entity_child engine.plan model + DTO
5 stage (Etapa) entity_child engine.plan model + DTO

Processos e regras

# Identifier Tipo Subdomain
6 pedagogical_compilation_engine process_domain engine.algorithm
7 study_plan_settings rule engine.plan
8 study_plan_migration process_domain engine.plan
9 unit_activation event engine.algorithm
10 student_plan process engine.plan
11 first_access event engine.onboarding

O que esta página não define


Referências

Navigation

Type to search…

↑↓ navigate↵ selectEsc close