MAD Designer iconMAD

MADModel — a camada de modelo de leitura do documento

Esta página descreve o MADModel, o modelo de leitura sobre as entidades Rptq: o que é cada classe, como ela é populada e mantida atualizada, e quem a lê.

Escrito na data original; fatos do estado atual reconciliados em 2026-11-22.

Escopo: MAD/Source/model/MADModel*.{h,m}, MAD/Source/model/MADTableFieldIdentifier.{h,m} e todo consumidor da camada em MAD e no MAD Designer. Data: 2026-10-16, lido em d7faff320. Status: referência. Tudo aqui foi lido em primeira mão nesse commit; os candidatos a refatoração da §7 são propostas e não estão aplicados.


1. O que a camada é

MADModel* é uma visão somente leitura, no escopo do documento, da definição do documento — a conexão, o esquema (tabelas e campos) e o grafo de consulta (quais tabelas a consulta usa, quais campos e as junções entre elas). É a ela que a interface de consulta do designer se vincula.

Ela não é o modelo canônico. O modelo canônico é o grafo de objetos Rptq* no armazenamento portátil: é o que o aplicativo edita, salva, converte e renderiza. Um objeto MADModel* é pouco mais que um identificador de linha do armazenamento (int64_t) mais um ponteiro fraco para o RptqStoreContext mais alguns valores de exibição copiados, resolvidos sob demanda buscando linhas com objectsForEntity:identifier:.

A regra prática que o código segue:

Escreva através de Rptq; leia e observe através de MADModel.

As duas camadas compartilham um espaço de identificadores: o identifier de um objeto de modelo é o identifier da linha do armazenamento. Essa é toda a cola — veja §3.

MADModelDocument                       one per open .mad — MADocument.documentModel
 └ databases: [MADModelDatabase]       (today: exactly one)
    ├ driverID / driverType / schemaName   ← RptqDatabase + RptqDatabaseCredentals
    ├ tables / tableDictionary : {id → MADModelTable}      ← RptqDatabaseSchemaTable
    │   └ MADModelTable  (name, queryable)
    │      └ fields / fieldIDs : {id → MADModelField}      ← RptqDatabaseSchemaField
    │         └ MADModelField (name, dataType, decimals, width, primaryKey)
    └ queries: [MADModelQuery]         (today: exactly one; `firstQuery` everywhere)
       └ MADModelQuery
          ├ queryTableIDs / tables : {id → MADModelQueryTable}   ← RptqQueryTable
          │   └ MADModelQueryTable  (schemaTable id, dropIndex, alias)
          │      └ queryFields : {id → MADModelQueryField}       ← RptqQueryField
          │         └ MADModelQueryField (schemaTable + schemaField ids)
          └ queryLinkIDs / links : {id → MADModelQueryLink}      ← RptqQueryLinks
              └ MADModelQueryLink   (left/right table+field ids — one join)

2. As classes

2.1 MADModel — identidade (MADModel.h, MADModel.m)

A classe base é apenas identidade: _uid (MADModel.m:32-64), com hash, isEqual: (mesma classe e mesmo _uid) e -objectID retornando o id em um NSNumber. +[MADModel newModelDocument:] (MADModel.m:35) é a fábrica nominal — nada a chama; MADocument aloca MADModelDocument diretamente. MADModelType.h define MADModelTypeUnknown/Document/Database/Queries; nada na árvore usa o enum.

O nome objectID e um debugDescription comentado que formata _objectID.URIRepresentation são a pista da idade da camada: os objetos costumavam envolver NSManagedObjectIDs (veja §5).

2.2 MADModelDocument — a raiz (MADModelDocument.h, .m)

2.3 MADModelDatabase — conexão, esquema e consultas (MADModelDatabase.h, .m)

2.4 MADModelTable / MADModelField — o esquema (MADModelTable.{h,m}, MADModelField.h)

2.5 MADModelQuery — uma consulta (MADModelQuery.h, .m)

A maior classe, e a que realmente justifica sua existência. Ela possui:

2.6 MADModelQueryTable / MADModelQueryField — as tabelas e campos da consulta

2.8 Os protocolos e as peças vestigiais

3. Ciclo de vida

3.1 Criação

MADocument constrói um MADModelDocument sob demanda (MADocument.m:389-395) e o mantém durante toda a vida do documento. Ele mantém o RptqStoreContext fraco (MADModelDocument.m:42), como todo objeto de modelo que mantém um contexto — o contexto do armazenamento é de propriedade do documento.

3.2 População

