291 lines
11 KiB
Markdown
291 lines
11 KiB
Markdown
# Repositório de Conteúdo Vitruvio
|
|
|
|
Um repositório de conteúdo Vitruvio é um repositório Git que declara artefatos de UI (painéis, processos, scripts, relatórios, etc.) através de um único arquivo de manifesto: `vitruvio.json`.
|
|
|
|
## Arquivos obrigatórios
|
|
|
|
| Arquivo | Obrigatório | Descrição |
|
|
|---------|-------------|-----------|
|
|
| `vitruvio.json` | Sim | Manifesto que declara todos os artefatos |
|
|
|
|
Todo o restante (formulários, scripts, BPMNs, etc.) é referenciado via caminhos relativos dentro do manifesto e pode ser organizado livremente.
|
|
|
|
---
|
|
|
|
## vitruvio.json
|
|
|
|
Localizado na **raiz** do repositório. O sistema falhará ao importar o repositório se este arquivo estiver ausente ou inválido.
|
|
|
|
### Campos raiz
|
|
|
|
| Campo | Tipo | Obrigatório | Descrição |
|
|
|-------|------|-------------|-----------|
|
|
| `version` | string | **Sim** | Versão semântica deste manifesto, ex.: `"1.0.0"` |
|
|
| `metadata` | object | **Sim** | Identidade do módulo (ver abaixo) |
|
|
| `panels` | array | Não | Painéis de UI |
|
|
| `processes` | array | Não | Processos BPMN |
|
|
| `scripts` | array | Não | Scripts compartilhados |
|
|
| `endpoints` | array | Não | Endpoints REST |
|
|
| `queries` | array | Não | Queries SQL nomeadas |
|
|
| `reports` | array | Não | Relatórios (estáticos ou dinâmicos) |
|
|
| `libraries` | array | Não | Bibliotecas de arquivos estáticos |
|
|
| `groups` | array | Não | Grupos de usuários para controle de acesso |
|
|
| `properties` | array | Não | Propriedades configuráveis do módulo |
|
|
| `menu` | array | Não | Árvore de navegação do menu |
|
|
| `permissions` | array | Não | Permissões de grupo por processo |
|
|
| `patches` | string | Não | Caminho para o diretório de changesets do Liquibase, ex.: `"patches/"` |
|
|
|
|
### metadata
|
|
|
|
```json
|
|
{
|
|
"name": "My Module",
|
|
"key": "my-module",
|
|
"standardProduct": false
|
|
}
|
|
```
|
|
|
|
| Campo | Obrigatório | Descrição |
|
|
|-------|-------------|-----------|
|
|
| `key` | **Sim** | Identificador único do módulo. Deve ser único em toda a plataforma. |
|
|
| `name` | Não | Nome de exibição legível |
|
|
| `standardProduct` | Não | Marca como produto padrão da plataforma (padrão: `false`) |
|
|
|
|
---
|
|
|
|
## Referência de artefatos
|
|
|
|
### panels
|
|
|
|
Cada entrada de painel corresponde a uma tela de UI.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único do painel |
|
|
| `name` | string | Nome de exibição |
|
|
| `description` | string | Descrição curta |
|
|
| `category` | string | Caminho de categoria hierárquica, ex.: `"Comercial/Vendas"` |
|
|
| `displayOrder` | int | Ordem de exibição dentro da categoria |
|
|
| `showInPresentation` | boolean | Exibir no modo apresentação/kiosk |
|
|
| `openInNewWindow` | boolean | Abrir em uma nova janela do navegador |
|
|
| `showInMobileList` | boolean | Exibir na lista mobile |
|
|
| `displayTimeInSeconds` | int | Tempo de rotação automática (0 = desativado) |
|
|
| `allowedGroups` | string[] | Chaves dos grupos com permissão de visualizar este painel |
|
|
| `allowedUsers` | string[] | Logins dos usuários com permissão de visualizar este painel |
|
|
| `forms.desktop` | string | Caminho relativo para o XML do formulário desktop |
|
|
| `forms.mobile` | string | Caminho relativo para o XML do formulário mobile |
|
|
| `forms.mobileAlternative` | string | Caminho relativo para o XML do formulário mobile alternativo |
|
|
| `defaultState` | string | Caminho relativo para um arquivo JSON com o estado padrão do painel |
|
|
| `thumbnail` | string | Caminho relativo para uma imagem de miniatura |
|
|
|
|
---
|
|
|
|
### processes
|
|
|
|
Fluxos de trabalho baseados em BPMN.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único do processo |
|
|
| `name` | string | Nome de exibição |
|
|
| `description` | string | Descrição curta |
|
|
| `bpmn` | string | Caminho relativo para o arquivo XML do BPMN |
|
|
| `forms.desktop` | string | Caminho relativo para o XML do formulário desktop |
|
|
| `forms.mobile` | string | Caminho relativo para o XML do formulário mobile |
|
|
| `forms.mobileAlternative` | string | Caminho relativo para o XML do formulário mobile alternativo |
|
|
| `schedules` | array | Agendamentos de disparo automático (ver abaixo) |
|
|
|
|
**Tipos de gatilho para agendamento:**
|
|
|
|
```json
|
|
{ "type": "cron", "expression": "0 0 0 * * ?" }
|
|
{ "type": "simple", "intervalMs": 60000, "repeatCount": -1 }
|
|
```
|
|
|
|
`repeatCount: -1` significa repetir indefinidamente.
|
|
|
|
---
|
|
|
|
### scripts
|
|
|
|
Scripts server-side reutilizáveis.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único do script |
|
|
| `name` | string | Nome de exibição |
|
|
| `description` | string | Descrição curta |
|
|
| `language` | string | Linguagem do script, ex.: `"javascript"` |
|
|
| `domain` | string | Classificação: `"NEGOCIO"` ou `"SISTEMA"` |
|
|
| `source` | string | Caminho relativo para o arquivo do script |
|
|
| `documentation` | string | Caminho relativo para o arquivo de documentação opcional |
|
|
|
|
---
|
|
|
|
### endpoints
|
|
|
|
Endpoints HTTP expostos.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único do endpoint |
|
|
| `name` | string | Nome de exibição |
|
|
| `description` | string | Descrição curta |
|
|
| `language` | string | Linguagem do script, ex.: `"javascript"` |
|
|
| `authMode` | string | `"PUBLIC"`, `"MOBILE"` ou `"STATIC_TOKEN"` |
|
|
| `active` | boolean | Se o endpoint está ativo |
|
|
| `source` | string | Caminho relativo para o arquivo do script do endpoint |
|
|
|
|
---
|
|
|
|
### queries
|
|
|
|
Queries SQL nomeadas que podem ser referenciadas por relatórios.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único da query |
|
|
| `name` | string | Nome de exibição |
|
|
| `connection` | string | Chave da conexão com o banco de dados |
|
|
| `source` | string | Caminho relativo para o arquivo `.sql` |
|
|
|
|
---
|
|
|
|
### reports
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único do relatório |
|
|
| `name` | string | Nome de exibição |
|
|
| `description` | string | Descrição curta |
|
|
| `type` | string | `"MODELO_ESTATICO"` ou `"DINAMICO_QUERY_SQL"` |
|
|
| `category` | string | Caminho de categoria hierárquica |
|
|
| `owner` | string | Chave do grupo proprietário do relatório |
|
|
| `template` | string | Caminho relativo para o template `.jrxml` |
|
|
| `parameterForm` | string | Caminho relativo para o XML do formulário de parâmetros |
|
|
| `query` | string | Referencia uma `QueryManifestEntry.key` |
|
|
| `orientation` | string | `"RETRATO"` ou `"PAISAGEM"` |
|
|
| `allowedGroups` | string[] | Chaves dos grupos com permissão de executar este relatório |
|
|
| `allowedUsers` | string[] | Logins dos usuários com permissão de executar este relatório |
|
|
| `columns` | array | Definições de colunas (label, alinhamento, largura, agregação) |
|
|
|
|
**Valores de agregação de coluna:** `"SUM"`, `"COUNT"`, `"AVG"` ou `null`.
|
|
|
|
---
|
|
|
|
### libraries
|
|
|
|
Pacotes de arquivos estáticos servidos para o front-end.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único da biblioteca |
|
|
| `name` | string | Nome de exibição |
|
|
| `type` | string | `"LOCAL"` |
|
|
| `authMode` | string | `"PUBLIC"`, `"MOBILE"` ou `"STATIC_TOKEN"` |
|
|
| `authToken` | string | Obrigatório quando `authMode` for `"STATIC_TOKEN"` |
|
|
| `mobileEnabled` | boolean | Se a biblioteca é servida para clientes mobile |
|
|
| `files` | string | Caminho relativo para o diretório contendo os arquivos da biblioteca |
|
|
|
|
---
|
|
|
|
### groups
|
|
|
|
Grupos de usuários utilizados para controle de acesso em painéis, relatórios e permissões.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único do grupo |
|
|
| `name` | string | Nome de exibição |
|
|
| `description` | string | Descrição curta |
|
|
| `tag` | string | Tag opcional para filtragem |
|
|
|
|
---
|
|
|
|
### properties
|
|
|
|
Propriedades configuráveis no nível do módulo, editáveis em tempo de execução.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Chave da propriedade utilizada no código |
|
|
| `displayName` | string | Label legível |
|
|
| `description` | string | Descrição curta |
|
|
| `type` | string | `"STRING"`, `"INTEGER"`, `"BOOLEAN"`, `"DATE"`, etc. |
|
|
| `size` | int | Tamanho máximo em caracteres (para STRING) |
|
|
| `precision` | int | Precisão decimal (para tipos numéricos) |
|
|
| `format` | string | Máscara de formato opcional |
|
|
| `required` | boolean | Se um valor deve obrigatoriamente ser definido |
|
|
| `password` | boolean | Se o valor deve ser mascarado na UI |
|
|
| `predefinedValues` | array | Valores permitidos: `{ "key": "...", "descricao": "...", "ordem": 1 }` |
|
|
|
|
---
|
|
|
|
### menu
|
|
|
|
Árvore de navegação hierárquica. Itens podem ser aninhados usando `children`.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `key` | string | Identificador único do item de menu |
|
|
| `name` | string | Label de exibição |
|
|
| `icon` | int | Código do ícone (definido pela plataforma) |
|
|
| `order` | int | Ordem de exibição entre os irmãos |
|
|
| `type` | string | `"PANEL"`, `"REPORT"`, `"PROCESS"` ou `"GROUP"` |
|
|
| `panelKey` | string | Referencia uma `PanelManifestEntry.key` (quando type for `"PANEL"`) |
|
|
| `reportKey` | string | Referencia uma `ReportManifestEntry.key` (quando type for `"REPORT"`) |
|
|
| `processKey` | string | Referencia uma `ProcessManifestEntry.key` (quando type for `"PROCESS"`) |
|
|
| `children` | array | Itens de menu aninhados (para o tipo `"GROUP"`) |
|
|
|
|
---
|
|
|
|
### permissions
|
|
|
|
Define o que um grupo pode fazer dentro de um processo.
|
|
|
|
| Campo | Tipo | Descrição |
|
|
|-------|------|-----------|
|
|
| `processKey` | string | Referencia uma `ProcessManifestEntry.key` |
|
|
| `group` | string | Referencia uma `GroupManifestEntry.key` |
|
|
| `read` | boolean | Pode visualizar instâncias do processo |
|
|
| `writeStages` | boolean | Pode avançar/concluir etapas |
|
|
| `cancel` | boolean | Pode cancelar instâncias |
|
|
| `delete` | boolean | Pode excluir instâncias |
|
|
| `stageStatus` | boolean | Pode alterar o status de etapas |
|
|
|
|
---
|
|
|
|
## Estrutura de diretórios sugerida
|
|
|
|
```
|
|
repo-root/
|
|
├── vitruvio.json
|
|
├── panels/
|
|
│ └── my-panel/
|
|
│ ├── my-panel-desktop.xml
|
|
│ ├── my-panel-mobile.xml
|
|
│ ├── default-state.json
|
|
│ └── thumbnail.png
|
|
├── processes/
|
|
│ └── my-process/
|
|
│ ├── my-process.bpmn
|
|
│ ├── my-process-desktop.xml
|
|
│ └── my-process-mobile.xml
|
|
├── scripts/
|
|
│ └── my-script.js
|
|
├── endpoints/
|
|
│ └── my-endpoint.js
|
|
├── queries/
|
|
│ └── my-query.sql
|
|
├── reports/
|
|
│ └── my-report/
|
|
│ ├── template.jrxml
|
|
│ └── params.xml
|
|
├── libraries/
|
|
│ └── my-library/
|
|
└── patches/
|
|
└── changelog.xml
|
|
```
|
|
|
|
Todos os caminhos no `vitruvio.json` devem ser **relativos à raiz do repositório**.
|