Skip to content

ADR-60: Domínio Engine — Arquitetura e Aggregate Roots

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)
  • enrolment tem identidade e lifecycle próprios (Ativa → Suspensa → Inativa). Armazena vigência, carga horária e vínculo com o plan. Item type EAV.
  • roadmap é criado no Primeiro Acesso, congelado permanentemente. Herda a Sequência do plan e 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.enrolment no ddd-config.yaml precisa migrar para engine.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 enrolment e 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 plan consumido 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
Navigation

Type to search…

↑↓ navigate↵ selectEsc close