@oondemand/create-central-oon 0.3.41 → 0.3.43
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/CODEX.md
CHANGED
|
@@ -25,6 +25,7 @@ A fonte de verdade desta documentação é a versão instalada do pacote `@oonde
|
|
|
25
25
|
|
|
26
26
|
- `FRONTEND_PATTERNS.md`
|
|
27
27
|
- `FRONTEND_MANIFEST_REFERENCE.md`
|
|
28
|
+
- `REACTIVE_DOMAIN_FORMULAS.md`
|
|
28
29
|
|
|
29
30
|
### UX avançada, modais, abas e itens relacionados
|
|
30
31
|
|
|
@@ -46,7 +47,8 @@ Use estes documentos quando a necessidade envolver:
|
|
|
46
47
|
## Princípios obrigatórios
|
|
47
48
|
|
|
48
49
|
- Escreva apenas o domínio da Central.
|
|
49
|
-
- Use `central.domain.json` para models e
|
|
50
|
+
- Use `central.domain.json` para models, campos, fórmulas e validações cobertos pelo contrato declarativo vigente.
|
|
51
|
+
- Não repita fórmulas do domínio em componentes React: os formulários do Core geram a prévia reativa a partir da metadata e o backend recalcula antes de persistir.
|
|
50
52
|
- Use `@oondemand/oon-core-back` para boot, autenticação, RBAC, CRUD, metadata, auditoria e padrões de API.
|
|
51
53
|
- Use `@oondemand/oon-core-front` para shell, rotas, menu, datagrid, formulários, badges, ações e renderização por metadata.
|
|
52
54
|
- Não recrie infraestrutura que já existe no Core.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Fórmulas reativas nos formulários OonCore
|
|
2
|
+
|
|
3
|
+
A partir do contrato declarativo de domínio, campos com `computed` são recalculados imediatamente nos formulários padrão do `@oondemand/oon-core-front`.
|
|
4
|
+
|
|
5
|
+
A Central não precisa repetir a fórmula em `central.ui.json` nem criar componentes React específicos. A declaração continua existindo uma única vez no `central.domain.json` do backend.
|
|
6
|
+
|
|
7
|
+
## Fluxo
|
|
8
|
+
|
|
9
|
+
1. O backend carrega e valida o `central.domain.json`.
|
|
10
|
+
2. A metadata da model expõe `readonly` e `computed`.
|
|
11
|
+
3. O frontend interpreta a mesma AST fechada para apresentar uma prévia imediata.
|
|
12
|
+
4. Campos calculados e readonly são removidos do payload enviado pelo formulário.
|
|
13
|
+
5. O backend recalcula novamente, executa as validações e persiste o valor autoritativo.
|
|
14
|
+
6. Depois da resposta, o formulário passa a exibir o registro devolvido pelo servidor.
|
|
15
|
+
|
|
16
|
+
> O cálculo no navegador melhora a experiência do usuário. Ele nunca substitui o cálculo, a proteção readonly ou a validação do backend.
|
|
17
|
+
|
|
18
|
+
## Formulários atendidos
|
|
19
|
+
|
|
20
|
+
- formulário dinâmico de coleções (`DynamicForm`);
|
|
21
|
+
- formulário principal em modal com abas (`CoreTabbedDetail`);
|
|
22
|
+
- criação e edição;
|
|
23
|
+
- formulários derivados integralmente da metadata;
|
|
24
|
+
- formulários com overrides de apresentação no `central.ui.json`, desde que a model continue sendo carregada pela metadata do Core.
|
|
25
|
+
|
|
26
|
+
## Exemplo
|
|
27
|
+
|
|
28
|
+
A declaração permanece somente no domínio:
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"subtotal": {
|
|
33
|
+
"kind": "currency",
|
|
34
|
+
"computed": {
|
|
35
|
+
"precision": 2,
|
|
36
|
+
"expression": {
|
|
37
|
+
"op": "multiply",
|
|
38
|
+
"args": [
|
|
39
|
+
{ "field": "quantidade" },
|
|
40
|
+
{ "field": "diarias" },
|
|
41
|
+
{ "field": "valorUnitario" }
|
|
42
|
+
]
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Ao alterar quantidade, diárias ou valor unitário, o campo subtotal é atualizado na tela. Ao salvar, subtotal não é enviado pelo cliente: o backend calcula novamente e devolve o valor persistido.
|
|
50
|
+
|
|
51
|
+
## Paridade da AST
|
|
52
|
+
|
|
53
|
+
O frontend suporta o mesmo vocabulário do backend:
|
|
54
|
+
|
|
55
|
+
- aritméticos: `add`, `subtract`, `multiply`, `divide`, `min`, `max`, `abs`, `negate`, `coalesce`;
|
|
56
|
+
- comparação: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`;
|
|
57
|
+
- lógicos e presença: `and`, `or`, `not`, `present`, `in`;
|
|
58
|
+
- nós de valor: `{ "value": ... }`;
|
|
59
|
+
- referências: `{ "field": "nomeDoCampo" }`.
|
|
60
|
+
|
|
61
|
+
Os testes de caracterização usam cadeias financeiras equivalentes às do backend para reduzir o risco de divergência sem permitir execução de JavaScript arbitrário no navegador.
|
|
62
|
+
|
|
63
|
+
## Tratamento de erros
|
|
64
|
+
|
|
65
|
+
Erros de prévia, como divisão por zero ou valor não numérico, aparecem associados ao campo calculado. O usuário pode corrigir as entradas imediatamente.
|
|
66
|
+
|
|
67
|
+
A decisão final continua no backend, que retorna `DomainRuleError` com status 422 quando a mutação viola o contrato.
|
|
68
|
+
|
|
69
|
+
## Extensões locais
|
|
70
|
+
|
|
71
|
+
Não crie funções de cálculo em componentes da Central para campos já descritos por `computed`.
|
|
72
|
+
|
|
73
|
+
Use código local apenas quando a regra:
|
|
74
|
+
|
|
75
|
+
- não puder ser representada pela AST;
|
|
76
|
+
- depender de consulta externa;
|
|
77
|
+
- exigir agregação de registros relacionados;
|
|
78
|
+
- ainda não possuir contrato declarativo no OonCore.
|
|
79
|
+
|
|
80
|
+
Nesses casos, mantenha o backend como fonte de verdade e registre a lacuna para evolução do Core.
|
package/package.json
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
"sync:metadata": "oonCore-front sync:metadata"
|
|
11
11
|
},
|
|
12
12
|
"dependencies": {
|
|
13
|
-
"@oondemand/oon-core-front": "^0.3.
|
|
13
|
+
"@oondemand/oon-core-front": "^0.3.43",
|
|
14
14
|
"@chakra-ui/react": "^3.13.0",
|
|
15
15
|
"@emotion/react": "^11.14.0",
|
|
16
16
|
"@tanstack/react-query": "^5.65.0",
|