🔄 AutoDD: Geração Automática do Dicionário de Dados (Data Dictionary)

⚠️

Acesso Antecipado (Beta)

Esta documentação refere-se ao recurso AutoDD do SDK Sankhya, disponível em acesso antecipado. APIs e comportamentos podem mudar. Para feedback, envie para [email protected].

📝 O que é o AutoDD?

O AutoDD (Auto Data Dictionary) é uma feature do SDK Sankhya que gera automaticamente o dicionário de dados XML (data dictionary) a partir das suas entidades Java anotadas com @JapeEntity.

O dicionário de dados é o coração do ORM Jape da Sankhya: todas as entidades precisam ser mapeadas por meio dele para que o framework reconheça tabelas, campos, chaves e relacionamentos.

Com o AutoDD, o desenvolvedor não precisa mais criar manualmente arquivos XML para mapear suas entidades. Basta anotar corretamente a classe com @JapeEntity e as anotações de campo (@Id, @Column, etc.), e o framework gera o XML do dicionário de dados automaticamente durante o build.

O AutoDD não substitui o mapeamento manual de outras features, como views, menus, dashboards, tree tables, filters etc. Ele é focado exclusivamente no mapeamento de Table e NativeTable.

🔗 Relação entre AutoDD e AutoDDL

• AutoDD: Gera o dicionário de dados XML a partir das entidades Java.
• AutoDDL: Converte o dicionário de dados XML (gerado pelo AutoDD ou manualmente) em scripts DDL (CREATE/ALTER) para Oracle/MSSQL.

Essas features são complementares: o AutoDD elimina o trabalho manual de criar o XML, e o AutoDDL elimina o trabalho manual de converter o XML em DDL.

Para usar o fluxo completo, é necessário habilitar ambas as features no build.gradle da raiz do projeto:

addon {
    autoDD = true
    autoDDL = true
}

✨ Benefícios do AutoDD

• ⚡ Agilidade: Não é mais necessário criar XMLs de dicionário de dados manualmente para mapear entidades (views, menus, dashboards etc. ainda precisam ser mapeados manualmente).
• 🎯 Menos erro humano: Reduz falhas comuns de digitação e inconsistências de tipos.
• 📏 Padronização: Garante que o modelo Java e o dicionário de dados estejam sempre sincronizados.
• 🔄 Integração total: Permite uso imediato do AutoDDL para geração de scripts de banco.

⚙️ Como funciona?

1. Defina sua entidade usando @JapeEntity e as anotações de campo (@Id, @Column, etc.).
2. Habilite o AutoDD no build.gradle da raiz.
3. Execute o build do projeto (ex.: ./gradlew clean deployAddon).
4. O AutoDD processa as entidades e gera automaticamente o XML de dicionário de dados na pasta de build.
5. (Opcional) Se o AutoDDL estiver habilitado, o XML gerado será convertido em scripts SQL DDL para Oracle/MSSQL.

💡 Exemplo prático

1. Entidade simples

@Data
@NoArgsConstructor
@JapeEntity(entity = "TST_MinhaClasse", table = "TST_MINHA_CLASSE", description = "Minha Classe Exemplo")
public class MinhaClasse {

    @Id
    @GeneratedValue(strategy = GeneratedValue.GenerationType.AUTO)
    @Column(name = "ID", dataType = DataType.INTEGER, description = "Id")
    private Long id;

    @Column(name = "MSG", dataType = DataType.TEXT, description = "Mensagem")
    private String mensagem;

    @Column(name = "OUTRO_FIELD", dataType = DataType.INTEGER, description = "Outro Campo")
    private Long outroField;
}

2. Entidades com relacionamentos

O AutoDD mapeia relacionamentos entre entidades usando @JoinColumn (para PK simples) ou @JoinColumns (para PK composta).

Exemplo: relacionamento com PK simples

@Data
@NoArgsConstructor
@JapeEntity(entity = "TST_MinhaClasse", table = "TST_MINHA_CLASSE", description = "Minha Classe Exemplo")
public class MinhaClasse {

    @Id
    @GeneratedValue(strategy = GeneratedValue.GenerationType.AUTO)
    @Column(name = "ID", dataType = DataType.INTEGER, description = "Id")
    private Long id;

    @Column(name = "MSG", dataType = DataType.TEXT, description = "Mensagem")
    private String mensagem;

    @OneToMany(
        cascade = Cascade.ALL,
        orphanRemovalStrategy = OrphanRemovalStrategy.DETACH
    )
    private List<MinhaOutraClasse> itens;
}

@Data
@NoArgsConstructor
@JapeEntity(entity = "TST_MinhaOutraClasse", table = "TST_MINHA_OUTRA_CLASSE", description = "Minha Outra Classe Exemplo")
public class MinhaOutraClasse {

    @Id
    @GeneratedValue(strategy = GeneratedValue.GenerationType.AUTO)
    @Column(name = "ID", dataType = DataType.INTEGER, description = "Id")
    private Long id;

    @Column(
        name = "STATUS",
        dataType = DataType.LIST,
        description = "Status",
        options = {
            @Option(label = "Ativo", value = "ATIVO"),
            @Option(label = "Inativo", value = "INATIVO")
        }
    )
    private Status status;

    @ManyToOne(cascade = Cascade.MERGE)
    @JoinColumn(
        name = "MINHA_ENTIDADE_ID",
        referencedColumnName = "ID",
        dataType = DataType.INTEGER,
        description = "Referência para MinhaClasse"
    )
    private MinhaClasse minhaClasse;
}

3. Tabelas e instâncias nativas

É possível mapear uma instância e tabela nativa do Sankhya utilizando os atributos isNativeTable e isNativeInstance na anotação @JapeEntity.

@Data
@AllArgsConstructor
@NoArgsConstructor
@JapeEntity(
    entity = "TST_InstanciaCustomizadaUsuarios",
    table = "TSIUSU",
    description = "Instância Customizada de Usuários",
    isNativeTable = true,
    isNativeInstance = false
)
public class InstanciaCustomizadaUsuarios {

    @Id
    @Column(name = "CODUSU", description = "Código do Usuário", dataType = DataType.INTEGER)
    private Long codUsuario;

    @Column(name = "NOMUSU", description = "Nome do Usuário", dataType = DataType.TEXT)
    private String nomeUsuario;
}

📋 Boas práticas

• Use prefixos exclusivos para tabelas e entidades (ex.: SGT_, LOG_).
• Nunca use o prefixo AD_ (reservado pelo sistema).
• Sempre revise os scripts antes de aplicar em ambientes produtivos.