Entity

Entidade Java (@JapeEntity) — Addon Studio 2.0

Entidade Java = representação domínio de tabela banco. Limpa — contém só mapeamento estrutural mínimo. Metadata UI, tipos, descrições, comportamento fica no Dicionário de Dados (XMLs em datadictionary/).

> Referência complementar: consulte data-dictionary para criar XML correspondente à entidade.

---

1. Regras Fundamentais

| Regra | Detalhe | |:-----------------------------------------------------|:----------------------------------------------------------| | @Column só tem name | @Column(name = "COLUNA") — nenhum outro atributo. | | @JoinColumn só tem name e referencedColumnName | @JoinColumn(name = "...", referencedColumnName = "...") | | @JapeEntity tem entity, table, isNativeTable e isNativeInstance | Addon puro: @JapeEntity(entity = "...", table = "..."). Tabela nativa Sankhya: adicionar isNativeTable = true. Instância também nativa: adicionar isNativeInstance = true. Veja seção 1.2. | | Sem @Expression | Expressões ficam no XML (`). | | Sem @GeneratedValue | Sequência fica no XML (sequenceType/sequenceField) — default "A", PK automática. | | Sem @Option / @Property | Opções ficam no XML (). | | Lombok obrigatório | @Data, @NoArgsConstructor, @AllArgsConstructor. | | Convencao de nomenclatura no entity/table` | Veja secao 1.1. |

1.1 Convencao de nomes (parametrizada por projeto)

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

| Atributo | Padrao | Exemplo (PRX=TDC, MOD3=XYZ) | |:----------|:------------------------------------|:-----------------------------| | entity | ` (PascalCase) | TdcXyzCabecalho | | table | (UPPER) | TDCXYZCAB` |

Componentes:

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

entity usa PascalCase legivel (Xyz, nao XYZ). table usa UPPER concatenado.

Exemplo coerente (`=TDC, =XYZ`):

@JapeEntity(entity = "TdcXyzCabecalho", table = "TDCXYZCAB")

> Antes criar entidade nova: (1) inspecionar projeto pra detectar ` existente; (2) se ausente, perguntar dev + + ; (3) confirmar entity + table` final.

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

1.2 Tabelas e Instâncias Nativas Sankhya (isNativeTable / isNativeInstance)

@JapeEntity aceita dois flags para sinalizar quando a tabela e/ou a instância já existem no Sankhya nativo. Os dois flags são independentes e cobrem 3 cenários:

| Cenário | isNativeTable | isNativeInstance | Tag XML correspondente | |:--------------------------------------|:----------------|:-------------------|:----------------------------------------| | Tabela addon + Instância addon | omitir | omitir | ` + | | Tabela nativa + Instância **nova** do addon | true | omitir | + | | Tabela nativa + Instância nativa | true | true | + ` |

> Por que isso importa: sem isNativeTable, o KSP rejeita a compilação com erro de entidade duplicada ao detectar que a tabela já existe. Sem isNativeInstance em uma instância nativa, a instância é regravada no metadata.xml gerado e, durante o deploy do addon, o dicionário a re-mapeia para o owner do addon — quebrando todas as regras, validações e telas nativas que dependem dessa instância.

Tabelas nativas mais comuns: TGFCAB, TGFFIN, TGFORD, TGFVEI, TGFEMP, TGFPAR, TGFPRO, TGFITE. Instâncias nativas mais comuns associadas: CabecalhoNota (TGFCAB), ItemNota (TGFITE), Parceiro (TGFPAR), Produto (TGFPRO), TipoOperacao (TGFTOP), Financeiro (TGFFIN).

// 1) Tabela e instância do addon — sem flags
@JapeEntity(entity = "TdcXyzCabecalho", table = "TDCXYZCAB")
public class TdcXyzCabecalho { ... }

// 2) Tabela nativa, instância NOVA do addon — só isNativeTable
@JapeEntity(entity = "TdcXyzDefensivos", table = "TGFDFAGR", isNativeTable = true)
public class TdcXyzDefensivos { ... }

// 3) Tabela e instância nativas — os dois flags
@JapeEntity(entity = "CabecalhoNota", table = "TGFCAB",
            isNativeTable = true, isNativeInstance = true)
public class CabecalhoNota { ... }

> Regra prática: se o entity for um nome usado pelo Sankhya nativo (CabecalhoNota, ItemNota, Parceiro, Produto, etc.), use isNativeInstance = true. Se o entity segue a convenção Tdc do addon, é instância nova — não use isNativeInstance.

---

2. Organizacao

> Skill nao opina sobre estrutura de pacotes. Organize entidades, Enums, PKs compostas, classes de dominio puro conforme arquitetura do seu projeto.

Tipos de classe que aparecem aqui:

| Tipo | Caracteristica | |:-------------------------------------------|:------------------------------------------------------------------------| | Entidade persistida (@JapeEntity) | Mapeia tabela do banco | | PK composta (@Embeddable) | Classe que agrupa colunas-chave de uma PK composta | | Enum (Value Object) | Valores finitos persistidos como texto curto | | Classe sem persistencia | Conceito de negocio, sem @JapeEntity (@Data + factory methods) |

---

3. Tipos de Classe no Domínio

3.1 Entidade Persistida (@JapeEntity)

Representa tabela no banco. Tem @JapeEntity, @Id, @Column, opcionalmente relacionamentos.

@JapeEntity(entity = "TdcXyzAlvo", table = "TDCXYZALV")
public class TdcXyzAlvo { ...
}

3.2 PK Composta (@Embeddable)

Tabela com PK composta — classe separada anotada com @Embeddable.

@Embeddable
public class TdcXyzEntidadeId { ...
}

3.3 Enum (Value Object)

Valores finitos de domínio (listas opções). Usados como tipo campo em entidades. Têm value = valor armazenado no banco.

Regras obrigatórias:

| Regra | Detalhe | |:-----------------------------------|:-----------------------------------------------------------------| | @Getter (Lombok) | Gera o getter de value automaticamente. | | @AllArgsConstructor (Lombok) | Gera o construtor que recebe value. | | Campo private final String value | Valor persistido no banco (código curto). | | Sufixo Enum | Nome da classe sempre termina com Enum (ex: TipoStatusEnum). |

Anatomia completa:

import lombok.AllArgsConstructor;
import lombok.Getter;

@Getter
@AllArgsConstructor
public enum TipoEnum {
    OPCAO_A("A"),
    OPCAO_B("B");

    private final String value;
}

3.4 Classe de Domínio Puro

Classes representando conceitos domínio sem persistência direta. Sem @JapeEntity. Contêm lógica negócio, validações, factory methods.

public class ResultadoCalculo { ...
}

public class DadosConsolidados { ...
}

---

4. Anatomia de uma Entidade

import br.com.sankhya.studio.persistence.*;                    // 1. Imports de persistência
import lombok.*;                                                // 2. Imports Lombok

@Data                                                           // 3. Lombok obrigatório
@NoArgsConstructor
@AllArgsConstructor
@JapeEntity(                                                    // 4. Mapeamento: somente entity + table
    entity = "NomeDaEntidade",
    table = "NOME_TABELA"
)
public class NomeDaEntidade {                                   // 5. Classe plana (sem herança de metadata)

    @Id                                                         // 6. Chave primária
    @Column(name = "COLUNA_PK")
    private Integer id;

    @Column(name = "COLUNA_1")                                  // 7. Campos: somente name
    private String campo1;

    @OneToMany(...)                                             // 9. Relacionamentos (se houver)
    private List filhos;

    public void metodoDeNegocio() { ...}                      // 10. Métodos de domínio (se houver)
}

---

5. Anotações Permitidas

Anotações que DEVEM ser usadas

| Anotação | Uso | Pacote | |:-----------------------------|:------------------------------------------------|:------------------------------------| | @JapeEntity(entity, table) | Toda entidade persistida | br.com.sankhya.studio.persistence | | @Id | Campo(s) de chave primária | br.com.sankhya.studio.persistence | | @Column(name) | Todo campo persistido | br.com.sankhya.studio.persistence | | @Embeddable | Classe de PK composta | br.com.sankhya.studio.persistence | | @Data | Getter/Setter/ToString/Equals/Hash | lombok | | @NoArgsConstructor | Construtor vazio (obrigatório para o framework) | lombok | | @AllArgsConstructor | Construtor com todos os campos | lombok |

Anotações opcionais (usar quando necessário)

| Anotação | Quando usar | Pacote | |:------------------------------------------|:-----------------------------------------------------------------------------|:------------------------------------| | @Builder | Quando a entidade é construída programaticamente no domínio | lombok | | @OneToMany | Relacionamento pai -> filhos | br.com.sankhya.studio.persistence | | @OneToOne | Navegação para entidade referenciada | br.com.sankhya.studio.persistence | | @ManyToOne | Navegação inversa filho -> pai | br.com.sankhya.studio.persistence | | @JoinColumn(name, referencedColumnName) | Junto com @OneToOne / @ManyToOne | br.com.sankhya.studio.persistence | | @JoinColumns | Múltiplos @JoinColumn (FK composta) | br.com.sankhya.studio.persistence | | @Cascade | Dentro de @OneToMany para cascatear operações | br.com.sankhya.studio.persistence | | @Relationship | Dentro de @OneToMany para definir campos do vínculo | br.com.sankhya.studio.persistence | | @SuperBuilder | Quando a entidade herda de classe base de domínio (ex: VO com campos comuns) | lombok.experimental | | @EqualsAndHashCode(callSuper = true) | Junto com herança + @SuperBuilder | lombok |

Anotações PROIBIDAS na entidade

| Anotação | Onde fica | Motivo | |:------------------|:-----------------------------------|:----------------------| | @Expression | XML ` | Metadata do framework | | @GeneratedValue | XML sequenceType/sequenceField | Metadata do framework | | @Option | XML | Metadata de UI | | @Property` | XML | Metadata do framework |

---

6. Chave Primária (PK)

Padrões de chave primária — @Id em PK simples (Integer ou BigDecimal conforme tabela addon vs nativa) e PK composta via @Embeddable com convenções e métodos auxiliares — em [references/primary-key.md](references/primary-key.md).

---

7. Campos (@Column)

Regra única

@Column(name = "NOME_COLUNA")
private TipoJava nomeCampo;

Nenhum outro atributo. Ponto.

Mapeamento de tipos

| Tipo no banco / XML | Tipo Java sugerido | |:---------------------------------|:---------------------------------------| | INTEIRO | Integer ou BigDecimal | | TEXTO | String | | DECIMAL | BigDecimal | | DATA_HORA | Timestamp (java.sql.Timestamp) | | CHECKBOX | Boolean | | PESQUISA (FK) | BigDecimal ou Integer (tipo da FK) | | Campo com opções (enum no banco) | Enum Java (veja seção 9) | | Demais dataTypes (CAIXA_TEXTO, HORA, LISTA, HTML, ARQUIVO, ...) | Ver tabela completa em data-dictionary/references/xml-to-java.md |

Quando usar Integer vs BigDecimal

| Contexto | Tipo | Motivo | |:-----------------------------------------------|:--------------------------|:---------------------------------| | PKs de tabelas do add-on (COD*/NU*) | Integer | Sequenciais do add-on sao inteiros simples | | PKs de tabelas nativas (NUNOTA, CODPARC, etc.) | BigDecimal | Padrão do Sankhya Om | | Quantidades, valores monetários | BigDecimal | Precisão decimal | | Campos numéricos simples | BigDecimal ou Integer | Conforme necessidade |

---

8. Relacionamentos

Padrões de relacionamento — @OneToMany (pai → filhos), @OneToOne + @JoinColumn (navegação para entidade referenciada), @OneToOne/@ManyToOne + @JoinColumns (FK composta), @ManyToOne + @JoinColumn (filho → pai), e quando usar cada — em [references/relationships.md](references/relationships.md).

---

9. Enums (Value Objects)

Enums = valores finitos armazenados no banco como texto curto (geralmente 1 caractere).

Estrutura padrão

import lombok.AllArgsConstructor;
import lombok.Getter;

@AllArgsConstructor
@Getter
public enum NomeEnum {
    OPCAO_UM("V"),
    OPCAO_DOIS("P");

    private final String value;
}

Convenções

| Regra | Detalhe | |:---------------------|:---------------------------------------------------------| | Anotações | @AllArgsConstructor, @Getter | | Campo value | private final String value — valor armazenado no banco | | Nomes das constantes | UPPER_SNAKE_CASE descritivo | | Valores | Strings curtas (1-2 caracteres, geralmente) |

Uso na entidade

…

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.