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:
- Lê a Trilha Pedagógica validada.
- Resolve a Sequência do Plano de Estudo — a ordem concreta de Fluxos de Estudo, Etapas, Blocos de Estudo e Atividades-base.
- 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.).
- Gera uma Versão do Plano de Estudo — carimbo imutável (ID ou hash) que identifica aquela publicação específica.
- 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 origemsource_versionou identificador de publicação — proveniência dounit_contentativo resolvidocontent_hash— identidade do conteúdo ativo para equivalência/deduplicaçãoconfig_hash— hash da configuração semântica normalizada usada na seleçãosnapshot_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:
- Gera o snapshot utilizando a versão atual da Unidade, mesmo que alguns recursos esperados não estejam presentes.
- Emite o signal
snapshot_inconsistency_detectedcom detalhes da divergência. - Registra um
content_conflictdo tipotrail— detectado no momento do acionamento, não do reprocessamento. - 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:
- Existe Matrícula no Produto.
- Existe um Plano de Estudo vigente para aquele Produto.
- 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 UnidadeEntidades 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
- Como Matrícula, Vigência e Onboarding funcionam → Aluno e Matrícula (Passo 6)
- Como o Motor de Execução conduz blocos, fluxos e CDA → Motor de Execução (Passo 7)
- Como alterações na Base de Conteúdo geram conflitos → Conteúdo pedagógico, Ato 3
Referências
- Produto e Trilha Pedagógica — como a Trilha é configurada e publicada (Passo 4)
- Conteúdo pedagógico — como a Base de Conteúdo é criada e evolui (Passos 1–3)
- Execução do Aluno (Metodologia) — fundamentos conceituais do percurso individual
- Terms: engine — vocabulário canônico do motor pedagógico