Data Dictionary

Dicionario de Dados (Data Dictionary) - Addon Studio 2.0

Dicionario de Dados define estrutura dados aplicacao — tabelas, campos, instancias, extensoes entidades nativas — declarativo via XML em datadictionary/.

Entidade Java (@JapeEntity) = classe dominio limpa — so @Column(name = "..."), @JoinColumn(name, referencedColumnName), anotacoes relacionamento (@OneToMany, @OneToOne, @ManyToOne). Toda metadata UI, tipos, descricoes, comportamento vive so nos XMLs.

> Regra fundamental: @Column so atributo name. @JoinColumn so name e referencedColumnName. Nao use @Expression, @GeneratedValue, @Option, @Property nem outro atributo extra. Tudo no XML.

---

PARTE 1 - CRIANDO O DICIONARIO DE DADOS

---

1.1 Estrutura de Arquivos

Um XML por tabela/entidade em datadictionary/.

Convencao: nome arquivo = nome tabela. Ex: TDCXYZCAD.xml pra tabela TDCXYZCAD.

---

1.2 Esqueleto XML Base

---

1.3 Tags Raiz

| Tag XML | Quando usar | |:------------------|:-------------------------------------------------------------------------| | ` | Tabela **nova** criada pelo add-on. | | | Tabela **hierarquica** (pai/filho) — cadastros tipo centro de custo, categorias de produto, organogramas. Framework gera UI tree + campos CODIGOPAI/ANALITICO/GRAU. Detalhes em [references/tree-table.md](references/tree-table.md). | | | Extensao tabela **nativa** Sankhya Om (adiciona campos/instancia). | | | Container para — encaixe em pasta nativa Sankhya (Configuracoes / Cadastros / Consulta / Rotina / Relatorio). Detalhes em [references/menu.md](references/menu.md). | | | Estrutura de menu/navegacao do add-on. Container para , , , , . Detalhes em [references/menu.md](references/menu.md). | | | Tela CRUD declarativa (sem JS/HTML) gerada a partir de uma da tabela. Vai dentro de /. Detalhes em [references/dynamic-form.md](references/dynamic-form.md). | | | Filtros de busca em telas geradas por /. Filho de /. Detalhes em [references/filters.md`](references/filters.md). |

---

1.4 Tag `` - Tabela nova

Atributos obrigatorios

| Atributo | Descricao | |:----------------|:----------------------------------------------------------------------------------------------------------------| | name | Nome tabela no banco. | | sequenceType | "A" (automatico) ou "M" (manual). Default "A" — "M" so nas excecoes da secao "Como determinar". | | sequenceField | Coluna PK que recebe sequencia. Obrigatorio com sequenceType="A"; omitir com sequenceType="M". |

Elemento filho obrigatorio: ``

` exige propria — registrada em TDDTAB.DESCRTAB (NOT NULL). Distinta da da : a do descreve a tabela fisica, a da ` descreve a entidade JAPE. Costumam ser iguais, mas as duas precisam estar presentes.

    Produtos
    ...
    
        
            Produtos
        
    
    ...

> Omitir ` da causa erro de deploy: DESCRTAB NULL em TDDTAB`.

Como determinar sequenceType

Default do ecossistema: "A" (automatica). Tabela nova do addon com PK propria nasce sequenceType="A" sequenceField="" — quem gera o valor e o framework. Cadastro, configuracao, log, registro, historico, auditoria, fila de integracao: todos "A". Nao perguntar ao dev qual usar: assumir "A" e so tratar "M" se a PK cair numa das excecoes abaixo.

"M" e excecao e precisa de justificativa. Unicos casos legitimos:

| Caso legitimo para "M" | Por que | |:----------------------------------------------------------------------------|:-------------------------------------------------------------------| | PK composta so de FKs (tabela de ligacao/vinculo) | Nao existe coluna pra sequenciar — o valor sai das FKs | | PK e codigo de negocio informado pelo usuario ou por sistema externo | O valor tem significado fora do addon; framework nao pode inventar | | PK espelha chave de registro nativo Sankhya (1:1 com NUNOTA, CODPARC, ...) | O valor ja existe no registro nativo |

> Por que "M" fora desses casos esta errado: joga a geracao da PK pra aplicacao (MAX+1 — corrida sob concorrencia) e quebra a gravacao pela tela do dicionario, que conta com a sequencia do framework. Sintoma tipico: usuario clica em "novo" na tela gerada, grava, e estoura ORA-01400: cannot insert NULL into (.) — a tela nao preenche PK que o framework nao gera. Tabela de log/config/apoio com PK manual e defeito, nao escolha de design. > > A armadilha e tabela de apoio "que so o dbscript alimenta": se ela tem `, tem tela — e alguem vai clicar em novo. Ter seed no dbscript **nao** e motivo pra "M"`.

