@oondemand/create-central-oon 0.3.39 → 0.3.41

package/docs/BACKEND_DOMAIN_MANIFEST.md

@@ -0,0 +1,411 @@
+# Manifesto declarativo de domínio — `central.domain.json`
+
+O arquivo `central.domain.json`, localizado na raiz do backend da Central, declara models, campos, fórmulas e validações sem exigir um arquivo JavaScript por model.
+
+O OonCore carrega o manifesto durante o bootstrap, antes de carregar `src/models`, `src/validations`, `src/triggers` e os demais diretórios de extensão.
+
+> A Central declara o domínio e as regras. O OonCore constrói schema Mongoose, metadata, CRUD, cálculos protegidos e validações.
+
+## Escopo da versão 1
+
+O contrato cobre:
+
+- identidade do manifesto;
+- models e seus caminhos de API;
+- configuração de CRUD já aceita por `defineModel`;
+- campos primitivos, enumerações, referências e moedas;
+- obrigatoriedade, valor padrão, busca, unicidade e índice simples;
+- limites numéricos e de tamanho de texto;
+- campos somente leitura protegidos nas mutações HTTP;
+- campos calculados no servidor;
+- dependências entre campos calculados, ordenadas automaticamente;
+- precisão e tratamento de valores ausentes em fórmulas;
+- validações declarativas entre campos, com condição opcional;
+- validação estrutural com todos os problemas retornados em uma única exceção.
+
+Ainda não fazem parte desta versão:
+
+- índices compostos;
+- triggers e transições declarativas;
+- migrações automáticas de dados;
+- mappings de integração;
+- funções JavaScript embutidas no JSON.
+
+As expressões são interpretadas por um avaliador fechado. O Core não usa `eval`, `Function` ou execução de código vindo do manifesto.
+
+## Exemplo financeiro
+
+```json
+{
+  "name": "Central SS Eventos",
+  "slug": "ss-eventos",
+  "schemaVersion": 1,
+  "models": [
+    {
+      "name": "ProjetoItem",
+      "singular": "item",
+      "basePath": "/itens",
+      "crud": {
+        "enabled": true
+      },
+      "fields": {
+        "quantidade": {
+          "kind": "number",
+          "required": true
+        },
+        "diarias": {
+          "kind": "number",
+          "required": true
+        },
+        "valorUnitario": {
+          "kind": "currency",
+          "required": true
+        },
+        "percentualFee": {
+          "kind": "number",
+          "default": 0
+        },
+        "valorContratado": {
+          "kind": "currency",
+          "default": 0
+        },
+        "valorPago": {
+          "kind": "currency",
+          "default": 0
+        },
+        "statusIntegracao": {
+          "kind": "string",
+          "readonly": true
+        },
+        "subtotal": {
+          "kind": "currency",
+          "computed": {
+            "precision": 2,
+            "expression": {
+              "op": "multiply",
+              "args": [
+                { "field": "quantidade" },
+                { "field": "diarias" },
+                { "field": "valorUnitario" }
+              ]
+            }
+          }
+        },
+        "valorFee": {
+          "kind": "currency",
+          "computed": {
+            "precision": 2,
+            "expression": {
+              "op": "divide",
+              "args": [
+                {
+                  "op": "multiply",
+                  "args": [
+                    { "field": "subtotal" },
+                    { "field": "percentualFee" }
+                  ]
+                },
+                { "value": 100 }
+              ]
+            }
+          }
+        },
+        "total": {
+          "kind": "currency",
+          "computed": {
+            "precision": 2,
+            "expression": {
+              "op": "add",
+              "args": [
+                { "field": "subtotal" },
+                { "field": "valorFee" }
+              ]
+            }
+          }
+        }
+      },
+      "validations": [
+        {
+          "name": "pagamento-limitado-ao-contratado",
+          "code": "PAGAMENTO_ACIMA_CONTRATADO",
+          "field": "valorPago",
+          "message": "O valor pago não pode superar o valor contratado.",
+          "assert": {
+            "op": "lte",
+            "args": [
+              { "field": "valorPago" },
+              { "field": "valorContratado" }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Estrutura principal
+
+| Propriedade | Obrigatória | Descrição |
+|---|---:|---|
+| `name` | sim | Nome legível da declaração de domínio. |
+| `slug` | não | Identificador em minúsculas, números e hífens. |
+| `schemaVersion` | sim | Nesta versão, deve ser `1`. |
+| `models` | sim | Lista não vazia de models. |
+
+## Model
+
+| Propriedade | Obrigatória | Descrição |
+|---|---:|---|
+| `name` | sim | Nome PascalCase usado no registry e no Mongoose. |
+| `singular` | não | Nome singular usado pelo Core. |
+| `basePath` | não | Caminho iniciado por `/`. |
+| `crud` | não | Mesmo contrato aceito por `defineModel`. |
+| `options` | não | Opções JSON compatíveis com o schema Mongoose. |
+| `fields` | sim | Objeto com pelo menos um campo. |
+| `validations` | não | Lista de regras declarativas executadas depois dos cálculos. |
+
+Não declare a mesma model no manifesto e em `src/models`. O registry interrompe o bootstrap para impedir duas fontes de verdade.
+
+## Tipos de campo
+
+- `string`
+- `number`
+- `boolean`
+- `date`
+- `ref`
+- `enum`
+- `currency`
+- `currencyCode`
+- `currencyConverted`
+
+### Opções comuns
+
+- `label`: rótulo para metadata e frontend;
+- `description`: explicação funcional;
+- `required`: campo obrigatório;
+- `default`: valor padrão JSON;
+- `readonly`: campo controlado pelo servidor;
+- `searchable`: inclui texto na busca derivada do Core;
+- `unique`: índice único simples;
+- `index`: índice simples;
+- `computed`: fórmula declarativa para campos numéricos ou monetários.
+
+### Opções por tipo
+
+- textos: `minLength`, `maxLength`;
+- números e moedas: `min`, `max`;
+- `ref`: `ref` com o nome da model relacionada;
+- `enum`: `values` com textos únicos e não vazios;
+- `currencyConverted`: `base` com código ISO de três letras.
+
+## Campos calculados
+
+`computed` é permitido em `number`, `currency` e `currencyConverted`.
+
+```json
+{
+  "kind": "currency",
+  "computed": {
+    "expression": {
+      "op": "multiply",
+      "args": [
+        { "field": "quantidade" },
+        { "field": "valorUnitario" }
+      ]
+    },
+    "precision": 2,
+    "nullAsZero": true
+  }
+}
+```
+
+| Propriedade | Padrão | Descrição |
+|---|---:|---|
+| `expression` | — | Expressão obrigatória. |
+| `precision` | `2` | Casas decimais, entre 0 e 8. |
+| `nullAsZero` | `true` | Trata campos ausentes ou vazios como zero nas operações numéricas. |
+
+Campos calculados:
+
+- são automaticamente `readonly`;
+- recebem `immutable` no schema Mongoose;
+- são recalculados no backend em criação, edição, patch e importação;
+- são calculados em ordem de dependência;
+- não podem formar ciclos;
+- aparecem na metadata com `readonly: true` e a declaração `computed`.
+
+## Expressões
+
+Uma expressão declara exatamente um destes nós:
+
+```json
+{ "value": 100 }
+```
+
+```json
+{ "field": "valorUnitario" }
+```
+
+```json
+{
+  "op": "multiply",
+  "args": [
+    { "field": "quantidade" },
+    { "field": "valorUnitario" }
+  ]
+}
+```
+
+### Operadores aritméticos
+
+- `add`
+- `subtract`
+- `multiply`
+- `divide`
+- `min`
+- `max`
+- `abs`
+- `negate`
+- `coalesce`
+
+### Operadores de comparação
+
+- `eq`
+- `neq`
+- `gt`
+- `gte`
+- `lt`
+- `lte`
+
+### Operadores lógicos e de presença
+
+- `and`
+- `or`
+- `not`
+- `present`
+- `in`
+
+Divisão por zero e valores não numéricos em fórmulas geram `DomainRuleError` com status 422.
+
+## Validações entre campos
+
+As validações rodam depois que o Core consolidou o registro e recalculou todos os campos dependentes.
+
+```json
+{
+  "name": "valor-pago-valido",
+  "code": "PAGAMENTO_ACIMA_CONTRATADO",
+  "field": "valorPago",
+  "message": "O valor pago não pode superar o valor contratado.",
+  "when": {
+    "op": "present",
+    "args": [{ "field": "valorPago" }]
+  },
+  "assert": {
+    "op": "lte",
+    "args": [
+      { "field": "valorPago" },
+      { "field": "valorContratado" }
+    ]
+  }
+}
+```
+
+| Propriedade | Obrigatória | Descrição |
+|---|---:|---|
+| `name` | sim | Identificador único da validação dentro da model. |
+| `message` | sim | Mensagem operacional apresentada ao usuário. |
+| `assert` | sim | Expressão que deve resultar em verdadeiro. |
+| `when` | não | Condição para executar a regra. |
+| `field` | não | Campo associado ao erro. |
+| `code` | não | Código em maiúsculas para tratamento programático. |
+
+Falhas geram `DomainRuleError` com `statusCode: 422`, `code`, `field`, `rule` e detalhes compatíveis com o tratamento de erros do Core.
+
+## Proteção de campos somente leitura
+
+A proteção não depende apenas do frontend.
+
+- valor readonly enviado na criação é rejeitado;
+- alteração de valor readonly é rejeitada;
+- em edição, o mesmo valor pode voltar no payload e é removido antes da persistência;
+- campos calculados podem voltar no payload somente quando coincidem com o resultado calculado pelo servidor;
+- tentativa de adulterar um campo calculado é rejeitada;
+- services recebem somente campos permitidos e os resultados recalculados.
+
+Isso permite formulários que enviam o registro completo sem abrir espaço para alterar totais, status técnicos ou identificadores controlados pelo sistema.
+
+## Atualizações parciais
+
+Em `PUT` ou `PATCH`, o Core:
+
+1. carrega o registro atual quando existem regras declarativas ou `defineValidation`;
+2. remove ou bloqueia campos readonly;
+3. consolida os campos atuais com as alterações recebidas;
+4. recalcula campos dependentes em ordem;
+5. executa validações declarativas;
+6. executa a validação JavaScript registrada, quando existir;
+7. persiste somente as alterações permitidas e os valores calculados.
+
+A validação JavaScript recebe:
+
+```js
+{
+  op,
+  method,
+  id,
+  current,
+  requestedChanges,
+  changes,
+  consolidated
+}
+```
+
+## Erros de validação do manifesto
+
+Um manifesto estruturalmente inválido lança `DomainManifestError`:
+
+```js
+{
+  name: "DomainManifestError",
+  code: "OON_DOMAIN_MANIFEST_INVALID",
+  statusCode: 422,
+  issues: [
+    {
+      path: "models[0].fields.total.computed.expression",
+      message: "dependência circular entre campos calculados: total -> fee -> total."
+    }
+  ]
+}
+```
+
+A validação agrega os problemas para que o autor corrija o documento em uma única rodada.
+
+## APIs públicas
+
+```js
+const {
+  validateDomainManifest,
+  domainManifestToDefinitions,
+  registerDomainManifest,
+  loadDomainManifest,
+  evaluateDomainExpression,
+  applyDomainMutation,
+  DomainManifestError,
+  DomainRuleError,
+  DOMAIN_EXPRESSION_OPERATORS
+} = require("@oondemand/oon-core-back");
+```
+
+Na operação normal não é necessário chamar essas funções: `oonCore-back start` descobre automaticamente `central.domain.json` e o CRUD aplica as regras.
+
+## Compatibilidade durante a migração
+
+Os diretórios JavaScript continuam disponíveis para regras ainda não declarativas. A ordem é:
+
+1. `central.config.js`;
+2. `central.domain.json`;
+3. diretórios em `src/`.
+
+Isso permite migrar model por model. `defineValidation` continua disponível e roda depois das fórmulas e validações declarativas.

package/docs/CODEX.md

@@ -15,6 +15,7 @@ A fonte de verdade desta documentação é a versão instalada do pacote `@oonde
 
 ### Backend/domínio
 
