ADR-10: Persistência EAV própria e critérios de uso
Status: Aceito Data: 2026-04-17
Contexto
O local_helico utilizava o padrão EAV (Entity-Attribute-Value) fornecido pelo local_middag, com tabelas middag_items e middag_itemmeta. Embora funcional, essa dependência acopla o ciclo de release do HÉLICO ao do middag: migrations, alterações de schema e evoluções de persistência ficam atreladas a um pacote externo.
Para entidades de configuração e baixo volume, o padrão EAV continua sendo adequado. No entanto, o HÉLICO precisa de critérios claros para decidir quando uma entidade deve usar o padrão EAV e quando deve ter tabela relacional própria. O EAV é flexível para entidades de configuração, mas apresenta limitações em cenários de alto volume, queries analíticas e índices compostos.
Decisão
1. EAV próprio em local_helico
Migrar de EAV do middag para EAV próprio, mantendo o mesmo padrão arquitetural (items + itemmeta + revision + revision_meta).
- Tabelas base:
helico_items,helico_itemmeta,helico_item_revision,helico_item_revision_meta. - TYPE: todos os tipos de entidade usam identifier direto, sem prefixo
helico_(conforme ADR-20,class_prefix: false). Ver REF-10-B para mapeamento completo. - Migrations: controladas exclusivamente pelo
local_helico, independentes do ciclo de release do middag. - Models: todos os models do HÉLICO estendem a base EAV própria, não mais a do middag.
- Compatibilidade: o padrão EAV é mantido — a mudança é de ownership, não de arquitetura.
2. Critérios para EAV vs tabela própria
EAV (helico_items / helico_itemmeta)
Indicado para:
- Entities de configuração e estrutura: Produto, Trilha, Plano de Estudo, Matrícula, Plano do Aluno
- Entities de execução estrutural: Fluxo, Bloco, Etapa, Ciclo CDA, Segmento, Sessão de Execução
- Entities auxiliares: Onboarding, Questionário de Perfil, Rastreador de Hábitos
- Volume previsível: centenas a poucos milhares de registros por tipo
Tabela própria
Indicado para:
- Respostas e submissões de atividades (alto volume, append-only)
- Resultados computados de atividades (consumidos por metrics)
- Classificações e relatórios de métricas (queries analíticas, consolidação)
- Artefatos do Caderno Online (versionamento, sync status)
Critérios objetivos para tabela própria
Uma entidade deve ter tabela própria quando qualquer dos seguintes critérios se aplica:
- Volume: mais de 10.000 registros/mês esperados
- Append-only: registros imutáveis que só crescem (respostas, classificações)
- Queries analíticas: agregações, agrupamentos, joins recorrentes
- Versionamento inline: necessidade de version + sync status nativos
- Performance crítica: leitura ou escrita em caminhos de alta frequência
3. Mapa definitivo de tabelas
Tabelas EAV (herdadas do padrão MIDDAG)
| Tabela | Função |
|---|---|
helico_items |
Estado atual dos items |
helico_itemmeta |
Metadados key-value |
helico_item_revision |
Histórico imutável de revisões |
helico_item_revision_meta |
Metadados das revisões |
Tabelas dedicadas
| Tabela | Domínio | Função | ADR |
|---|---|---|---|
helico_metrics |
metrics | Classificações + Relatórios (via campo type) |
ADR-70 |
helico_response |
activity | Respostas e submissões de atividades | ADR-80 |
helico_result |
activity | Resultados computados (NR, elegibilidade) | ADR-80 |
helico_notebook |
activity | Artefatos do Caderno Online (versionados) | ADR-80 |
Total: 4 tabelas EAV + 4 tabelas dedicadas = 8 tabelas.
Item types EAV por domínio
| Domínio | item_types |
|---|---|
| product | product, trail, trail_publication, trail_validation, trail_preview, plan, plan_sequence, plan_version |
| engine | enrolment, roadmap, study_flow, study_block, stage, cda_cycle, segment, execution_session, onboarding, profile_questionnaire, habit_tracker |
| content | discipline, unit, unit_content, unit_snapshot, file_word, file_word_validation, flashcards, question_history, change_record, report_change, sync_job, process_job, flashcard_job |
Consequências
- Independência de ciclo de release: HÉLICO pode evoluir schema sem aguardar releases do middag.
- 8 tabelas no total — modelo enxuto. Domínios product, engine e content inteiros em EAV.
- Apenas 4 tabelas dedicadas para dados transacionais de alto volume (activity + metrics).
- Critérios objetivos reduzem decisões ad hoc sobre modelagem.
- Entidades podem migrar de EAV para tabela própria conforme o volume cresce — o critério é revisável.
- Manutenção de duas implementações EAV (middag e helico) no mesmo ambiente Moodle.
- Item types do engine (study_flow, study_block, etc.) com hierarquia
parentprofunda no EAV — monitorar performance.
ADRs relacionados
- ADR-01 — Separação de regra pedagógica, orquestração e infraestrutura
- ADR-02 — Ciclo de vida em 4 fases — orienta a modelagem de entidades por fase
- ADR-11 — Versionamento snapshot imutável — snapshots usam EAV próprio
- ADR-30 — Domínio Content — entities em EAV
- ADR-50 — Domínio Product — product, trail, plan em EAV
- ADR-60 — Domínio Engine — enrolment, roadmap + entities estruturais em EAV
- ADR-70 — Domínio Metrics — helico_metrics (tabela dedicada)
- ADR-80 — Domínio Activity — helico_response, helico_result, helico_notebook (tabelas dedicadas)
- REF-10-B — Mapeamento de TYPE constants (renames legado → canônico)
- REF-10-C — Table-Aware Query Engine — Spec de implementação (query builder
from(),table_repository,helico_query_builder,helico_item_service)
Histórico
| Data | Evento |
|---|---|
| 2026-04-17 | Criado — consolida ADR-106 e ADR-108 |
| 2026-04-24 | Atualizado — mapa definitivo de 8 tabelas + item_types por domínio (sessão 15) |
| 2026-04-24 | REF-10-C — spec table-aware query engine (diagnóstico: query engine hardcoda middag_items) |