sankhya-modulo-java

Skill para Claude Code especializada em desenvolvimento de módulos Java complementares para o ERP Sankhya OM — sem Addon Studio, com registro manual de artefatos.

---

O que esta skill faz

Transforma o Claude em um especialista em módulos Java Sankhya OM, capaz de:

• Criar EventoProgramavelJava (eventos CRUD em entidades)
• Criar AcaoRotinaJava (botões de ação manuais)
• Criar RegraNegocioJava / Regra (lógica no ciclo de confirmação/faturamento)
• Criar ScheduledAction (jobs agendados via Cuckoo)
• Estruturar as camadas service, repository, exception e dto
• Gerar XML do Construtor de Telas (criação de tabelas e telas via metadados)
• Criar popups personalizados via PopUpBuilder (confirmação, seleção em grid, formulário, wizard)
• Seguir os antipadrões proibidos e boas práticas da plataforma

---

Estrutura da Skill

sankhya-modulo-java/
├── SKILL.md Instruções principais da skill
├── README.md Este arquivo
│
├── instructions/
│ └── encoding-instructions.md ISO-8859-1 obrigatório — regras e comandos de conversão
│
├── evals/
│ └── evals.json Casos de teste para avaliação da skill
│
├── examples/ Templates Java prontos para copiar
│ ├── Modelo_ActionButton.java AcaoRotinaJava — valida UI, abre sessão, delega para component/
│ ├── Modelo_Event.java EventoProgramavelJava com 7 métodos, delega para component/
│ ├── Modelo_Job.java ScheduledAction — abre sessão, delega para component/
│ ├── Modelo_RegraNegocio.java RegraNegocioJava completo
│ ├── Modelo_RegraPreferencia.java Interface Regra via preferência
│ ├── Modelo_Service.java Service — regras puras sem acesso a banco
│ ├── Modelo_Repository.java Repository — acesso a dados para entidades AD_*
│ ├── Modelo_Exception.java Exceção de domínio com códigos rastreáveis [MOD_NNNN]
│ ├── Modelo_Dto.java DTO com construtor a partir de DynamicVO
│ ├── Modelo_JapeHelper.java Gerência de sessão e transação
│ ├── Modelo_PopUpHelper.java Popup via PopUpBuilder
│ └── PopUpBuilder.java Utilitário não nativo — copiar para utils/
│
├── assets/
│ └── popup/ Templates HTML/JS de popup
│ ├── PopUpConfirmacao.html / .js
│ ├── PopUpSelecao.html / .js
│ ├── PopUpFormulario.html / .js
│ ├── PopUpDetalhes.html / .js
│ └── PopUpWizard2Paginas.html / .js
│
└── references/ Documentação técnica detalhada
├── estrutura-modulo.md Pacotes, diretórios, build.gradle, deploy
├── event-java.md EventoProgramavelJava, padrões, ModifyingFields
├── action-button.md AcaoRotinaJava, ContextoAcao, padrões
├── component.md Component — orquestração, padrões por artefato
├── controller.md Controller — endpoint REST/serviço, registro manual
├── service-repository.md Service (puro), Repository, Exception, DTO
├── regra-negocio.md RegraNegocioJava, Regra, ScheduledAction
├── acesso-dados.md JapeFactory, DwfUtils, EntityFacade, JdbcWrapper
├── nativesql-assertivo.md NativeSql utilitários, MapUtils, IN chunking — quando JAPE não resolve
├── boas-praticas.md Erros, logging, transações, performance, lote, EntityFacade, máquina de estados
├── logger.md Logger (br.com.sankhya.utils.Logger), níveis, exemplos
├── entidades-sistema.md DynamicEntityNames, campos TGFCAB/TGFITE/TGFFIN
├── construtor-de-telas.md XML de metadados, campos, relacionamentos
├── popup-personalizado.md PopUpBuilder, HTML/JS, Angular, regras críticas
├── sankhyautil.md StringUtils, TimeUtils, SQLUtils, JsonUtils e outros
├── comercial-notas.md CACHelper, ImpostosHelpper, CentralFinanceiro, confirmar nota
├── organizacao-pacotes-java.md Conflitos de ClassLoader, segmento nomedemanda obrigatório
├── clean-code-metodos.md Nomes, tamanho, return early, SRP, efeitos colaterais
└── clean-code-variaveis.md Nomes, constantes, booleanos, escopo, convenções Sankhya

---

Arquitetura de Camadas

br.com.sankhya.dstech.
nomedemanda/
actionbutton/ ← AcaoRotinaJava — validação de UI, abre sessão, delega para component/
component/ ← Hub obrigatório — orquestra service/ e repository/; chamado por todos os artefatos
controller/ ← Endpoint REST/serviço via ServiceProvider manual — delega para component/
event/ ← EventoProgramavelJava — extrai VO, delega para component/
job/ ← ScheduledAction — abre sessão, delega para component/
regra/ ← RegraNegocioJava / Regra — delega para component/
service/ ← Regras de negócio puras — cálculos, validações; sem acesso a banco
repository/ ← Acesso a dados — entidades AD_* e queries nativas via NativeSql
exception/ ← Exceções de domínio com código rastreável [MOD_XXXX]
dto/ ← Transferência de dados entre camadas
enums/ ← AdicionalEntityNames, StatusXxx, TipoXxx
helper/ ← Helpers de apresentação (PopUpHelper) compartilhados na demanda
utils/ ← DwfUtils (consultas genéricas), MessageUtils (feedback ao usuário)

Para entidades nativas (TGFCAB, TGFPAR, TGFPRO, etc.) o component/ acessa JapeFactory ou DwfUtils diretamente — sem repository/ dedicado. O repository/ customizado é focado em entidades AD_* e queries que precisam de NativeSql.

SQL complexo: arquivos .sql ficam em Java/resources/sql/ e são carregados via getResourceAsStream("/sql/nome-query.sql") no repository/.

---

Módulo Java vs. Addon Studio

Aspecto	Módulo Java	Addon Studio
Registro de artefatos	Manual via UI do Sankhya	Automático via anotações
Eventos	EventoProgramavelJava (manual)	@Listener (automático)
Botões de ação	AcaoRotinaJava (manual)	@ActionButton (automático)
Jobs agendados	ScheduledAction org.cuckoo.core	@Job (automático)
Regras de negócio	RegraNegocioJava / Regra (manual)	@BusinessRule (automático)
Frontend	Popups via PopUpBuilder	xhtml5, SankhyaJS, Design System
Telas/Tabelas	XML Construtor de Telas (manual)	datadictionary/ (deploy automático)
Build	Gradle → JAR → importação manual	Gradle → deploy automático
Pacote raiz	br.com.sankhya.dstech	br.com.empresa.addon

---

Licença

Uso interno — DSTech Soluções.