ADR-60: Domínio Engine — Arquitetura e Aggregate Roots
Status: Aceito Data: 2026-04-23 Autor: Michael Meneses (Arquiteto)
Contexto
O domínio engine é o maior e mais complexo do sistema. Ele materializa toda a camada de execução pedagógica: desde a compilação do Plano de Estudo até a condução individual do percurso do Aluno, passando pelo acesso, onboarding e sessões de execução.
As páginas arquitetura/ (Passos 5, 6 e 7) já detalham a operação — este ADR consolida a arquitetura formal do domínio: aggregate roots, boundaries, item types, storage, events e interfaces cross-domain.
As decisões aqui formalizadas absorvem D-13, D-14 e D-35 a D-41 do BL-009 (Engine Discovery Review, 2026-03-31).
Subdomínios
| Subdomínio | Slug | Escopo funcional |
|---|---|---|
| Engine | engine |
Macrodomínio — namespace container |
| Algoritmos | engine.algorithm |
Motor de Compilação, Motor de Execução, Recomendação de Atividades |
| Plano | engine.plan |
Plano de Estudo, Plano do Aluno, Sequência, Etapas, Fluxos, Blocos, Snapshots |
| Acesso | engine.access |
Matrícula, Vigência, Expiração, Renovação, Revogação, Ciclo de Acesso |
| Onboarding | engine.onboarding |
Onboarding Geral, Complemento, Primeiro Acesso, Questionário de Perfil |
| Sessão | engine.session |
Sessão de Execução, Sessão de Questionário, Sessão de Flashcards |
Nota: metrics_consolidation_engine será migrado de engine.algorithm para o domínio metrics quando este for especificado. Engine emite eventos; Metrics consome e consolida (decisão A-05).
Aggregate Roots
Item types (EAV)
| item_type | Conceito | Natureza | Storage |
|---|---|---|---|
enrolment |
Matrícula | AR de vínculo pedagógico | EAV (helico_items) |
roadmap |
Plano do Aluno | AR instanciado (execução) | EAV (helico_items) |
Nota sobre plan: O Plano de Estudo (study_plan nos terms) é o mesmo artefato definido como item_type plan no ADR-50 (domínio product). Engine consome o plan — não cria item_type próprio. O plan é gerado pelo product (via compilação) e consumido pelo engine (via instanciação).
Relação entre aggregate roots
plan (Plano de Estudo — EAV, compilado do product)
│
├── enrolment (Matrícula — EAV, vínculo pedagógico)
│ └── [Onboarding → Primeiro Acesso]
│
└── roadmap (Plano do Aluno — EAV, instanciado no Primeiro Acesso)
├── study_flow (N por plano)
│ └── study_block (N por fluxo)
│ └── cda_cycle (1 por bloco CDA)
│ └── segment (2 por CDA: DI + SVD)
├── stage (N por plano)
└── execution_session (N por plano)enrolmenttem identidade e lifecycle próprios (Ativa → Suspensa → Inativa). Armazena vigência, carga horária e vínculo com oplan. Item type EAV.roadmapé criado no Primeiro Acesso, congelado permanentemente. Herda a Sequência doplane registra estado, progresso e ponteiros de execução via metas. Item type EAV — 1 registro por Aluno/Matrícula, volume gerenciável.
Nota sobre DI/SVD e classificação: Diagnóstico Inicial e Simulado de Verificação de Desempenho são tratados como atividades normais — seus resultados (respostas, classificações de nível) vivem no domínio activity, em tabelas genéricas de atividades/respostas e resultados. Engine orquestra o CDA (cda_cycle + segment) e consome os resultados via interface cross-domain.
Processos sem persistência própria
| Identifier | Conceito | Subdomain | Papel |
|---|---|---|---|
student_cycle |
Ciclo do Aluno | engine.onboarding | Orquestrador: Matrícula → Onboarding → Plano → Conclusão. Estado derivável dos componentes. |
Entities auxiliares (EAV, não são ARs)
| item_type | Conceito | Subdomain | Parent |
|---|---|---|---|
onboarding |
Onboarding | engine.onboarding | enrolment |
profile_questionnaire |
Questionário de Perfil | engine.onboarding | enrolment |
habit_tracker |
Rastreador de Hábitos | engine.onboarding | — |
Storage
EAV (helico_items — todo o domínio engine)
Todas as entities do engine vivem no EAV. Entities estruturais (study_flow, study_block, etc.) são filhos hierárquicos do roadmap via parent. O volume transacional real (respostas, resultados) vive no domínio activity em tabelas dedicadas.
| item_type | Conceito | Natureza |
|---|---|---|
enrolment |
Matrícula | AR — vínculo pedagógico |
roadmap |
Plano do Aluno | AR — instância individual |
study_flow |
Fluxo de Estudo | Filho do roadmap — N por plano |
study_block |
Bloco de Estudo | Filho do study_flow — N por fluxo |
stage |
Etapa | Filho do roadmap — N por plano |
cda_cycle |
Ciclo CDA | Filho do study_block — 1 por bloco CDA |
segment |
Segmento (DI/SVD) | Filho do cda_cycle — 2 por CDA |
execution_session |
Sessão de Execução | Filho do roadmap — N por plano |
onboarding |
Onboarding | Auxiliar — filho do enrolment |
profile_questionnaire |
Questionário de Perfil | Auxiliar — filho do enrolment |
habit_tracker |
Rastreador de Hábitos | Auxiliar — independente |
Decisão de storage: Todo o domínio engine opera via EAV. A hierarquia parent do EAV modela naturalmente a árvore roadmap → study_flow → study_block → cda_cycle → segment. O dado transacional de alto volume (respostas, resultados, classificações) vive nos domínios activity e metrics em tabelas dedicadas.
Engine não cria tabelas próprias. As 4 tabelas EAV do MIDDAG (helico_items, helico_itemmeta, helico_item_revision, helico_item_revision_meta) são suficientes.
Invariantes dos Aggregate Roots (absorve D-35)
enrolment
- Status segue máquina de estados (Ativa → Suspensa → Inativa)
- Vigência de Acesso com datas válidas (início < término)
- Vínculo obrigatório com Plano de Estudo (
plan) e Aluno - Carga Horária de Referência obrigatória para Módulos Dinâmicos
- Renovação respeita Política de Renovação do Produto
- Revogação respeita Política de Revogação do Produto
roadmap (Plano do Aluno)
- Congelado permanentemente no Primeiro Acesso
- Status coerente com estado dos Fluxos e Blocos
- Transições de status válidas (ver enums)
- Critério de Conclusão Pedagógica avaliado contra estado interno
- Causa de Bloqueio registrada quando status = bloqueado
- Lazy loading: Blocos e Sessões carregados sob demanda
Domain Events (absorve D-36)
Events emitidos pelo engine
| Evento | Trigger | Consumidores |
|---|---|---|
student_plan_created |
Primeiro Acesso após Onboarding | Motor de Execução (ativa primeiro Bloco) |
student_plan_status_changed |
Transição de status | Consolidação (metrics), Notificações, Suporte |
student_plan_concluded |
Critério de Conclusão satisfeito | Métricas (relatório final), Notificações |
study_block_activated |
Motor ativa próximo Bloco | Roteiro (atualiza visão), Atividades (prepara execução) |
study_block_completed |
Regra de Conclusão satisfeita | Motor (avalia progressão), Métricas |
study_flow_completed |
Último Bloco do Fluxo concluído | Motor (avalia próximo Fluxo), Métricas |
stage_completed |
4 Módulos concluídos | Motor (insere Fluxo Revisional) |
unit_activated |
Bloco ativado referencia Unidade inédita | Conteúdo (pré-carregamento), Métricas |
unit_snapshot_created |
Acionamento na geração do Fluxo de Estudo; novo Snapshot quando conteúdo ativo/configuração diferem | Sistema (deduplicação por Unidade + hash de conteúdo ativo + hash de configuração) |
cda_cycle_started |
Bloco CDA ativado | Motor (orquestra DI) |
level_classified |
DI ou SVD respondido e avaliado | Recomendação de Atividades, Segmento SVD |
cda_cycle_completed |
Ambos Segmentos concluídos/dispensados | Motor (conclui Bloco CDA) |
onboarding_completed |
Todas etapas do Onboarding finalizadas | Motor (instancia Plano do Aluno) |
progress_rebalanced |
Dispensa aplicada ou alteração de conteúdo | Métricas (Roteiro de Estudos) |
automatic_termination |
Scheduled task detecta expiração | Notificações, Suporte |
execution_session_completed |
Aluno finaliza Sessão | Motor (Regra de Conclusão), Métricas |
study_plan_published |
Motor de Compilação conclui | Product (vincular), Engine (disponibilizar) |
enrolment_created |
Provisionamento concluído | Motor (preparar instanciação), Onboarding |
enrolment_suspended |
Pendência reversível | Motor (pausar execução) |
enrolment_inactivated |
Expiração/cancelamento/revogação | Motor (encerrar Plano), Moodle (revogar inscrição) |
access_renewed |
Evento de renovação comercial | Motor (reativar ou criar Plano) |
Events consumidos pelo engine
| Evento | Produtor | Efeito |
|---|---|---|
trail_published |
Product | Motor de Compilação gera novo Plano de Estudo |
trail_republished |
Product | Migração de Plano para Matrículas sem 1º Acesso |
activity_completed |
Activity | Motor avalia progressão, Regra de Conclusão |
order_received |
Webhook externo | Disparar Concessão de Acesso |
commercial_sync_event |
Webhook externo | Renovação, Revogação, Cancelamento |
Regras de Negócio (absorve D-37, D-13, D-14)
| # | Regra | Tipo | Escopo |
|---|---|---|---|
| 1 | Regra de Progressão: Aluno avança apenas com pré-requisitos satisfeitos | pedagógica | trilha |
| 2 | Regra de Conclusão: define quando Bloco/Fluxo/Atividade é concluído | pedagógica | unidade |
| 3 | Regra de Disponibilidade: controla quando Blocos/Módulos ficam acessíveis | temporal | unidade |
| 4 | Pré-requisito de Unidade: condiciona sequência entre Unidades | pedagógica | unidade |
| 5 | Critério de Conclusão Pedagógica: define quando Plano é concluído | pedagógica | trilha |
| 6 | Causa de Bloqueio: categoriza motivos de indisponibilidade | operacional | aluno |
| 7 | Dispensa no CDA: Nível alto permite pular Atividades básicas; Denominador Dinâmico ajustado | pedagógica | unidade |
| 8 | Denominador Dinâmico: recalcula total de Atividades quando Dispensas mudam escopo | funcional | aluno |
| 9 | Modo Somente Leitura: consulta ao Roteiro/Caderno quando Plano bloqueado | operacional | aluno |
| 10 | Sequenciamento DI → SVD: DI sempre precede SVD dentro do Bloco CDA | pedagógica | unidade |
| 11 | CDA: todas as atividades obrigatórias, exceto quando Dispensa é aplicada (absorve D-13) | pedagógica | unidade |
| 12 | Rebalanceamento: recalcula módulos futuros; módulos concluídos não mudam (absorve D-14) | funcional | aluno |
| 13 | Cada publicação da Trilha gera nova versão do Plano de Estudo, mesmo sem mudança de conteúdo | funcional | trilha |
| 14 | Plano do Aluno congelado no Primeiro Acesso — republicações da Trilha não afetam Planos existentes | consistência | aluno |
| 15 | Acionamento na geração do Fluxo de Estudo; Snapshot reutilizado entre Planos quando Unidade, hash de conteúdo ativo e hash de configuração coincidem | funcional | plano |
| 16 | Reinício total: mudança de produto reinicia Plano + Onboarding, sem migração automática de progresso | operacional | aluno |
Services (absorve D-39)
| Service | Responsabilidade | Subdomain |
|---|---|---|
| CompilationEngine | Trilha publicada → Plano de Estudo compilado (Sequência, Fluxos, Blocos) | engine.algorithm |
| PlanInstantiationService | Plano de Estudo + Matrícula → Plano do Aluno individual (Primeiro Acesso) | engine.plan |
| ExecutionEngine | Progressão: transições de status, regras, ativação de Blocos | engine.algorithm |
| CdaOrchestrator | Ciclo CDA: classificação de Nível, Segmentos DI/SVD, Dispensa | engine.algorithm |
| ProgressRebalancer | Denominador Dinâmico recalculado após Dispensas/alterações | engine.algorithm |
| ActivityRecommendationService | Publica critérios de recomendação (nível, dispensas, atividades habilitadas) | engine.algorithm |
| OnboardingOrchestrator | Fluxo de Onboarding (Geral + Complemento) + Primeiro Acesso | engine.onboarding |
| AutomaticTerminationService | Scheduled task: vigências expiradas → Planos bloqueados | engine.access |
| AccessGrantService | Resolve elegibilidade, verifica Modo de Acesso, delega ao Provisioning | engine.access |
| EnrolmentProvisioningService | Cria Matrícula, define Vigência, inscreve no Moodle, vincula Plano de Estudo | engine.access |
| EnrolmentLifecycleService | Transições de status (ativar, suspender, inativar), aplica Políticas | engine.access |
| AccessRenewalService | Processa renovação conforme Política (extensão ou nova matrícula) | engine.access |
| StudyPlanMigrationService | Identifica Matrículas afetadas por republicação, coordena migração | engine.plan |
Nota: MetricsConsolidationEngine migra para domínio metrics (decisão A-05). Engine publica eventos via ExecutionEventContract; Metrics consome e consolida.
Interfaces Cross-Domain (absorve D-40)
| Domínio externo | Direção | Contrato | Dados trocados |
|---|---|---|---|
| Product | consome | StudyPlanProviderContract | Plano de Estudo, Sequência, Configurações, Trilha |
| Activity | consome | ActivityExecutionContract | Resultado de execução, status, Formato |
| Activity | publica | BlockActivationContract | Bloco ativado + critérios de recomendação |
| Content | consome | ContentSnapshotContract | Snapshot de Unidade, Disciplina (para acionamento) |
| Metrics | publica | ExecutionEventContract | Eventos de execução, Resultados Elegíveis |
| Metrics | consome | MetricsQueryContract | Métricas consolidadas, Progresso (para tela do Aluno) |
| Moodle core | consome/publica | MoodleEnrolmentAPI | Inscrição via Enrolment API nativa |
| Sistema externo | consome | OrderWebhookContract | Pedido via webhook (compra, cancelamento, renovação) |
Fronteira ActivityRecommendation (decisão A-04): Engine define critérios (nível, dispensas, atividades habilitadas) via BlockActivationContract. Activity resolve quais atividades concretas montar e executar.
Decisões abertas registradas (absorve D-41)
| # | Item | Tipo | Status |
|---|---|---|---|
| 1 | Roadmap como AR com lazy loading | decisão validada | Confirmado (D-41.1). Tabela helico_plan; Blocos/Sessões carregados sob demanda |
| 2 | DI/SVD como atividades normais | decisão validada | Resultados/classificações vivem no domínio activity. Engine orquestra CDA, não armazena resultados |
| 3 | HabitTracker em engine.onboarding (EAV) | decisão validada | Confirmado (A-02). Ciclo independente do Plano; interface cross-domain se necessário |
| 4 | Sessão de Execução hierárquica (sessão agrupa N registros) | decisão validada | Confirmado (A-03). helico_execution_session com registros filhos por atividade |
| 5 | MetricsConsolidationEngine migra para metrics | decisão validada | Confirmado (A-05). Engine emite; Metrics consolida |
| 6 | Compilação: nova versão sempre, mesmo sem mudança | decisão validada | Confirmado (A-06). Simplicidade e rastreabilidade |
| 7 | StudentCycle como processo orquestrador, sem persistência | decisão validada | Confirmado (A-07). Estado derivável dos componentes |
| 8 | Granularidade de persistência dos Eventos de Execução | decisão futura | Definir schema de helico_execution_session nos contracts |
| 9 | Fronteira Recomendação de Atividades | decisão validada | Confirmado (A-04). Engine publica critérios; Activity executa |
| 10 | Schema do webhook de Pedido | decisão futura | Formato do contrato com sistema de pagamento externo (herdado do ADR-50 #7) |
Consequências
- Domínio engine especificado com 2 ARs em EAV (
enrolment,roadmap) - Nomes de AR simplificados:
enrolment,roadmap— padrão palavra única como product/trail/plan - DI/SVD tratados como atividades normais — resultados no domínio activity, engine só orquestra
- Separação clara: EAV para configuração, tabela própria para runtime
plan(Plano de Estudo) permanece no product — engine consome sem duplicação- MetricsConsolidationEngine migra para metrics — boundary limpa
- StudentCycle como processo, não entity — sem overhead de persistência
- 21 domain events formalizados (emitidos + consumidos)
- 16 regras de negócio consolidadas
- 13 services com responsabilidades e subdomain atribuídos
- 8 interfaces cross-domain com contratos nomeados
- Engine 100% EAV — sem tabelas dedicadas. Dados transacionais vivem em activity/metrics.
product.enrolmentno ddd-config.yaml precisa migrar paraengine.access- Schema do webhook externo não definido
ADRs relacionados
- ADR-02 — Ciclo de vida pedagógico em 4 fases (fundação)
- ADR-04 — Eventos para desacoplamento (events deste ADR seguem o padrão)
- ADR-10 — Persistência EAV (storage do
enrolmente entities auxiliares) - ADR-11 — Versionamento por snapshot (
unit_snapshot,study_plan_version) - ADR-21 — Contratos JSON para entities (contracts futuros do engine)
- ADR-22 — Convenções de domínio (subdomains engine.*)
- ADR-40 — Configuração por preset e invariantes (config_json governa o motor)
- ADR-50 — Domínio Product (gera o
planconsumido pelo engine) - REF-50-A — Mapeamento de enums da Sequence (flow_type, block_type, activities)
- REF-60-A — Mapeamento de enums do Engine (status, causas, ciclos)
Histórico
| Data | Evento |
|---|---|
| 2026-04-23 | Criado — consolida decisões da sessão 15 + absorve BL-009 D-13, D-14, D-35..D-41 |