+- `BACKEND_DOMAIN_MANIFEST.md`
 - `BACKEND_PATTERNS.md`
 - `COLLECTIONS_AND_PIPELINES.md`
 - `CONNECTORS_AND_INTEGRATIONS.md`
@@ -45,6 +46,7 @@ Use estes documentos quando a necessidade envolver:
 ## Princípios obrigatórios
 
 - Escreva apenas o domínio da Central.
+- Use `central.domain.json` para models e campos cobertos pelo contrato declarativo vigente.
 - Use `@oondemand/oon-core-back` para boot, autenticação, RBAC, CRUD, metadata, auditoria e padrões de API.
 - Use `@oondemand/oon-core-front` para shell, rotas, menu, datagrid, formulários, badges, ações e renderização por metadata.
 - Não recrie infraestrutura que já existe no Core.
@@ -53,7 +55,7 @@ Use estes documentos quando a necessidade envolver:
 - Não hardcode tenant, app, usuário, perfil, permissões, URLs sensíveis ou segredos.
 - Não exponha chaves em código, templates ou documentação gerada.
 - Não altere arquivos gerados do Core se houver extensão declarativa disponível.
-- Prefira models, validations, triggers, hooks, mappings, documents, pipelines, integrations e overrides declarativos.
+- Prefira manifestos, validations, triggers, hooks, mappings, documents, pipelines, integrations e overrides declarativos.
 - Antes de criar uma página React customizada, tente resolver com `central.ui.json`, `detailModal`, `form.groups`, `relatedGrid`, `readonlyGrid` e `rowActions`.
 
 ## Ordem de decisão