Tudo abaixo do documento é sob demanda e armazenado em cache: a primeira leitura de databases, tables, fields, queryTableIDs, queryFields ou links dispara uma passagem de busca e filtragem (objectsForEntity: sobre a entidade Rptq relevante, filtrada pelo identificador do pai, depois ordenada onde uma busca anterior à migração ordenava). Os caches só são invalidados chamando -update ou pelo caminho de notificação abaixo; nada expira por conta própria.

3.3 Mudanças ao vivo — a ida e volta

Adicionar uma tabela ou um link no designer grava linhas Rptq (por exemplo, o fluxo de adicionar tabela em MADQueryViewController.m:745-790 cria linhas RptqQueryTable + RptqQueryField e salva o contexto). O modelo então se atualiza sozinho:

user adds a table / link
  → RptqQueryTable / RptqQueryLinks rows written + saved
    → RptqStoreContextObjectsDidChangeNotification
      → MADModelDocument's observer (on its private queue)     MADModelDocument.m:91-158
        → [firstQuery insertQueryTable:/insertQueryLink:]       MADModelQuery.m:361-410
          → MADNotification…Insert/Delete reposted on main      MADModelQuery.m:361-514
            → MADQueryVisualizationViewController, MADQueryBuilderAddTableViewController

Duas filas estão em jogo: o modelo muta em _objectContextQueue (uma NSOperationQueue privada, MADModelDocument.m:83-87) e as notificações chegam na fila principal. As coleções em si não são sincronizadas.

3.4 Obsolescência

-update (documento ou banco de dados) reconstrói coleções com novos objetos de modelo; qualquer objeto de modelo entregue antes continua funcionando para o que armazenou em cache, mas não é mais o que está em firstQuery.tables. Nada na árvore chama -update em um objeto de modelo hoje — o caminho de notificação é o ativo — mas código que armazena objetos de modelo através de um -update estaria lendo entradas obsoletas.

4. Consumidores

4.1 A aba Query (construtor de consultas ad hoc)

4.2 A aba Query Visualization (caixas e conectores)

4.3 O documento e os testes

MADocument.documentModel é o único ponto de entrada de produção. Testes: MADDocumentTests.m:263-265 (databases/queries de um documento reaberto), MADDocumentTests.m:399-404 (a ordem de tabelas/campos de um MADModelDatabase), mais as suítes dedicadas MADModelQueryTableTests, MADModelQueryFieldTests e a cobertura de MADModelField / MADModelQueryLink em MADModelValueTypesTests.

4.4 O que não a usa

Então o escopo real da camada hoje é: o lado de consulta do designer, e nada mais.

5. Por que ela existe

A camada é do início de 2017 (cabeçalhos de arquivo 1/22/17–6/3/17) e foi construída na era do Core Data como um modelo de visão feito à mão para a interface de consulta: objetos leves aos quais as visões de tabela do designer e a tela de visualização podiam se vincular, em vez de NSManagedObjects e NSFetchedResultsControllers. A evidência está nos arquivos: -objectID, a descrição de depuração de NSManagedObjectID comentada em MADModel.m:66-80, e três comentários sobreviventes que dizem “era um NSFetchedResultsController” (MADQueryChooseFieldController.m:149, MTGroupByViewController.m:53, MADTableViewControllerCoreDataResults.h:14).

A migração do armazenamento (Fase C/D de MAD_STORE_MIGRATION.md) religou toda busca do Core Data para RptqStoreContext + objectsForEntity: sem mudar a superfície desta camada — e é por isso que a §Findings de MIGRATION_KICKOFF.md a chama de “[uma] camada de domínio MADModel* limpa [que] já envolve as entidades Rptq; é a costura a manter.”

Então é MVC de certo tipo, mas não “o modelo do aplicativo”: é um modelo de leitura por documento (o “modelo” do MVC como visto pelo controlador), e os objetos de domínio canônicos são o grafo Rptq. A abstração compra três coisas e é fina em todo o resto: (1) o grafo de consulta em uma forma moldada para exibição (aliases, adjacência, buscas de id para metadados) sem travessia de relacionamentos; (2) um lugar que converte notificações de mudança do armazenamento em eventos do grafo de consulta; (3) uma interface que a UI pôde manter intocada enquanto o armazenamento abaixo dela mudava completamente — que é exatamente o que aconteceu.

6. Arestas ásperas conhecidas

