ranbot-ai/sankhya-dashboard-html-jsp-custom-best-pratices

sankhya-dashboard-html-jsp-custom-best-pratices

Purpose

To provide a consolidated guide of patterns and best practices for creating and maintaining dashboards, SQL queries, BI parameterization, and UI/UX within the Sankhya ecosystem (JSP/HTML/Java).

When to Use This Skill

This skill should be used when:

• The user asks about "boas praticas do sankhya" or "Sankhya best practices".
• The user mentions "dashboard sankhya" or is working on a Sankhya BI dashboard.
• The user asks for anything related to the word "Sankhya".
• The user wants to create or modify code files for Sankhya dashboards.

Core Capabilities

1. Code Generation & Review: Apply JSP/JSTL patterns and server-side organization to reduce compilation errors and rendering failures.
2. Visual Consistency: Standardize visual identity in BI components using predefined CSS tokens.
3. Database Exploration: Structure data exploration queries for performance and correct mapping of Sankhya entities.
4. BI Construction Guide: Use the HTML5 component flow in BI to ensure correct rendering, reactivity, and navigation.

Patterns

Melhores Práticas de Código

Aplicar padrões de JSP/JSTL e organização server-side para reduzir erros de compilação, falhas de renderização e regressões em dashboards/telas.

Diretrizes de implementação

• Declarar diretivas JSP e taglibs obrigatórias no topo do arquivo.
• Forçar isELIgnored="false" para habilitar ${...} em tempo de renderização.
• Preferir core_rt para JSTL core no ecossistema Sankhya.
• Evitar scriptlets Java em JSP; usar JSTL (c:if, c:choose, c:forEach).
• Modularizar lógica de negócio (camadas/serviços), evitando acoplamento em arquivo único.
• Evitar hardcode de credenciais, URLs sensíveis e tokens.
• Modelar estado global da UI (dados, filtros, ordenação, aba ativa) e resetar estado antes de novo carregamento.
• Persistir preferências de visualização no localStorage (ordem de colunas e ordenação).
• Implementar carregamento sob demanda para abas/modais pesados (lazy-load) para reduzir tempo inicial.
• Blindagem de Parâmetros: Sempre definir um valor padrão (fallback) para parâmetros de URL via c:set para evitar Erro 500 no servidor Java do Sankhya.
• Separação de Camadas (JSP vs JS): Evitar injetar tags JSP diretamente dentro de blocos <script>. Utilizar containers HTML ocultos para passar dados ao JavaScript, mantendo a saúde do editor de código (IDE Linting).

Os nomes de tabelas e campos abaixo são representativos e podem variar conforme a implementação da instância.

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8" isELIgnored="false" %>
<%@ taglib prefix="snk" uri="/WEB-INF/tld/sankhyaUtil.tld" %>
<%@ taglib uri="http://java.sun.com/jstl/core_rt" prefix="c" %>
<%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %>
<snk:load />

Carregamento de assets em dashboard/gadget

• Referenciar arquivos com contextPath + BASE_FOLDER.
• Em níveis secundários (openLevel), manter caminho absoluto para evitar quebra de resolução.

<script src="${pageContext.request.contextPath}/${BASE_FOLDER}/js/app.js"></script>
<link rel="stylesheet" href="${pageContext.request.contextPath}/${BASE_FOLDER}/css/style.css" />

Consumo seguro de snk:query

• Iterar em query.rows (não no objeto raiz).
• Testar vazio com empty query.rows.

<snk:query var="qDados">
    SELECT CAB.NUNOTA, CAB.CODPARC
      FROM TGFCAB CAB
</snk:query>

<c:choose>
    <c:when test="${empty qDados.rows}">
        <span>Sem resultados</span>
    </c:when>
    <c:otherwise>
        <c:forEach var="linha" items="${qDados.rows}">
            ${linha.NUNOTA}
        </c:forEach>
    </c:otherwise>
</c:choose>

Sanitização de parâmetros antes da SQL

• Normalizar valor de entrada.
• Remover aspas (" e ") antes de injetar em query.
• Definir fallback seguro para evitar SQL inválida.

<c:set var="raw_codusu" value="${empty param.P_CODUSU ? '0' : param.P_CODUSU}" />
<c:set var="codusu_limpo" value="${fn:replace(raw_codusu, '\"', '')}" />
<c:set var="codusu_limpo" value="${fn:replace(codusu_limpo, '&quot;', '')}" />
<c:set var="codusu_seguro" value="${empty codusu_limpo ? '0' : codusu_limpo}" />

<snk:query var="qAcessos">
    SELECT CODUSU, NOMEUSU
      FROM TSIUSU
     WHERE CODUSU = :codusu_seguro
</snk:query>

Estado de tela e lazy-load em dashboard único

• Definir listas globais para reutilização em KPI, gráfico, tabela e modais.
• Guardar flag de carregamento por aba para evitar reconsultas desnecessárias.
• Recarregar dados e reabrir o contexto (produto/aba) após atualização transacional.

var dadosGlobais = [];
var produtoAtual = null;
var abaCarregada = {};

function abrirDetalhe(dado) {
  produtoAtual = dado;
  abaCarregada = {};
  trocarAba("estoque");
}

function trocarAba(aba) {
  if (aba === "estoque" && !abaCarregada.estoque) carregarAbaEstoque(produtoAt