@@ -61,8 +63,8 @@ Use estes documentos quando a necessidade envolver:
 Ao implementar uma necessidade, siga esta ordem:
 
 1. Configuração existente do Core.
-2. Declaração em `central.config.js` ou `central.ui.json`.
-3. Model, validation, trigger, hook ou mapping no backend da Central.
+2. Declaração em `central.config.js`, `central.domain.json` ou `central.ui.json`.
+3. Validation, trigger, hook ou mapping no backend da Central.
 4. Modal, abas, grid relacionado, ação e renderer declarativos do Core.
 5. Override local pequeno e isolado.
 6. Código customizado somente quando o Core não oferecer extensão adequada.

package/docs/releases/0.3.41.md

@@ -0,0 +1,37 @@
+# OonCore 0.3.41 — Manifesto declarativo de domínio
+
+Versão destinada à homologação do primeiro contrato declarativo completo de domínio no backend.
+
+## Recursos incluídos
+
+- carregamento automático de `central.domain.json`;
+- declaração versionada de models e campos;
+- validação estrutural agregada;
+- fórmulas declarativas sem execução de JavaScript arbitrário;
+- campos calculados no servidor;
+- ordenação de dependências e detecção de ciclos;
+- proteção de campos `readonly` em criação, atualização e importação;
+- validações declarativas entre campos;
+- atualização parcial com consolidação e recálculo;
+- compatibilidade com `defineValidation` durante a migração gradual.
+
+## Objetivo da homologação
+
+Validar o contrato em uma Central de teste antes da conversão dos models e regras da SS-Eventos.
+
+A homologação deve confirmar:
+
+1. criação e carregamento do manifesto;
+2. geração de metadata e CRUD;
+3. recálculo de campos em `POST`, `PUT` e `PATCH`;
+4. rejeição de adulteração em campos controlados pelo servidor;
+5. mensagens de validação associadas ao campo correto;
+6. compatibilidade com models e validações JavaScript ainda não migrados.
+
+## Fora do escopo
+
+- fórmulas reativas no frontend;
+- índices compostos;
+- triggers e transições declarativas;
+- engine genérica de integrações;
+- migração da SS-Eventos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.3.39",
+  "version": "0.3.41",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/templates/_base/backend/package.json

@@ -12,6 +12,6 @@
     "deploy": "oonCore-back deploy"
   },
   "dependencies": {
-    "@oondemand/oon-core-back": "^0.3.39"
+    "@oondemand/oon-core-back": "^0.3.41"
   }
 }

package/templates/_base/frontend/package.json

@@ -10,7 +10,7 @@
     "sync:metadata": "oonCore-front sync:metadata"
   },
   "dependencies": {
-    "@oondemand/oon-core-front": "^0.3.39",
+    "@oondemand/oon-core-front": "^0.3.41",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",