# Data Dictionary > Cria, revisa e padroniza XML do dicionário de dados Sankhya (`datadictionary/.xml`) — ``, ``, ``, ``, ``, ``, ``, ``, ``, `dataType` (TEXTO/INTEIRO/DECIMAL/DATA/DATA_HORA/HORA/CHECKBOX/LISTA/PESQUISA), ``, `calculated`, lookups e relacionamentos. Use ao criar, alterar, revisar, audita… - **Type:** Skill - **Install:** `agentstack add skill-snk-devcenter-addon-studio-data-dictionary` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [snk-devcenter](https://agentstack.voostack.com/s/snk-devcenter) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [snk-devcenter](https://github.com/snk-devcenter) - **Source:** https://github.com/snk-devcenter/addon-studio/tree/main/plugins/addon-studio/skills/data-dictionary ## Install ```sh agentstack add skill-snk-devcenter-addon-studio-data-dictionary ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ```xml ``` --- ## 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. ```xml 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:** ```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 ``. ```xml ``` --- ## 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 ``. | ```xml Produtos ``` ```xml ``` ### 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`: ```xml "> " 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). ```xml 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.`. ```xml ``` > `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](https://github.com/snk-devcenter) - **Source:** [snk-devcenter/addon-studio](https://github.com/snk-devcenter/addon-studio) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-snk-devcenter-addon-studio-data-dictionary - Seller: https://agentstack.voostack.com/s/snk-devcenter - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.