@oondemand/create-central-oon 0.3.40 → 0.3.41

package/docs/BACKEND_DOMAIN_MANIFEST.md

@@ -1,14 +1,14 @@
 # Manifesto declarativo de domínio — `central.domain.json`
 
-O arquivo `central.domain.json`, localizado na raiz do backend da Central, declara models e campos sem exigir um arquivo JavaScript por model.
+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. O OonCore constrói schema Mongoose, metadata, CRUD e recursos derivados.
+> 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
 
-A primeira versão do contrato cobre:
+O contrato cobre:
 
 - identidade do manifesto;
 - models e seus caminhos de API;
@@ -16,21 +16,24 @@ A primeira versão do contrato cobre:
 - 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, convertidos para `immutable` no schema;
+- 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 da versão 1:
+Ainda não fazem parte desta versão:
 
-- fórmulas e campos calculados;
 - índices compostos;
-- validações entre campos;
-- triggers e transições;
+- triggers e transições declarativas;
 - migrações automáticas de dados;
-- mappings de integração.
+- mappings de integração;
+- funções JavaScript embutidas no JSON.
 
-Esses recursos serão adicionados em contratos próprios ou em versões posteriores, sem transformar expressões de negócio em JavaScript arbitrário dentro do 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
+## Exemplo financeiro
 
 ```json
 {
@@ -39,49 +42,103 @@ Esses recursos serão adicionados em contratos próprios ou em versões posterio
   "schemaVersion": 1,
   "models": [
     {
-      "name": "ClienteFornecedor",
-      "singular": "cliente/fornecedor",
-      "basePath": "/clientes-fornecedores",
+      "name": "ProjetoItem",
+      "singular": "item",
+      "basePath": "/itens",
       "crud": {
         "enabled": true
       },
       "fields": {
-        "nome": {
-          "kind": "string",
-          "label": "Nome",
-          "required": true,
-          "searchable": true,
-          "minLength": 2
+        "quantidade": {
+          "kind": "number",
+          "required": true
         },
-        "tipo": {
-          "kind": "enum",
-          "label": "Tipo",
-          "values": ["PF", "PJ", "Est"],
-          "default": "PJ"
+        "diarias": {
+          "kind": "number",
+          "required": true
         },
-        "documento": {
-          "kind": "string",
-          "label": "Documento",
-          "unique": true,
-          "index": true
+        "valorUnitario": {
+          "kind": "currency",
+          "required": true
         },
-        "responsavelId": {
-          "kind": "ref",
-          "label": "Responsável",
-          "ref": "Responsavel"
+        "percentualFee": {
+          "kind": "number",
+          "default": 0
         },
-        "ativo": {
-          "kind": "boolean",
-          "label": "Ativo",
-          "default": true
+        "valorContratado": {
+          "kind": "currency",
+          "default": 0
         },
-        "limite": {
+        "valorPago": {
           "kind": "currency",
-          "label": "Limite",
-          "default": 0,
+          "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" }
+            ]
+          }
         }
-      }
+      ]
     }
   ]
 }
@@ -106,6 +163,7 @@ Esses recursos serão adicionados em contratos próprios ou em versões posterio
 | `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.
 
@@ -127,10 +185,11 @@ Não declare a mesma model no manifesto e em `src/models`. O registry interrompe
 - `description`: explicação funcional;
 - `required`: campo obrigatório;
 - `default`: valor padrão JSON;
-- `readonly`: gera campo imutável no backend e metadata somente leitura;
+- `readonly`: campo controlado pelo servidor;
 - `searchable`: inclui texto na busca derivada do Core;
 - `unique`: índice único simples;
-- `index`: índice simples.
+- `index`: índice simples;
+- `computed`: fórmula declarativa para campos numéricos ou monetários.
 
 ### Opções por tipo
 
@@ -140,9 +199,172 @@ Não declare a mesma model no manifesto e em `src/models`. O registry interrompe
 - `enum`: `values` com textos únicos e não vazios;
 - `currencyConverted`: `base` com código ISO de três letras.
 
-## Erros de validação
+## 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 inválido lança `DomainManifestError`:
+Um manifesto estruturalmente inválido lança `DomainManifestError`:
 
 ```js
 {
@@ -151,8 +373,8 @@ Um manifesto inválido lança `DomainManifestError`:
   statusCode: 422,
   issues: [
     {
-      path: "models[0].fields.clienteId.ref",
-      message: "é obrigatório para campos ref."
+      path: "models[0].fields.total.computed.expression",
+      message: "dependência circular entre campos calculados: total -> fee -> total."
     }
   ]
 }
@@ -168,17 +390,22 @@ const {
   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`.
+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 validações, regras e recursos ainda não declarativos. A ordem é:
+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, mantendo regras específicas fora do Core até existir um contrato declarativo equivalente.
+Isso permite migrar model por model. `defineValidation` continua disponível e roda depois das fórmulas e validações declarativas.

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.40",
+  "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.40"
+    "@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.40",
+    "@oondemand/oon-core-front": "^0.3.41",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",