victor
95 lines
13 KiB
Markdown
Executable File
95 lines
13 KiB
Markdown
Executable File
# Guia de Autocomplete Copilot – 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 do Copilot 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`, Copilot 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.
|