vscode-ia/CLAUDE.md

Workspace Rules

Este workspace utiliza agentes especializados.

Regra principal

1. Para tarefas do ecossistema DavinTI Vitruvio em /davinti, use vitruvio-specialist como agente principal sempre.
2. O vitruvio-specialist decide quando delegar para os agentes especializados de banco, mobile, libs, paineis, processos, relatorios e webservices.
3. Nao carregue nem force contexto de todos os agents ao mesmo tempo; delegue apenas quando o escopo estiver claramente isolado.

Comportamento esperado

6. Priorize respostas produzidas pelo agente mais adequado ao dominio da tarefa.
7. Se a solicitacao for simples e ja estiver no agente correto, nao faca delegacao desnecessaria.

Guia de Autocomplete – DavinTI / Vitruvio

Visão geral

• Repositório de soluções Vitruvio.
• Arquivos principais: scripts JavaScript (orquestração e widgets Vitruvio), formulários XML (*_web_desktop, _mobile, .bpmn) e PL/SQL (PRC_VTR_*, VI_VTR_*).
• Bancos Oracle usados nas integrações: vitruvio_producao, superus_producao, davinti_producao, entre outros.
• Sempre adicionar comentários nas alterações no padrão: -- CASO [número] - [usuario] - [Data] - [breve descrição da mudança].
  • Exemplo: -- CASO 32715 - Victor da Cruz - 15-09-2024 - Ajuste na query de validação de estoque para considerar reservas.
    • Use o número do caso para rastrear o histórico da demanda e facilitar consultas futuras, se não existir deixar XXX.

JavaScript Rhino (Vitruvio)