| Estrutura da PK | XML | |:-------------------------------------------------------------|:-------------------------------------------------------| | PK simples (caso comum) | sequenceType="A" sequenceField="" | | PK composta com uma coluna sequencial (ex.: NUITEM) | sequenceType="A" sequenceField="" | | PK composta so de FKs / PK = codigo de negocio externo | sequenceType="M" (sem sequenceField) |

Exemplos XML:

    Produtos
    ...

    Vinculo Origem x Produto
    
        
        
    
    ...

> Padrao PK sequencial: nao usar prefixo ID na coluna sequencia. > Use COD* pra cadastros (ex.: CODPRODUTO), NU* pra movimentos/documentos (ex.: NUNOTA).

---

1.5 Chave Primaria (``)

Lista campos PK. PK simples = 1 `; PK composta = varios `.

---

1.6 Instancias (``)

Define entidade (instancia JAPE) da tabela. Existem duas tags possiveis dentro de ``:

| Tag | Quando usar | |:-----------------------|:---------------------------------------------------------------------------------------------| | ` | Instancia **nova**, criada pelo addon. Permitida em e em . | | | Instancia **nativa do Sankhya** (ex.: CabecalhoNota, Parceiro, Produto). **Somente** dentro de `. |

    
        Produtos
    

Atributos de ` / `

| Atributo | Obrigatorio | Descricao | |:-----------------|:------------|:----------------------------------------------------------------------------------------------| | name | Sim | Nome logico da entidade (bate com @JapeEntity(entity = "...")). | | resourceId | Nao | Identificador do recurso da instancia no Sankhya. Formato br.com.sankhya... | | parentInstance | Nao | resourceId da instancia nativa da qual esta deriva. Declara a instancia como alias/derivada da nativa. |

parentInstance — alias de instancia nativa. Use quando o addon cria uma instancia propria sobre uma tabela nativa mas quer herdar o vinculo com a instancia nativa correspondente (telas, permissoes, comportamento). O valor e o resourceId da nativa, nao o name:

">
    
        "
                  resourceId="br.com.sankhya.."
                  parentInstance="">
            ...
        
    

> O resourceId da instancia nativa alvo nao e adivinhavel — confira no dicionario do ambiente (TDDINS) ou no metadata nativo. Nunca invente o valor a partir do nome da instancia.

> Sem parentInstance, a instancia nasce solta — perde o vinculo com a nativa. Omitir o atributo na geracao dropa a informacao silenciosamente (o XSD nao exige).

> **Por que ` ao inves de :** ambas as tags geram a mesma entidade no runtime, mas sinaliza para o builder que a instancia **ja existe** no Sankhya nativo e **nao** deve ser regravada no metadata.xml final. Se uma instancia nativa for declarada como , o deploy do addon re-mapeia o owner da instancia para o addon e quebra regras de negocio, validacoes e telas nativas que dependem dela. Pareie sempre com isNativeInstance = true no @JapeEntity correspondente (ver entity` secao 1.2).

Convencao de nomes (parametrizada por projeto)

Padrao parametrizado por ` (prefixo) + (modulo). Ver database` secao "Descobrir convencao do projeto" antes de criar tabela nova.

| Atributo | Padrao | Exemplo (PRX=TDC, MOD3=XYZ) | |:----------------------------------------|:----------------------------------------|:-----------------------------| | ` | (UPPER) | TDCXYZCAB | | (em ) | (PascalCase) | TdcXyzCabecalho | | (em , instancia nova) | (PascalCase) | TdcXyzDefensivos | | (em ) | Nome **exato** da instancia nativa Sankhya | CabecalhoNota, Parceiro, ItemNota` |

Componentes do prefixo addon:

• ` / : prefixo fixo do projeto, **3-4 caracteres** (ex.: Tdc/TDC, App/APP, Cst/CST`)
• ` / : sigla modulo, **3 caracteres** (ex.: Xyz/XYZ, Fin/FIN`)
• ` / : contexto/entidade (ex.: Cabecalho/CAB, Item/ITE`)

> Prefixo ` no evita colisao com outros contextos do ERP. Bate com @JapeEntity(entity = "...") correspondente. ` nunca leva prefixo addon — o nome tem que ser identico ao da instancia nativa Sankhya.

