Skip to content

REF-10-C: Table-Aware Query Engine — Spec de implementação

REF-10-C: Table-Aware Query Engine — Spec de implementação

ADR: ADR-10 (Persistência EAV própria e critérios de uso) Data: 2026-04-24 Origem: Brainstorm — diagnóstico de que item_query_repository hardcoda middag_items e ignora tabelas de plugins


Problema

O item_query_repository do MIDDAG usa private const TABLE = 'middag_items'. Plugins que declaram tabelas EAV próprias (como HÉLICO com helico_items) não conseguem usar o query engine do framework — todas as queries vão para middag_items independente da configuração do plugin.

Além disso, não existe base class para repositórios de tabelas com schema fixo (não-EAV). Plugins que precisam de tabelas dedicadas (como helico_metrics) não têm caminho para usar o query builder do MIDDAG.

Fluxo atual (quebrado)

query_builder::make() → query_executor → executor → item_query_repository
                                                      ↓
                                            private const TABLE = 'middag_items'  ← hardcoded
                                            private const TABLE_META = 'middag_itemmeta'
  • helico_item_repository existe com TABLE = 'helico_items', mas nunca é usado pelo query engine.
  • helico_item_service não existe — services injetam item_service_interface (resolve para middag).
  • Nenhuma extension de HÉLICO faz register() no container.

Decisão de design

Abordagem: Table-Aware Query Builder

O query_builder ganha um método from() que permite especificar a tabela-alvo. O item_query_repository lê essa informação do builder ao invés de usar constantes hardcoded. Fallback = middag_items (zero impacto em plugins existentes).


Entregas no MIDDAG

1. query_builder::from()

Novo método na surface API (@api):

// Novo estado interno
private ?string $table = null;
private ?string $meta_table = null;

public function from(string $table, ?string $meta_table = null): static
{
    $clone = clone $this;
    $clone->table = $table;
    $clone->meta_table = $meta_table;
    return $clone;
}

public function get_table(): ?string { return $this->table; }
public function get_meta_table(): ?string { return $this->meta_table; }
  • Imutável (retorna clone), consistente com o padrão existente.
  • Ambos opcionais — null = default do framework (middag_items / middag_itemmeta).
  • meta_table separado porque tabelas dedicadas (não-EAV) não têm meta table.

2. item_query_repository — resolução dinâmica

// Antes:
private const TABLE = 'middag_items';
private const TABLE_META = 'middag_itemmeta';

// Depois:
protected const DEFAULT_TABLE = 'middag_items';
protected const DEFAULT_TABLE_META = 'middag_itemmeta';

// Em build_sql():
$table = $builder->get_table() ?? static::DEFAULT_TABLE;
$meta_table = $builder->get_meta_table() ?? static::DEFAULT_TABLE_META;

Quando meta_table = null e a query usa where_meta() ou with_metadata(), lançar InvalidArgumentException com mensagem clara.

3. base/table_repository.php — repositório para tabelas não-EAV

Nova classe no public API boundary:

namespace local_middag\base;

abstract class table_repository extends repository
{
    protected const TABLE = '';
    protected const COLUMNS = [];

    public function find_by_id(int $id): ?entity_interface { /* via db_support */ }
    public function create(entity_interface $entity): entity_interface { /* via mapper + db_support */ }
    public function update(entity_interface $entity): entity_interface { /* via mapper + db_support */ }
    public function delete(int $id): void { /* via db_support */ }

    public function query(): query_builder
    {
        return query_builder::make()->from(static::TABLE);
    }
}
  • CRUD com db_support, transações, mapper pattern.
  • query() retorna builder pré-configurado com from().
  • Sem EAV — meta_table = null.

4. ADRs de MIDDAG impactadas

ADR Revisão necessária
ADR-503 Adicionar: plugins externos podem declarar tabelas próprias no seu db/install.xml e usar o query engine via from(). Remover restrição de “plugin separado” para storage customizado.
ADR-506 Adicionar from() à lista de métodos @api com semântica e exemplos.
ADR-507 Documentar resolução dinâmica de tabelas no item_query_repository.
ADR-502 Sem mudança de regra. Documentar que types funcionam cross-table.

