Skip to content

ADR-80: Domínio Activity — Arquitetura e Aggregate Roots

ADR-80: Domínio Activity — Arquitetura e Aggregate Roots

Status: Aceito Data: 2026-04-24 Autor: Michael Meneses (Arquiteto)

Contexto

O domínio activity é responsável por registrar toda a interação do Aluno com atividades pedagógicas: respostas a questionários, submissões de simulados escritos, práticas com flashcards e artefatos do Caderno Online. O domínio não controla quando uma atividade é executada (isso é responsabilidade do engine via Motor de Execução) — ele controla o quê o Aluno respondeu e qual resultado foi computado.

A página arquitetura/07-activity.md (Passo 8) já detalha o catálogo de atividades. Este ADR consolida a arquitetura formal do domínio: aggregate roots, storage, events e interfaces.

As decisões da sessão 15 (DI/SVD como atividades normais) tornaram este domínio a fonte primária de dados de execução que engine e metrics consomem. As decisões aqui formalizadas absorvem D-17, D-18 e D-24 a D-27 do BL-009 (Activity Discovery Review, 2026-03-31).


Subdomínios

Subdomínio Slug Escopo funcional
Activity activity Namespace container
Avaliação activity.assessment Questionários VF, Objetivo, Escrito — atividades avaliativas
Produtivo activity.productive Estudo Dirigido, Caderno Online — atividades que geram artefatos
Prática activity.practice Flashcards — atividades de retenção

Aggregate Roots

AR Conceito Tabela Natureza
response Respostas e submissões helico_response AR de alto volume, N por sessão
result Resultados computados helico_result AR de alto volume, 1 por atividade
notebook Artefato do Caderno Online helico_notebook AR persistente com versionamento

Relação entre aggregate roots

execution_session (engine — helico_execution_session)
  │
  ├── response (N por sessão — respostas, submissões, práticas)
  │     └── result (1 por atividade — score, status, elegibilidade)
  │
  └── notebook (1 por aluno/unidade — artefato persistente, versionado)
  • response registra a interação bruta: respostas de VF/Objetivo, submissões de Escrito (upload), práticas de Flashcards. Cada response referencia a execution_session do engine. Alto volume — tabela própria.
  • result é o resultado computado de uma atividade: score (NR), status de conclusão, elegibilidade para métricas. Consumido pelo domínio metrics para gerar classificações. 1 por atividade concluída.
  • notebook é o artefato do Caderno Online: conteúdo produzido ou recebido pelo Aluno, com versionamento e status de sincronia. Lifecycle independente das sessões. Tabela própria por ter versionamento e sync status.

Fronteira com engine

A sessão de execução (helico_execution_session) permanece no engine (decisão A-13). Activity faz FK para session_id. Engine controla lifecycle da sessão; Activity controla conteúdo.


Storage

Tabelas próprias

Tabela Entidade Justificativa
helico_response Respostas e submissões Alto volume; N por sessão; índice por session_id, type, student_id
helico_result Resultados computados Alto volume; 1 por atividade; índice por student_id, plan_id, unit_id
helico_notebook Artefato do Caderno Online 1 por aluno/unidade; versionamento + sync status; índice por student_id

Sem EAV

Activity não define item_types EAV. Todas as entities são de alto volume ou com lifecycle especializado.


Invariantes dos Aggregate Roots (absorve D-24)

response

  • Só existe se sessão iniciada (FK obrigatório para helico_execution_session)
  • Sessão finalizada não aceita novas respostas
  • Submissão rejeitada permite reenvio (novo response, não edição)
  • Tipo de response determina schema de dados (VF, Objetivo, Escrito, Flashcard)

result

  • 1 por atividade concluída — imutável após criação
  • Score (NR) obrigatório para atividades avaliativas
  • Apenas Resultados Elegíveis são marcados para consumo por metrics
  • Elegibilidade determinada por: sessão completa, não-treino, não-cancelada

notebook

  • 1 por aluno/unidade — identidade estável
  • Preserva versões anteriores ao ser editado (versionamento incremental)
  • Status de sincronia atualizado quando conteúdo de origem muda (synchronized → desynchronized)
  • Pode ser auto-populado (conteúdo HÉLICO) ou livre (produção do Aluno)
  • Resumo produzido pelo Aluno: se recusar, auto-populado com conteúdo HÉLICO (decisão D-18)

Domain Events (absorve D-25)

Events emitidos pelo activity

Evento Trigger Consumidores
activity_completed Regra de Conclusão satisfeita Engine (progressão), Metrics (consolidação)
questionnaire_session_completed Aluno finaliza ou tempo esgota Engine (status do bloco), Metrics (score)
flashcard_session_completed Aluno completa ou encerra sessão Engine (status do bloco), Metrics (score)
written_exam_submitted Aluno envia submissão Sistema (processamento), Tutoria (atribuição)
written_exam_submission_processed Sistema conclui processamento Tutoria (submissão disponível para correção)
written_exam_corrected Tutor conclui correção Engine (status), Aluno (devolutiva)
written_exam_submission_rejected Sistema detecta problema no upload Aluno (reenvio disponível)
notebook_artifact_created Aluno submete estudo dirigido Engine (status do bloco)
notebook_artifact_desynchronized Conteúdo de origem alterado Aluno (notificação), Sistema (log)

Events consumidos pelo activity

