# Entity

> Cria, revisa e refatora entidades Java `@JapeEntity` Sankhya — Lombok (`@Data`/`@NoArgsConstructor`/`@AllArgsConstructor`), PK simples/composta com `@Embeddable`, `@Column`, `@Id`, `@JoinColumn`, `@OneToMany`/`@OneToOne`/`@ManyToOne`, `@Relationship`, naming `<PRX><MOD3><CTX>`, mapeamento de tipos (`Integer`/`BigDecimal`/`String`/`Boolean`/`Date`/`Timestamp`). Use ao criar, alterar, revisar, audi…

- **Type:** Skill
- **Install:** `agentstack add skill-snk-devcenter-addon-studio-entity`
- **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/entity

## Install

```sh
agentstack add skill-snk-devcenter-addon-studio-entity
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`):

```java
@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).

```java
// 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.

```java

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

### 3.2 PK Composta (`@Embeddable`)

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

```java

@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:**

```java
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.

```java
public class ResultadoCalculo { ...
}

public class DadosConsolidados { ...
}
```

---

## 4. Anatomia de uma Entidade

```java
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

```java

@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 `dataType`s (`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

```java
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](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-entity
- 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%.