REF-10-D: Mapa de Storage por Entity
ADR: ADR-10 (Persistência EAV própria e critérios de uso) Status: Aceito Data: 2026-04-24
Contexto
O local_helico usa dois padrões de persistência: EAV (helico_items) para entities de configuração e estrutura; tabelas dedicadas para dados transacionais de alto volume. Este REF mapeia todas as entities às suas tabelas, complementando o ADR-10 com a visão por entity.
EAV — helico_items / helico_itemmeta
Domínio content
| item_type | Conceito | Aggregate? | Subdomain |
|---|---|---|---|
discipline |
Disciplina | sim | content.base |
unit |
Unidade | não | content.base |
unit_content |
Tópico de Conteúdo | não | content.base |
unit_snapshot |
Snapshot imutável de Unidade | não | content.base |
file_word |
Arquivo Word de origem | sim | content.management |
file_word_validation |
Resultado de validação do Word | não | content.management |
flashcards |
Set de flashcards de uma Unidade | não | content.base |
question_history |
Histórico de questões por Aluno | não | content.base |
change_record |
Registro de alteração pedagógica | sim | content.change |
report_change |
Relatório de impacto de mudança | não | content.change |
sync_job |
Job de sincronização SharePoint | não | content.management |
process_job |
Job de processamento de Word | não | content.management |
flashcard_job |
Job de geração de flashcards | não | content.management |
Domínio product
| item_type | Conceito | Aggregate? | Subdomain |
|---|---|---|---|
product |
Produto Comercial | sim | product.commercial |
trail |
Trilha Pedagógica | sim | product.learning_path |
trail_publication |
Publicação da Trilha | não | product.learning_path |
trail_validation |
Resultado de validação da Trilha | não | product.learning_path |
trail_preview |
Pré-visualização da Trilha | não | product.learning_path |
plan |
Plano de Estudo (compilado) | sim | product (gerado em engine.algorithm) |
plan_sequence |
Sequência do Plano de Estudo | não | product |
plan_version |
Versão do Plano de Estudo | não | product |
Domínio engine
| item_type | Conceito | Aggregate? | Subdomain |
|---|---|---|---|
enrolment |
Matrícula | sim | engine.access |
roadmap |
Plano do Aluno | sim | engine.plan |
study_flow |
Fluxo de Estudo | não | engine.plan |
study_block |
Bloco de Estudo | não | engine.plan |
stage |
Etapa | não | engine.plan |
cda_cycle |
Ciclo CDA | não | engine.plan |
segment |
Segmento (DI ou SVD) | não | engine.plan |
execution_session |
Sessão de Execução | não | engine.session |
onboarding |
Onboarding do Aluno | não | engine.onboarding |
profile_questionnaire |
Questionário de Perfil | não | engine.onboarding |
habit_tracker |
Rastreador de Hábitos | não | engine.onboarding |
Hierarquia EAV do engine via parent:
enrolment
roadmap
└── study_flow
└── study_block
└── cda_cycle
└── segment
└── stage
└── execution_sessionTabelas dedicadas
Domínio activity
| Tabela | item_type (type) | Conceito | Justificativa |
|---|---|---|---|
helico_response |
response |
Resposta/submissão de atividade | Append-only, alto volume, sem update |
helico_result |
result |
Resultado computado (NR, elegibilidade) | Queries analíticas, consumido por metrics |
helico_notebook |
notebook |
Artefato do Caderno Online | Versionamento inline, sync status nativo |
Domínio metrics
| Tabela | Campo type |
Conceito | Justificativa |
|---|---|---|---|
helico_metrics |
classification |
Classificação de nível | Acumulativa, queries analíticas por aluno |
helico_metrics |
report |
Relatório de desempenho | Gerado event-driven, queries por trail/período |
Resumo por domínio
| Domínio | EAV (helico_items) |
Tabelas dedicadas | Total de item_types EAV |
|---|---|---|---|
| content | sim | — | 13 |
| product | sim | — | 8 |
| engine | sim | — | 11 |
| activity | — | helico_response/result/notebook | — |
| metrics | — | helico_metrics (2 types) | — |
| platform | — | — (stateless, sem persistência) | — |
Total: 32 item_types no EAV + 4 tabelas dedicadas = 8 tabelas físicas.
Critérios de decisão (resumo do ADR-10)
Uma entity deve ter tabela própria quando qualquer dos seguintes se aplica:
- Mais de 10.000 registros/mês esperados
- Append-only (respostas, classificações)
- Queries analíticas recorrentes (agregações, agrupamentos)
- Versionamento inline necessário
- Leitura/escrita em caminho de alta frequência
Ver ADR-10 para a decisão completa e REF-10-B para o mapeamento de TYPE constants (renames legado → canônico).