Evento Produtor Efeito
study_block_activated Engine Prepara atividades do bloco para execução
unit_activated Engine Pré-carrega conteúdo para notebook/estudo dirigido

Regras de Negócio (absorve D-26, D-17, D-18)

# Regra Tipo Escopo
1 Atividade só inicia se status “pendente” e Bloco ativo funcional processo
2 Sessão finalizada não aceita novas respostas consistência processo
3 Simulado Escrito deve ter Template associado funcional trilha
4 Tipos de Simulado Escrito habilitados dependem dos Parâmetros da Trilha pedagógica trilha
5 Submissão rejeitada permite reenvio funcional processo
6 Correção deve usar Folha Espelho como referência pedagógica processo
7 Atividade Dispensada não exige execução pedagógica aluno
8 Regra de Conclusão determina quando Atividade está concluída pedagógica processo
9 Artefato do Caderno preserva versões anteriores ao ser editado consistência aluno
10 Artefato fica “desatualizado” quando Tópico de origem é alterado consistência aluno
11 Encerramento automático por tempo em sessões de questionário e simulado escrito temporal trilha
12 Correção de Simulado Escrito: configurável via written_exam_correction_mode no config_json da Trilha. Com Tutoria habilitada: modos manual e assistida_ia disponíveis. Sem Tutoria: apenas automatica (Espelho de Resposta) é permitido. (absorve D-17, D-51 §9.6) pedagógica trilha
13 Caderno Online: auto-populado + livre; Resumo não é auto-populado (absorve D-18) pedagógica aluno

Services

Service Responsabilidade Subdomain
QuestionnaireService Monta questionário (VF/Objetivo), registra respostas, calcula score (NR) activity.assessment
WrittenExamService Gerencia submissão, processamento, correção e devolutiva activity.assessment
FlashcardPracticeService Monta sessão de flashcards, registra práticas, calcula resultado activity.practice
DirectedStudyService Orquestra Resumo, Leitura e Leitura de Reforço com Caderno Online activity.productive
NotebookService CRUD de artefatos, versionamento, auto-população, detecção de dessincronia activity.productive
ActivityCompletionService Avalia Regra de Conclusão e emite activity_completed activity

Interfaces Cross-Domain

Domínio externo Direção Contrato Dados trocados
Engine consome BlockActivationContract Bloco ativado + critérios de recomendação (nível, dispensas)
Engine publica ActivityExecutionContract Resultado de execução, status, tipo
Content consome ContentSnapshotContract Conteúdo da Unidade para notebook/estudo dirigido
Metrics publica ActivityResultContract Scores (NR), elegibilidade, tipo de atividade
Product consome TrailActivityConfigContract Formatos habilitados, Templates de Escrito, correção mode

Decisões abertas registradas (absorve D-24..D-27)

# Item Tipo Status
1 Modelo de 2+1 tabelas (response + result + notebook) decisão validada Confirmado (A-12). 3 ARs com palavra única
2 Sessão de execução permanece no engine decisão validada Confirmado (A-13). Activity faz FK para session_id
3 Correção de Simulado Escrito configurável (manual/IA/auto) decisão validada Absorvido de D-17 + D-51 §9.6. Constraint: Tutoria habilitada → manual/assistida_ia; Tutoria desabilitada → só automatica
4 Caderno Online: auto-populado + livre decisão validada Absorvido de D-18. Resumo do Aluno não é auto-populado
5 Contrato pedagógico detalhado por atividade decisão futura D-52 (P1): 8 aspectos por atividade — tratar antes de implementar
6 Escopo do Simulado Escrito por subtipo decisão futura D-52 #4: critérios por subtipo (dissertativa, petição, etc.)

Consequências

  • Domínio activity especificado com 3 ARs em tabela própria (response, result, notebook)
  • Nomes simplificados: palavra única, padrão consistente com todos os domínios
  • DI/SVD tratados como atividades normais — sem caso especial
  • Separação clara: engine controla sessão, activity controla conteúdo e resultado
  • 9 domain events formalizados
  • 13 regras de negócio consolidadas (incluindo D-17, D-18)
  • 6 services com responsabilidades e subdomain atribuídos
  • 5 interfaces cross-domain com contratos nomeados
  • 3 tabelas dedicadas a criar no install.xml quando implementação iniciar
  • Contratos pedagógicos por atividade (D-52) pendentes — prerequisito para implementação
  • Correção por IA ainda sem spec (D-17 registra a possibilidade, não o comportamento)

ADRs relacionados

  • ADR-03 — Abstração seletiva e hierarquia de atividades (Atividade-base → Atividade → Formato)
  • ADR-04 — Eventos para desacoplamento (activity_completed segue o padrão)
  • ADR-40 — Configuração por preset (formatos habilitados, Templates, correção)
  • ADR-50 — Domínio Product (configura atividades na Trilha)
  • ADR-60 — Domínio Engine (orquestra blocos, consome resultados)
  • ADR-70 — Domínio Metrics (consome resultados para classificação)
  • REF-80-A — Mapeamento de enums do Activity

Histórico

Data Evento
2026-04-24 Criado — consolida decisões da sessão 15 + absorve BL-009 D-17, D-18, D-24..D-27
2026-04-24 Regra #12 atualizada com constraint Tutoria↔correction_mode — absorve D-51 §9.6 (decisão A)
Navigation

Type to search…

↑↓ navigate↵ selectEsc close