5. Novos REFs em MIDDAG

REF Conteúdo
REF-503-02 Guia para plugins: como declarar tabelas próprias, registrar no container, usar from() (usa yourplugin como exemplo).
REF-506-02 Cookbook atualizado com exemplos de from() para EAV próprio e tabelas dedicadas (usa yourplugin).

Entregas no HÉLICO

1. helico_query_builder

namespace local_helico\base;

class helico_query_builder extends \local_middag\base\query_builder
{
    public static function make(): static
    {
        return parent::make()->from('helico_items', 'helico_itemmeta');
    }
}

Services usam helico_query_builder::make() — sem repetir from() em cada query.

2. helico_item_service

namespace local_helico\base;

class helico_item_service extends \local_middag\base\domain\item_service
{
    public function __construct(
        helico_item_repository $repository,
        helico_item_revision_repository $revision_repository,
    ) {
        parent::__construct($repository, $revision_repository);
    }
}

3. Registro no container

Extensions implementam register() para bindar repositórios e services:

public function register(ContainerInterface $container): void
{
    $container->register(helico_item_repository::class)->setAutowired(true);
    $container->register(helico_item_revision_repository::class)->setAutowired(true);
    $container->register(helico_item_service::class)->setAutowired(true);
}

4. Refactor dos 9 services existentes

Trocar em todos:

Antes Depois
query_builder::make() helico_query_builder::make()
item_service_interface $item_service helico_item_service $item_service

Services afetados:

  • helico_learning_path_service
  • helico_learning_path_publication_service
  • helico_study_plan_service
  • helico_study_plan_version_service
  • helico_enrolment_service
  • unit_service
  • unit_content_service
  • discipline_service
  • file_word_service

5. Repositories para tabelas dedicadas

Estendem table_repository do MIDDAG:

Repository Tabela Domínio
helico_metrics_repository helico_metrics metrics
helico_response_repository helico_response activity
helico_result_repository helico_result activity
helico_notebook_repository helico_notebook activity

6. Migração de dados

Se existirem dados em middag_items com types de HÉLICO, criar upgrade step em db/upgrade.php:

// Mover registros de middag_items → helico_items WHERE type IN (...)
// Mover registros de middag_itemmeta → helico_itemmeta WHERE itemid IN (...)
// Mesmo para revision tables

7. Atualização do ADR-10

Adicionar seção sobre helico_query_builder, helico_item_service e table_repository. Referenciar REF-10-C.


O que NÃO muda

  • Plugins sem tabelas próprias — zero impacto, default middag_* preservado.
  • query_builder API existente — todos os métodos atuais intactos.
  • item_repository base — CRUD direto continua via protected const TABLE.
  • Item type system — #[item_type] e TYPE constant funcionam cross-table.
  • Global scopes — aplicam normalmente independente da tabela.

Ordem de execução

# Ação Projeto Dependência
1 Revisar ADR-503 (regra de tabelas por plugin) MIDDAG —
2 Revisar ADR-507 (resolução dinâmica) MIDDAG —
3 Revisar ADR-506 (from() na API pública) MIDDAG —
4 Implementar query_builder::from() MIDDAG #1-3
5 Refatorar item_query_repository MIDDAG #4
6 Criar base/table_repository.php MIDDAG #4
7 Escrever REF-503-02 e REF-506-02 MIDDAG #4-6
8 Revisar ADR-10 (referenciar REF-10-C) HÉLICO #4-6
9 Criar helico_query_builder e helico_item_service HÉLICO #4-6
10 Registrar no container via register() HÉLICO #9
11 Refatorar 9 services HÉLICO #9-10
12 Criar repositories para tabelas dedicadas HÉLICO #6
13 Migração de dados middag_* → helico_* HÉLICO #9-11

Histórico

Data Evento
2026-04-24 Criado — spec de implementação para table-aware query engine
Navigation

Type to search…

↑↓ navigate↵ selectEsc close