# 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**.