📂 Dicionário de Dados (Data Dictionary)

Conheça o novo mecanismo de Mapeamento de Instâncias/Entidades no Dicionário de Dados.

Leia a documentação de AutoDD e de ORM.

O Dicionário de Dados é o coração do seu add-on. É onde você define a estrutura de dados da sua aplicação — tabelas, telas, menus e extensões de entidades nativas — de forma declarativa usando arquivos XML.

Este mecanismo garante que suas personalizações sejam armazenadas e manipuladas de maneira estruturada, segura e padronizada dentro do ecossistema Sankhya.

🗂️ Estrutura de Arquivos

Todos os arquivos do Dicionário de Dados devem ser criados dentro do diretório datadictionary, localizado em model/src/main/resources/.

💡 Boa Prática: Crie um arquivo XML separado para cada entidade principal (uma tabela, um menu, etc.). Isso torna a manutenção muito mais simples. Por exemplo, SGT_MINHATABELA.xml, SGT_MEUMENU.xml.

📄 Arquivo XML Base e o metadados.xsd

Todo arquivo de dicionário de dados deve seguir uma estrutura XML padrão que referencia o metadados.xsd. Este XSD (XML Schema Definition) é crucial, pois permite que sua IDE valide o arquivo e ofereça autocompletar, guiando o desenvolvimento.

Estrutura inicial:

<?xml version="1.0" encoding="iso-8859-1" ?>
<metadados xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="../.gradle/metadados.xsd">
           
    <!-- Suas definições de tabelas, menus, etc., vêm aqui -->

</metadados>

🏛️ Estruturas de Dados Suportadas

Dentro da tag <metadados>, você pode definir diversas estruturas, conforme o metadados.xsd.

🧩 Merge-on-root via XML

O merge-on-root estende uma entidade com os campos de outra tabela, sem criar colunas na tabela estendida. Na instância da entidade raiz, declare um relacionamento 1:1 com a expressão @ref-param[merge-on-root=true] para a tabela de extensão: uma <table /> comum com a mesma chave primária da raiz. A plataforma funde as duas, e na tela e no registro é uma entidade só.

Exemplo: a instância nativa Parceiro (TGFPAR) estendida pela tabela CNX_INTEGRACAO_PARCEIRO (entidade CNX_IntegracaoParceiro), ligadas por CODPARC:

<?xml version="1.0" encoding="UTF-8"?>
<metadados xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="../.gradle/metadados.xsd">
    <nativeTable name="TGFPAR">
        <instances>
            <nativeInstance name="Parceiro">
                <relationShip>
                    <relation entityName="CNX_IntegracaoParceiro" insert="S" update="S" relation="OneToOne" removeCascade="N">
                        <expression>@ref-param[merge-on-root=true]</expression>
                        <fields>
                            <field localName="CODPARC" targetName="CODPARC"/>
                        </fields>
                    </relation>
                </relationShip>
            </nativeInstance>
        </instances>
    </nativeTable>
</metadados>

O mesmo resultado com @JapeEntity está em Merge-on-root.

✨ Boas Práticas

• Nomenclatura com Prefixo Único: Use um prefixo exclusivo para suas tabelas e campos (ex: SGT_ para o add-on "Super Gestão") para evitar conflitos com as tabelas nativas e de outros add-ons.
• Organização: Separe as definições em arquivos lógicos. Exemplo: um arquivo para a tabela SGT_PRODUTOEXTRA, outro para o menu menu.xml.
• Validação Contínua: Confie no XSD. Se a IDE apontar um erro no seu XML, corrija-o antes de tentar fazer o deploy.

🚫 Anti-Patterns (O que evitar)

• Uso do Prefixo AD_: Não use o prefixo AD_. Ele é utilizado internamente pelo SankhyaOm para campos e tabelas adicionai criados via contrutor de Telas e Dicionário de dados.
• "Monolito" XML: Colocar todas as definições (tabelas, menus, telas) em um único arquivo gigante. Isso dificulta a leitura, a manutenção e o trabalho em equipe.
• Adicionar Campos em Tabelas Nativas: Não use <nativeTable /> para criar campos numa tabela nativa (ex: TGFPAR). Isso exige migração numa tabela de alta carga, o que pode derrubar o SankhyaOM. Crie uma tabela de extensão (ex: SGT_INFOPARCEXTRA) com a mesma chave primária e ligue-a à entidade nativa com merge-on-root.
• Ignorar o XSD: Escrever o XML "no bloco de notas" sem a ajuda do metadados.xsd é uma receita para erros de sintaxe e estrutura que só serão descobertos em tempo de deploy.