• Runtime Rhino: scripts de processo/form usam Rhino JavaScript (ECMAScript 5). Declarar variáveis sempre com var; const e let não são suportados. Métodos de array como map, forEach, filter, reduce, indexOf funcionam normalmente.
• Interop Java: Rhino permite instanciar classes Java (new java.util.ArrayList(), java.lang.String). Utilize quando precisar de coleções Java ou interoperar com APIs da plataforma.
• **Compatibilidade: **: Validações de valores de classes e métodos do Java em Rhino com 3 iguais(===) ou 3 diferentes (!==) não funcionam corretamente. Use sempre 2 iguais (==) ou 2 diferentes (!=).
• APIs padrão: engine, execution, vFormService, sendMessageToVitruvio, db, taskService, vProcessInstanceService. Scripts carregam libs via libService.loadScript('db'|'javadateutils'|'lib_valor_config'|'processo_util'|'util'|'threads'|'notification'|'email'|...). Sugira helpers recorrentes como db.queryRow(sql, params), db.query(sql, params).each(function (row) { ... }), db.transaction(function () { ... }), sprDB.executeProcedure(nome, parametros), sprDB.update(sql, params), processoUtil.alterarDescricaoProcesso, threads.execute(function () { ... }), util.isEmptyOrNull, notification.criarNotificacao, sendMessageToVitruvio({ ... }).
• Consultas: db.query retorna null quando não há linhas; se o objeto existir, já há ao menos um registro e deve ser percorrido com lista.each(...) (não utilizar size).
• Padrões de string/SQL: template strings não funcionam. Monte blocos com concatenação incremental (var sql = " SELECT ..."; sql += " FROM ..."; sql += " WHERE ...";), respeitando identação com espaços à esquerda (sql += " AND campo = :param";). Para HTML siga o mesmo padrão (var html = ''; html += '<div>...';). reforco_abastecimento.js mostra var sql = ""; sql += ...; somado a db.queryRow, sprDB.update e construção de params para executeProcedure com objetos { input: [{ name: 'ParChaveOrigem', type: 'number', value: ... }], output: [...] }.
• Estrutura: organize helpers internos (formatação de data, filtros, builders de HTML) antes das funções expostas (this.metodo = function () { ... }). Comentários curtos ajudam a documentar regras específicas. Use JSON.stringify/JSON.parse para guardar estado em tb_state_panels ou variáveis do processo.
• Dashboards/Widgets: replique padrões de function AbastecimentoDashboardDados() {.js (arrays ordersColumns, showBySigle, toggles HTML com sendMessageToVitruvio). Respeite colunas padrão (SECOS, CONGELADOS, PESÁVEIS, REFORÇO, FRUTAS_SECAS, PULMAO_DOCA).
• React Native (pricetotem/): único módulo fora do Rhino; quando necessário consulte o código existente em App.tsx e src/**, mas mantenha este guia focado em Rhino + Oracle.

WebServices Vitruvio

• Artefatos exportados de vitruvio.script_ws_endpoint ficam em Vitruvio/WebServices/ e seguem runtime Rhino ES5.
• Estrutura recorrente: function WebService() { this.onGet = function (...) { ... }; this.onPost = function (...) { ... }; } module.exports = new WebService();.
• Em GET, os parâmetros costumam vir de params.query; em POST JSON, o padrão mais comum do acervo é JSON.parse(params.requestBody).
• Para respostas JSON, prefira helper local como enviarJson ou sendResponse, com res.setStatus(...), res.setContentType('application/json; charset=UTF-8'), res.getWriter().write(JSON.stringify(obj)) e flush().
• Para download ou binário, preserve Content-Type, Content-Disposition, Content-Length quando aplicável e streaming via res.getOutputStream().
• Valide entrada antes de acessar filesystem ou banco; ao lidar com nomes de arquivo, bloquear path traversal (.., /, \\) e caracteres inválidos.
• Preserve contrato HTTP existente do endpoint: método, parâmetros, shape do JSON e status codes (200, 400, 404, 500) não devem mudar sem necessidade explícita.

Relatórios Jasper e iReport 5.6

• Artefatos exportados de vitruvio.relatorio ficam em Vitruvio/Relatorios/<Nome do Relatório>/, contendo jasper_template.jrxml e, quando existir, form_parametros.xml.
• form_parametros.xml é um report-form, não um formulário comum; pode conter widgets, filtros, scripts CDATA e botões que chamam vReportService.generateReportFile(...).
• Preserve compatibilidade com Jasper iReport 5.6: evite migrações de schema, reformatadores agressivos ou mudanças estruturais fora do necessário.
• Nomes e caixa dos parâmetros devem permanecer alinhados entre campos da tela, mapa Java (params.put(...)), expressões $P{...}, filtros $X{IN,...} e datasets do JRXML.
• Parâmetros comuns no acervo: java.util.Date, java.util.Collection, java.lang.String, java.lang.Long, java.lang.Integer e java.io.InputStream para logos.
• Quando o relatório for disparado por script, preserve os padrões de Formato.PDF, Formato.XLSX, downloadutil.downloadFile ou download.openFileNewWindow já adotados no acervo.
• Ajustes em SQL do JRXML devem continuar parametrizados; evite converter filtros do Jasper para concatenação manual dentro do template.

XML (Formulários Vitruvio)

• Sempre declarar namespace xmlns="http://www.davinti.com.br/vitruvio/form" e schema location oficial na raiz <forms>.
• Estrutura típica: <descriptorScript> (função s() com this.getDescriptor e var script = new s();), <form formKey="...">, <name>, <initScript>, <buttons>, <validators>. Scripts internos usam <![CDATA[ ... ]]> e apenas var.
• Manipule campos com engine.getField('campo').setValue, engine.getLabel('id').setValue, engine.getWidget('id'). Configure globais via engine.setGlobalVariable('nome', funcao); e use execution.getVariable/ setVariable para compartilhar dados.
• Validators seguem padrão function f() { this.isValid = function () { ... return true; }; } var validator = new f();. Use db.transaction(function () { ... this.update(sql, params); }); para inserts/updates, validando resultado e retornando mensagens string quando houver erro.
• Tags recorrentes: <grid columns=""> para layout, <panel>, <input type="text" ...>, <combo>, <label id="lblTitulo">, <button>; reutilize IDs existentes (parComprador, prazo, pedidosGerados).
• Em <bind>, todo <parameter> deve ter defaultValue sempre preenchido (inclusive para string, number e date) para evitar falhas de binding em runtime.
• Construa SQL e HTML dentro de scripts com concatenação incremental (var sql = " SELECT ..."; sql += ...;) e utilize libs carregadas (var banco = new db('superus_producao');, var data = libService.loadScript('javadateutils');).
• Ao gerar scripts dentro das tags XML, siga rigorosamente os padrões de JavaScript Rhino descritos na seção anterior. Como a estrutura é integrada ao Java, priorize scripts pequenos, legíveis e objetivos, evitando validações redundantes. Não é necessário validar a existência de campos ao utilizar engine.getField(), pois campos presentes em tela sempre serão retornados. Da mesma forma, getValue() retorna null quando o campo não está preenchido, permitindo a definição de valores padrão diretamente com o operador ||.

PL/SQL (Oracle)

• Procedures e functions seguem prefixo PRC_VTR_/FNC_ com parâmetros nomeados. Cabeçalhos usam CREATE OR REPLACE PROCEDURE e declarações NUMBER(14,4).
• Sempre trate exceções com EXCEPTION WHEN NO_DATA_FOUND THEN .... Use cursores explícitos apenas quando necessário; preferir SELECT ... INTO com NVL e CASE.
• Funções auxiliares internas (FNC_MEDIA_REGISTROS_PDV, FNC_QTD_TIPO_EMB) devem ser definidas no corpo da procedure principal, replicando padrões do arquivo PRC_VTR_CONTROLE_SUGESTAO.sql.
• Use schemas explícitos (VITRUVIO.TB_ABAST_AGRUP_DISP_PANEL, RESTaurante.SOCIN_DETALHES_CUPOM). Parâmetros OUT devem ser preenchidos antes de commit.
• Comentários com histórico (-- Caso 32715 - Victor da Cruz) são comuns; mantenha o formato ao adicionar novos registros.

Estrutura de diretórios (referência rápida)

• Reforço abastecimento/: XML e JS de reforço promocional; integra com reforco_abastecimento BPMN.
• Abastecimento - Ressuprimentos/: layouts e reforco_abastecimento.js; subpasta termo de aceite/ guarda assets PNG para documentação.
• PCP - Grill - 43217/ e PCP DRE - Perdas - 44371/: procedures Oracle (PRC_VTR_PCP_*), relatórios Jasper (.jrxml) e scripts de planejamento.
• Recebimento - Tolerância - 44857/: recebimento_mercadorias.js e XML mobile (Recebimento_de_Mercadorias_1.05_mobile_alt.xml).
• Importação ... pastas: fluxos BPMN e arquivos XML (Importa_o_1.25_web_desktop*.xml) com scripts de validação.
• Concluidos/: histórico de demandas; usar como referência de código legado ao construir novas features.
• Vitruvio/: pasta raiz para artefatos exportados e organizados por tipo.
• Vitruvio/Libs/: scripts .js exportados de vitruvio.script_lib; cada subpasta pode ser carregada em runtime com libService.loadScript('sigla'), usando a sigla (nome da pasta) em minúsculo para reaproveitar funções nos scripts.
• Vitruvio/WebServices/: endpoints .js exportados de vitruvio.script_ws_endpoint; ao revisar integrações REST públicas, considere esta pasta como parte da base exportada.
• Vitruvio/Paineis/: painéis XML exportados de vitruvio.painel.
• Vitruvio/Processos/: processos exportados de vitruvio.processo_versao (BPMN e formulários web/mobile).
• Vitruvio/Relatorios/: relatórios exportados de vitruvio.relatorio; cada relatório fica em uma subpasta própria contendo jasper_template.jrxml e, quando existir, form_parametros.xml.
• Vitruvio/Documentacao/: documentação de referência para contexto com custo reduzido.
• Vitruvio/Documentação/Componentes/: documentação base por componente em arquivos .ts.

Documentação operacional (prioridade de contexto)

• Priorize consultas aos arquivos em Vitruvio/Documentação/ antes de sugerir implementações novas.
• Fontes principais:
  • Vitruvio/Documentação/eventos-vitruvio.md
  • Vitruvio/Documentação/queries-padroes.md
  • Vitruvio/Documentação/Componentes/*.ts
• Objetivo: manter respostas consistentes, curtas e com menor custo de contexto.
• Ao identificar padrão novo validado em produção, atualize a documentação correspondente.

Convenções gerais

• Datas: manipular com libService.loadScript('javadateutils') e formatar DD/MM/YYYY (TO_DATE(:data, 'DD/MM/YYYY')).
• HTML embutido: estilização inline simples; evite bibliotecas externas. Use classes utilitárias (.table-scroll, .meu-botao).
• Nomes de variáveis: seguir português/portuguese (e.g., quantidade, comprador, lojasSelecionadas).
• Bancos múltiplos: quando usar duas conexões, instanciar com nomes distintos (var vitruvio = new db('vitruvio_producao'); var superus = new db('superus_producao');).
• Dados persistidos: estados salvos em tb_state_panels, PEDIDOS_VITRUVIO, PROCESSO_INSTANCIA devem ser serializados com JSON.stringify e recuperar via JSON.parse.

Como usar

• Ao pedir sugestões para arquivos .js, priorizar padrões descritos acima e tabelas mencionadas.
• Para formulários .xml, deve montar skeletons completos com blocos descriptorScript, form, initScript, validators e scripts CDATA embutidos seguindo os exemplos citados.
• Em .sql, manter formato Oracle clássico, com identação de 3 espaços e palavras-chave em maiúsculas; reutilizar nomes de colunas/tabelas existentes.
• Quando houver dúvida sobre componente/evento/query, usar primeiro os guias de Vitruvio/Documentacao/.
• Na exportação unificada da base do Vitruvio, considere sempre os cinco blocos principais do ZIP: Paineis/, Libs/, WebServices/, Processos/ e Relatorios/; qualquer script de sincronização local deve preservar todos eles.