Skip to content

ADR-10: Persistência EAV própria e critérios de uso

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 parent profunda 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)
Navigation

Type to search…

↑↓ navigate↵ selectEsc close