> NOTA: exemplos seguintes usam TDC como prefixo ilustrativo. Substituir pelo `` real do projeto.

---

1.7 Relacionamentos (``)

Entidade com relacao (@OneToMany, @OneToOne) declara ` dentro /`.

Atributos do ``

| Atributo XML | Obrigatorio | Default | Significado | |:----------------|:------------|:------------|:--------------------------------------------------------------------------------| | entityName | Sim | - | Nome da instancia relacionada. | | relation | Nao | OneToOne | Tipo: OneToOne, OneToMany, ManyToOne, ManyToMany. Default e OneToOne — informar sempre em relacao 1:N. | | insert | Nao | - | "S"/"N". So com OneToOne: inclui a entidade relacionada que tenha merge-on-root. | | update | Nao | - | "S"/"N". So com OneToOne: atualiza a entidade relacionada que tenha merge-on-root. | | removeCascade | Nao | - | "S"/"N". So com OneToMany: exclui os dados relacionados (equivale a delete on cascade). |

Filhos: ` (opcional) e (obrigatorio). Cada do tem localName (coluna da tabela atual) e targetName` (coluna da relacionada).

    Produtos
    
        
            
                
            
        
    

Sub-tag ` do ` (opcional)

Configura o relacionamento e/ou filtra a entidade destino. Aceita tres formatos (combinaveis no mesmo ``):

1) @ref-param[...] — configuracao do relacionamento (reflete no dynaform)

| Opcao | Efeito | |:----------------------------|:------------------------------------------------------------------------------------------------| | description= | Descricao da aba no dynaform (ex.: description=Contatos). | | force-one-to-one=true | Forca entidade com chave dupla por data a aparecer como pesquisa em vez de aba. Ex.: TipoOperacao, TipoNegociacao. | | result-only-analytic=true | Exibe so registros analiticos da entidade hierarquica destino. | | show-on-ui=false | Com dynaform, a aba nao aparece na tela. | | auto-search=true | Busca automatica da relacionada. | | merge-on-root=true | Junta as 2 entidades na tela — o usuario ve uma coisa so. Pareia com insert/update no `. | | merge-to-find=true | Junta as entidades na busca. | | APP_PROFILE=P:(...) | Exibe so se o cliente tiver os modulos da chave. Formato P:({},...)` — chave e codigo saem do modulo licenciado, nao invente. |

2) @form-filter[...] — filtro de formulario

Pode depender de campo dos dois formularios. Alias form. = formulario de origem; alias this. = formulario de destino.

3) Filtro simples — depende so da entidade destino. Alias this..

> force-one-to-one decide OneToOne vs aba no dynaform; description= nomeia a aba. Omitir `` na geracao perde cardinalidade correta, filtro e nome de aba — o XSD nao exige, entao a falta e silenciosa.

---

1.8 Campos (` e `)

Cada `` = coluna + metadata.

Atributos do ``

| Atributo XML | Tipo | Obrigatorio | Default | Descricao | |:------------------|:-------|:------------|:--------|:-------------------------------------------------------------| | name | String | Sim | - | Nome coluna no banco. | | dataType | String | Sim | - | Tipo dado (ver tabela abaixo). | | size | int | Nao | - | Tamanho (TEXTO). | | nuCasasDecimais | int | Nao | - | Casas decimais (DECIMAL). | | required | String | Nao | "N" | Obrigatorio: "S" ou "N". | | readOnly | String | Nao | "N" | Somente leitura: "S" ou "N". | | nullable | String | Nao | "S" | Permite valor nulo: "S" ou "N". | | allowDefault | String | Nao | "S" | Permite valor padrao: "S" ou "N". | | allowSearch | String | Sim | "N" | Permite pesquisa: "S" ou "N". Sempre informar. | | visibleOnSearch | String | Sim | "N" | Visivel na pesquisa: "S" ou "N". Sempre informar. | | isPresentation | String | Nao | "N" | Campo apresentacao entidade. | | visible | String | Nao | "S" | Visivel UI ("N" oculta). | | calculated | String | Nao | "N" | Calculado, nao persistido. | | order | int | Nao | - | Ordem exibicao tela. | | UITabName | String | Nao | - | Aba UI. "__main" = aba principal. | | UIGroupName | String | Nao | - | Agrupamento na aba. | | targetInstance | String | Condicional | - | (PESQUISA) Entidade referenciada. | | targetField | String | Condicional | - | (PESQUISA) Campo na en

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: snk-devcenter
• Source: snk-devcenter/addon-studio
• License: MIT

Install and usage instructions live in the source repository linked above.