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)responseregistra a interação bruta: respostas de VF/Objetivo, submissões de Escrito (upload), práticas de Flashcards. Cada response referencia aexecution_sessiondo 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.xmlquando 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_completedsegue 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) |