@oondemand/create-central-oon 0.3.39 → 0.3.40
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.
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Manifesto declarativo de domínio — `central.domain.json`
|
|
2
|
+
|
|
3
|
+
O arquivo `central.domain.json`, localizado na raiz do backend da Central, declara models e campos sem exigir um arquivo JavaScript por model.
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
> A Central declara o domínio. O OonCore constrói schema Mongoose, metadata, CRUD e recursos derivados.
|
|
8
|
+
|
|
9
|
+
## Escopo da versão 1
|
|
10
|
+
|
|
11
|
+
A primeira versão do contrato cobre:
|
|
12
|
+
|
|
13
|
+
- identidade do manifesto;
|
|
14
|
+
- models e seus caminhos de API;
|
|
15
|
+
- configuração de CRUD já aceita por `defineModel`;
|
|
16
|
+
- campos primitivos, enumerações, referências e moedas;
|
|
17
|
+
- obrigatoriedade, valor padrão, busca, unicidade e índice simples;
|
|
18
|
+
- limites numéricos e de tamanho de texto;
|
|
19
|
+
- campos somente leitura, convertidos para `immutable` no schema;
|
|
20
|
+
- validação estrutural com todos os problemas retornados em uma única exceção.
|
|
21
|
+
|
|
22
|
+
Ainda não fazem parte da versão 1:
|
|
23
|
+
|
|
24
|
+
- fórmulas e campos calculados;
|
|
25
|
+
- índices compostos;
|
|
26
|
+
- validações entre campos;
|
|
27
|
+
- triggers e transições;
|
|
28
|
+
- migrações automáticas de dados;
|
|
29
|
+
- mappings de integração.
|
|
30
|
+
|
|
31
|
+
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.
|
|
32
|
+
|
|
33
|
+
## Exemplo
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"name": "Central SS Eventos",
|
|
38
|
+
"slug": "ss-eventos",
|
|
39
|
+
"schemaVersion": 1,
|
|
40
|
+
"models": [
|
|
41
|
+
{
|
|
42
|
+
"name": "ClienteFornecedor",
|
|
43
|
+
"singular": "cliente/fornecedor",
|
|
44
|
+
"basePath": "/clientes-fornecedores",
|
|
45
|
+
"crud": {
|
|
46
|
+
"enabled": true
|
|
47
|
+
},
|
|
48
|
+
"fields": {
|
|
49
|
+
"nome": {
|
|
50
|
+
"kind": "string",
|
|
51
|
+
"label": "Nome",
|
|
52
|
+
"required": true,
|
|
53
|
+
"searchable": true,
|
|
54
|
+
"minLength": 2
|
|
55
|
+
},
|
|
56
|
+
"tipo": {
|
|
57
|
+
"kind": "enum",
|
|
58
|
+
"label": "Tipo",
|
|
59
|
+
"values": ["PF", "PJ", "Est"],
|
|
60
|
+
"default": "PJ"
|
|
61
|
+
},
|
|
62
|
+
"documento": {
|
|
63
|
+
"kind": "string",
|
|
64
|
+
"label": "Documento",
|
|
65
|
+
"unique": true,
|
|
66
|
+
"index": true
|
|
67
|
+
},
|
|
68
|
+
"responsavelId": {
|
|
69
|
+
"kind": "ref",
|
|
70
|
+
"label": "Responsável",
|
|
71
|
+
"ref": "Responsavel"
|
|
72
|
+
},
|
|
73
|
+
"ativo": {
|
|
74
|
+
"kind": "boolean",
|
|
75
|
+
"label": "Ativo",
|
|
76
|
+
"default": true
|
|
77
|
+
},
|
|
78
|
+
"limite": {
|
|
79
|
+
"kind": "currency",
|
|
80
|
+
"label": "Limite",
|
|
81
|
+
"default": 0,
|
|
82
|
+
"readonly": true
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
]
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Estrutura principal
|
|
91
|
+
|
|
92
|
+
| Propriedade | Obrigatória | Descrição |
|
|
93
|
+
|---|---:|---|
|
|
94
|
+
| `name` | sim | Nome legível da declaração de domínio. |
|
|
95
|
+
| `slug` | não | Identificador em minúsculas, números e hífens. |
|
|
96
|
+
| `schemaVersion` | sim | Nesta versão, deve ser `1`. |
|
|
97
|
+
| `models` | sim | Lista não vazia de models. |
|
|
98
|
+
|
|
99
|
+
## Model
|
|
100
|
+
|
|
101
|
+
| Propriedade | Obrigatória | Descrição |
|
|
102
|
+
|---|---:|---|
|
|
103
|
+
| `name` | sim | Nome PascalCase usado no registry e no Mongoose. |
|
|
104
|
+
| `singular` | não | Nome singular usado pelo Core. |
|
|
105
|
+
| `basePath` | não | Caminho iniciado por `/`. |
|
|
106
|
+
| `crud` | não | Mesmo contrato aceito por `defineModel`. |
|
|
107
|
+
| `options` | não | Opções JSON compatíveis com o schema Mongoose. |
|
|
108
|
+
| `fields` | sim | Objeto com pelo menos um campo. |
|
|
109
|
+
|
|
110
|
+
Não declare a mesma model no manifesto e em `src/models`. O registry interrompe o bootstrap para impedir duas fontes de verdade.
|
|
111
|
+
|
|
112
|
+
## Tipos de campo
|
|
113
|
+
|
|
114
|
+
- `string`
|
|
115
|
+
- `number`
|
|
116
|
+
- `boolean`
|
|
117
|
+
- `date`
|
|
118
|
+
- `ref`
|
|
119
|
+
- `enum`
|
|
120
|
+
- `currency`
|
|
121
|
+
- `currencyCode`
|
|
122
|
+
- `currencyConverted`
|
|
123
|
+
|
|
124
|
+
### Opções comuns
|
|
125
|
+
|
|
126
|
+
- `label`: rótulo para metadata e frontend;
|
|
127
|
+
- `description`: explicação funcional;
|
|
128
|
+
- `required`: campo obrigatório;
|
|
129
|
+
- `default`: valor padrão JSON;
|
|
130
|
+
- `readonly`: gera campo imutável no backend e metadata somente leitura;
|
|
131
|
+
- `searchable`: inclui texto na busca derivada do Core;
|
|
132
|
+
- `unique`: índice único simples;
|
|
133
|
+
- `index`: índice simples.
|
|
134
|
+
|
|
135
|
+
### Opções por tipo
|
|
136
|
+
|
|
137
|
+
- textos: `minLength`, `maxLength`;
|
|
138
|
+
- números e moedas: `min`, `max`;
|
|
139
|
+
- `ref`: `ref` com o nome da model relacionada;
|
|
140
|
+
- `enum`: `values` com textos únicos e não vazios;
|
|
141
|
+
- `currencyConverted`: `base` com código ISO de três letras.
|
|
142
|
+
|
|
143
|
+
## Erros de validação
|
|
144
|
+
|
|
145
|
+
Um manifesto inválido lança `DomainManifestError`:
|
|
146
|
+
|
|
147
|
+
```js
|
|
148
|
+
{
|
|
149
|
+
name: "DomainManifestError",
|
|
150
|
+
code: "OON_DOMAIN_MANIFEST_INVALID",
|
|
151
|
+
statusCode: 422,
|
|
152
|
+
issues: [
|
|
153
|
+
{
|
|
154
|
+
path: "models[0].fields.clienteId.ref",
|
|
155
|
+
message: "é obrigatório para campos ref."
|
|
156
|
+
}
|
|
157
|
+
]
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
A validação agrega os problemas para que o autor corrija o documento em uma única rodada.
|
|
162
|
+
|
|
163
|
+
## APIs públicas
|
|
164
|
+
|
|
165
|
+
```js
|
|
166
|
+
const {
|
|
167
|
+
validateDomainManifest,
|
|
168
|
+
domainManifestToDefinitions,
|
|
169
|
+
registerDomainManifest,
|
|
170
|
+
loadDomainManifest,
|
|
171
|
+
} = require("@oondemand/oon-core-back");
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Na operação normal não é necessário chamar essas funções: `oonCore-back start` descobre automaticamente `central.domain.json`.
|
|
175
|
+
|
|
176
|
+
## Compatibilidade durante a migração
|
|
177
|
+
|
|
178
|
+
Os diretórios JavaScript continuam disponíveis para validações, regras e recursos ainda não declarativos. A ordem é:
|
|
179
|
+
|
|
180
|
+
1. `central.config.js`;
|
|
181
|
+
2. `central.domain.json`;
|
|
182
|
+
3. diretórios em `src/`.
|
|
183
|
+
|
|
184
|
+
Isso permite migrar model por model, mantendo regras específicas fora do Core até existir um contrato declarativo equivalente.
|
package/docs/CODEX.md
CHANGED
|
@@ -15,6 +15,7 @@ A fonte de verdade desta documentação é a versão instalada do pacote `@oonde
|
|
|
15
15
|
|
|
16
16
|
### Backend/domínio
|
|
17
17
|
|
|
18
|
+
- `BACKEND_DOMAIN_MANIFEST.md`
|
|
18
19
|
- `BACKEND_PATTERNS.md`
|
|
19
20
|
- `COLLECTIONS_AND_PIPELINES.md`
|
|
20
21
|
- `CONNECTORS_AND_INTEGRATIONS.md`
|
|
@@ -45,6 +46,7 @@ Use estes documentos quando a necessidade envolver:
|
|
|
45
46
|
## Princípios obrigatórios
|
|
46
47
|
|
|
47
48
|
- Escreva apenas o domínio da Central.
|
|
49
|
+
- Use `central.domain.json` para models e campos cobertos pelo contrato declarativo vigente.
|
|
48
50
|
- Use `@oondemand/oon-core-back` para boot, autenticação, RBAC, CRUD, metadata, auditoria e padrões de API.
|
|
49
51
|
- Use `@oondemand/oon-core-front` para shell, rotas, menu, datagrid, formulários, badges, ações e renderização por metadata.
|
|
50
52
|
- Não recrie infraestrutura que já existe no Core.
|
|
@@ -53,7 +55,7 @@ Use estes documentos quando a necessidade envolver:
|
|
|
53
55
|
- Não hardcode tenant, app, usuário, perfil, permissões, URLs sensíveis ou segredos.
|
|
54
56
|
- Não exponha chaves em código, templates ou documentação gerada.
|
|
55
57
|
- Não altere arquivos gerados do Core se houver extensão declarativa disponível.
|
|
56
|
-
- Prefira
|
|
58
|
+
- Prefira manifestos, validations, triggers, hooks, mappings, documents, pipelines, integrations e overrides declarativos.
|
|
57
59
|
- Antes de criar uma página React customizada, tente resolver com `central.ui.json`, `detailModal`, `form.groups`, `relatedGrid`, `readonlyGrid` e `rowActions`.
|
|
58
60
|
|
|
59
61
|
## Ordem de decisão
|
|
@@ -61,8 +63,8 @@ Use estes documentos quando a necessidade envolver:
|
|
|
61
63
|
Ao implementar uma necessidade, siga esta ordem:
|
|
62
64
|
|
|
63
65
|
1. Configuração existente do Core.
|
|
64
|
-
2. Declaração em `central.config.js` ou `central.ui.json`.
|
|
65
|
-
3.
|
|
66
|
+
2. Declaração em `central.config.js`, `central.domain.json` ou `central.ui.json`.
|
|
67
|
+
3. Validation, trigger, hook ou mapping no backend da Central.
|
|
66
68
|
4. Modal, abas, grid relacionado, ação e renderer declarativos do Core.
|
|
67
69
|
5. Override local pequeno e isolado.
|
|
68
70
|
6. Código customizado somente quando o Core não oferecer extensão adequada.
|
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.40",
|
|
14
14
|
"@chakra-ui/react": "^3.13.0",
|
|
15
15
|
"@emotion/react": "^11.14.0",
|
|
16
16
|
"@tanstack/react-query": "^5.65.0",
|