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_repositoryexiste comTABLE = 'helico_items', mas nunca é usado pelo query engine.helico_item_servicenão existe — services injetamitem_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_tableseparado 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 comfrom().- 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_servicehelico_learning_path_publication_servicehelico_study_plan_servicehelico_study_plan_version_servicehelico_enrolment_serviceunit_serviceunit_content_servicediscipline_servicefile_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 tables7. 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_builderAPI existente — todos os métodos atuais intactos.item_repositorybase — CRUD direto continua viaprotected const TABLE.- Item type system —
#[item_type]eTYPEconstant 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 |