Lidas em primeira mão; nenhuma delas tem consumidor hoje, então todas são latentes.

  1. MADModelField.inTable (MADModelField.h:20) é declarado weak MADModelField * — o tipo está errado (deveria ser MADModelTable *) — e nada nunca o atribui.
  2. Os outros ponteiros de retorno ao pai são igualmente inutilizados: MADModelTable.inDatabase, MADModelQueryTable.inQuery e MADModelQueryField.inQueryTable nunca são atribuídos por nenhum caminho de código na árvore. Apenas MADModelQuery.inDatabase é algum dia definido (MADModelQuery.m:108-114). (-addField:schemaField: não ligar o ponteiro de retorno do seu campo já está registrado em BUGS.md.)
  3. MADModelDatabase -driverName (MADModelDatabase.m:184-215) termina em return @"";, então ele responde a string vazia mesmo depois de armazenar o nome real em cache; -schemaName já retorna a mesma string do mesmo lugar. Não existe leitor.
  4. MADModelDocument.m:228-234 decodifica um id de documento (docID) e nunca o usa.
  5. MADModelQuery -update (MADModelQuery.m:354) é vazio; MADModelDatabase -update não tem chamadores; +[MADModel newModelDocument:] não tem chamadores.
  6. MADModelType é inutilizado.
  7. Sem sincronização entre a fila privada que muta o modelo e os leitores da thread principal; e MADModelDocument mantém o contexto do armazenamento fraco, então um modelo que sobreviva ao seu documento não tem contexto para resolver nada.
  8. Nomenclatura: um MADModelDocument tem databases, e um MADModelDatabase tem queries — mas o documento constrói um “banco de dados” por consulta e hoje há exatamente um de cada. A estrutura é uma preparação para o futuro anterior à simplificação de um banco de dados/uma consulta.

7. Candidatos a refatoração (propostas — nenhuma aplicada)

Ordenados por valor sobre risco. A e B são pura arrumação; C muda o que um cabeçalho público promete; D é uma decisão.

A. Documentação, não consolidação. O ganho de clareza mais barato são comentários de cabeçalho por classe (2–4 linhas: o que a classe é, por que é chaveada, quem a lê) mais este documento. Fundir os arquivos das classes é a opção cara, não a barata: mais de dezesseis arquivos importam os cabeçalhos por classe (#import <MAD/MADModelQueryField.h> etc.), cada cabeçalho é um arquivo separado nos alvos Xcode, e a cunha de include da compilação Linux é um diretório de links simbólicos por cabeçalho (Linux/README.md, a cunha do MAD). Consolidar tocaria no pbxproj, nas listas de fontes Linux e em todo sítio de importação por um ganho cosmético. Se alguma fusão for desejada, a direção segura é a oposta: mantenha uma classe por arquivo e torne o ponto de entrada óbvio (documento no topo de MADModel.h, “comece em MADModelDocument”).

B. Excluir ou completar a superfície vestigial. Cada um destes é seguro para o comportamento (nada os lê), mas toca cabeçalhos, então trate como uma decisão de API:

C. Ligar os ponteiros de retorno declarados. inDatabase, inQuery e inQueryTable existem para que o grafo possa ser caminhado para cima; hoje apenas buscas para baixo funcionam. Atribuí-los na construção (MADModelDatabase -updateTables já tem self; insertTableRptqQueryTable: tem a consulta de modelo; -addField:schemaField: tem a tabela) faz o grafo de objetos corresponder aos seus cabeçalhos e é seguro precisamente porque nada os lê ainda. Semântica a ter em mente: eles são declarados weak, o que é correto para pais de propriedade descendente.

D. Identidade através de atualizações (uma decisão, não uma arrumação). -update substitui objetos; se identidade estável através de atualizações for desejada, os métodos de atualização devem mutar no lugar (reutilizar o objeto para um identificador, adicionar/remover a diferença) em vez de reconstruir. Isso muda a identidade observável dos objetos entregues, então requer uma escolha deliberada.

E. Deduplicação mecânica. MADModelTable.fields e -fieldIDs (MADModelTable.m:88-118) contêm o mesmo bloco de inicialização duas vezes, e os três getters de MADModelQuery repetem a mesma dança de “garantir coleções, depois atualizar” (MADModelQuery.m:116-181). Ambos podem colapsar em um auxiliar privado cada sem mudança de comportamento; vale fazer apenas quando o arquivo estiver aberto para outra coisa.

F. NÃO recomendado: renomear. MADModelDatabase → algo como MADModelConnection leria melhor, mas renomeações aqui são agitação em arquivos de projeto Xcode/Linux sem retorno funcional.

8. Se você mudar esta camada

Esta página é uma tradução para o português do Brasil do original em inglês; em caso de divergência, prevalece a versão original em inglês.