@oondemand/create-central-oon 0.3.8 → 0.3.10

package/README.md

@@ -1,9 +1,9 @@
 # @oondemand/create-central-oon
 
-📖 **[Documentação completa → ooncoredoc.vercel.app](https://ooncoredoc.vercel.app)**
-
 Gerador de **Centrais Oon**. Cria, a partir do nome da Central, um `backend/` de domínio e um `frontend/` declarativo prontos para consumir o Core (`@oondemand/oon-core-back` e `@oondemand/oon-core-front`).
 
+> A documentação pública pode existir para consulta, mas a fonte de verdade para codificação assistida fica dentro deste pacote npm, versionada junto com o gerador.
+
 Toda Central gerada nasce com o padrão visual e operacional consolidado na **Central Minexco**:
 
 - identidade visual Oon/CST com Poppins, azul `#0474AF` e fundo `#F8F9FA`;
@@ -36,6 +36,57 @@ Aliases: o binário também responde por `scaffold-central-oon`.
 | `--no-install`   | Não roda `npm install` nos projetos gerados.                  |
 | `--list`         | Lista os templates e sai.                                     |
 
+## Documentação interna para Codex
+
+O pacote inclui documentação canônica em `docs/`. Ela é publicada no npm junto com o gerador.
+
+A referência completa das opções do manifesto front fica em:
+
+```txt
+packages/create-central-oon/docs/FRONTEND_MANIFEST_REFERENCE.md
+```
+
+Ao criar uma Central, o CLI gera uma pasta `.ooncore/` com um cache local da documentação da versão instalada:
+
+```txt
+<central>/
+└── .ooncore/
+    ├── CODEX.md
+    ├── context.generated.md
+    ├── manifest.json
+    └── docs/
+```
+
+A pasta `.ooncore/` não é a fonte de verdade. Ela é apenas o contexto local para o Codex trabalhar sem depender de site externo.
+
+### Sincronizar documentação local
+
+Na raiz da Central:
+
+```bash
+npm run ooncore:docs
+```
+
+ou diretamente:
+
+```bash
+npx create-central-oon docs --sync
+```
+
+### Verificar se está atualizada
+
+```bash
+npm run ooncore:docs:check
+```
+
+ou diretamente:
+
+```bash
+npx create-central-oon docs --check
+```
+
+O check compara a versão e o hash da documentação local com a versão instalada do pacote.
+
 ## Templates funcionais
 
 Todos utilizam o mesmo frontend padrão Minexco.
@@ -55,6 +106,8 @@ Todos utilizam o mesmo frontend padrão Minexco.
 ```txt
 <central>/
 ├── README.md
+├── package.json              # scripts de sync/check da documentação OonCore
+├── .ooncore/                 # cache local gerado a partir do pacote instalado
 ├── backend/                  # consome @oondemand/oon-core-back
 │   ├── central.config.js     # identidade + módulos + paths de domínio
 │   ├── central.manifest.json # valores de deploy (render no Core)
@@ -70,8 +123,11 @@ Todos utilizam o mesmo frontend padrão Minexco.
 ## Próximos passos após gerar
 
 ```bash
-cd <central>/backend  && cp .env.example .env && npm run dev
-cd ../frontend        && cp .env.example .env && npm run dev
+cd <central>
+npm run ooncore:docs:check
+
+cd backend  && cp .env.example .env && npm run dev
+cd ../frontend && cp .env.example .env && npm run dev
 ```
 
 Evoluir a Central significa criar models em `backend/src/models` e declarar as telas em `frontend/central.ui.json`. Menu, rotas, datagrids, formulários e esteiras são montados pelo Core mantendo o padrão Minexco.

package/bin/cli.js

@@ -2,9 +2,11 @@
 "use strict";
 
 /**
- * CLI do create-central-oon (Fase 4 — Seção 5/25).
+ * CLI do create-central-oon.
  *
  *   npx create-central-oon <nome-da-central> [opções]
+ *   npx create-central-oon docs --sync
+ *   npx create-central-oon docs --check
  *
  * Opções:
  *   --template=<t>   Template inicial (default: basic). Veja --list.
@@ -12,26 +14,62 @@
  *   --force          Sobrescreve pasta existente.
  *   --no-install     Não roda npm install nos projetos gerados.
  *   --list           Lista os templates disponíveis e sai.
+ *
+ * Documentação:
+ *   docs --sync      Gera/atualiza .ooncore/ com a documentação da versão instalada.
+ *   docs --check     Valida se .ooncore/ está sincronizado com a versão instalada.
  */
 
-const { run, listTemplates } = require("../src/index");
+const { run, listTemplates, syncDocs, checkDocs } = require("../src/index");
 
 function parseArgs(argv) {
-  const opts = { template: "basic", here: false, force: false, install: true, list: false };
+  const opts = {
+    command: null,
+    template: "basic",
+    here: false,
+    force: false,
+    install: true,
+    list: false,
+    docsSync: false,
+    docsCheck: false,
+  };
   const positionals = [];
-  for (const arg of argv) {
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
     if (arg === "--here") opts.here = true;
     else if (arg === "--force") opts.force = true;
     else if (arg === "--no-install") opts.install = false;
     else if (arg === "--list") opts.list = true;
+    else if (arg === "--sync") opts.docsSync = true;
+    else if (arg === "--check") opts.docsCheck = true;
     else if (arg.startsWith("--template=")) opts.template = arg.slice("--template=".length);
-    else if (arg === "--template") opts.template = argv[argv.indexOf(arg) + 1];
-    else if (!arg.startsWith("-")) positionals.push(arg);
+    else if (arg === "--template") {
+      opts.template = argv[i + 1];
+      i += 1;
+    } else if (!arg.startsWith("-")) {
+      positionals.push(arg);
+    }
   }
-  opts.name = positionals[0];
+
+  if (positionals[0] === "docs") {
+    opts.command = "docs";
+  } else {
+    opts.name = positionals[0];
+  }
+
   return opts;
 }
 
+function printUsage() {
+  console.error("Uso:");
+  console.error("  npx create-central-oon <nome-da-central> [--template=basic]");
+  console.error("  npx create-central-oon --list");
+  console.error("  npx create-central-oon docs --sync");
+  console.error("  npx create-central-oon docs --check");
+}
+
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
 
@@ -41,13 +79,21 @@ async function main() {
     process.exit(0);
   }
 
-  if (!opts.name) {
-    console.error("Uso: npx create-central-oon <nome-da-central> [--template=basic]");
-    console.error("     npx create-central-oon --list");
-    process.exit(1);
-  }
-
   try {
+    if (opts.command === "docs") {
+      if (opts.docsCheck) {
+        checkDocs();
+      } else {
+        syncDocs();
+      }
+      return;
+    }
+
+    if (!opts.name) {
+      printUsage();
+      process.exit(1);
+    }
+
     await run(opts);
   } catch (err) {
     console.error("\n✖", err.message);

package/docs/BACKEND_PATTERNS.md

@@ -0,0 +1,87 @@
+# Padrões Backend
+
+O backend da Central deve conter apenas domínio e extensões. Boot, infraestrutura, CRUD padrão, autenticação, RBAC e metadata pertencem ao `@oondemand/oon-core-back`.
+
+## Estrutura esperada
+
+```txt
+backend/
+├── central.config.js
+├── central.manifest.json
+└── src/
+    ├── models/
+    ├── validations/
+    ├── triggers/
+    ├── hooks/
+    ├── mappings/
+    ├── documents/
+    ├── pipelines/
+    ├── integrations/
+    ├── routes/
+    ├── controllers/
+    └── services/
+```
+
+## Models
+
+Use models para declarar entidades de negócio. Cada model deve ser pequeno, com nomes claros e campos compatíveis com as telas e integrações.
+
+Boas práticas:
+
+- use campos explícitos;
+- defina tipos, obrigatoriedade e enums quando aplicável;
+- preserve campos de status para esteiras;
+- evite regras complexas diretamente no schema;
+- evite dependência direta de frontend.
+
+## Validations
+
+Use validations para regras de negócio síncronas e mensagens claras para o usuário.
+
+Exemplos:
+
+- campo obrigatório condicional;
+- status permitido para transição;
+- valor mínimo/máximo;
+- combinação inválida de campos;
+- bloqueio por permissão ou perfil.
+
+## Triggers e hooks
+
+Use triggers e hooks para efeitos controlados depois ou antes de alterações.
+
+Exemplos:
+
+- criar ticket de integração;
+- recalcular campos derivados;
+- gerar histórico operacional;
+- disparar conector;
+- atualizar etapa da esteira.
+
+Regras:
+
+- trigger não deve esconder regra crítica sem validação;
+- evite efeitos irreversíveis sem log;
+- integração externa deve passar por camada de integração/conector;
+- falhas de integração devem gerar status rastreável, não quebrar silenciosamente o processo.
+
+## Rotas customizadas
+
+Crie rotas customizadas somente quando o CRUD/metadata do Core não resolver.
+
+Toda rota customizada deve ter:
+
+- autenticação;
+- verificação de permissão;
+- validação de entrada;
+- tratamento de erro;
+- resposta padronizada;
+- ausência de segredo hardcoded.
+
+## Serviços
+
+Use `services/` para regras reutilizáveis. Evite controllers grandes.
+
+## Segurança
+
+Nunca confie no frontend para permissão, tenant, app ou perfil. O backend deve validar tudo que altera dados, dispara integrações ou expõe informações sensíveis.

package/docs/CHECKLIST_IMPLEMENTACAO.md

@@ -0,0 +1,41 @@
+# Checklist de Implementação
+
+Use este checklist antes de concluir qualquer tarefa de codificação em uma Central Oon.
+
+## Contexto
+
+- [ ] Rodei `npm run ooncore:docs:check`.
+- [ ] Rodei `npm run ooncore:docs` se havia documentação desatualizada.
+- [ ] Li `.ooncore/context.generated.md`.
+- [ ] Entendi qual recurso do Core já resolve parte da necessidade.
+
+## Backend
+
+- [ ] Usei model, validation, trigger, hook, mapping ou integration quando aplicável.
+- [ ] Evitei recriar CRUD.
+- [ ] Validei entrada.
+- [ ] Validei permissão no backend.
+- [ ] Tratei erros.
+- [ ] Não hardcodei segredos.
+- [ ] Mantive rastreabilidade.
+
+## Frontend
+
+- [ ] Usei `central.ui.json` antes de criar componente customizado.
+- [ ] Evitei recriar shell, rotas, menu, datagrid ou form.
+- [ ] Usei override apenas quando necessário.
+- [ ] Não coloquei regra crítica apenas no frontend.
+
+## Integrações
+
+- [ ] Usei camada de integração/conector.
+- [ ] Modelei mapping.
+- [ ] Registrei status de integração.
+- [ ] Normalizei erros externos.
+- [ ] Não expus credenciais.
+
+## Entrega
+
+- [ ] A Central continua atualizável com novas versões do Core.
+- [ ] A alteração é pequena, coesa e aderente à arquitetura.
+- [ ] O comportamento esperado está documentado no README ou no próprio módulo quando necessário.

package/docs/CODEX.md

@@ -0,0 +1,46 @@
+# CODEX.md — Regras de Codificação OonCore
+
+Este arquivo é a porta de entrada para o Codex codificar uma Central Oon.
+
+A fonte de verdade desta documentação é a versão instalada do pacote `@oondemand/create-central-oon`. A pasta `.ooncore/` gerada em cada Central é apenas um cache local, criado por `create-central-oon docs --sync`.
+
+## Antes de codificar
+
+1. Rode `npm run ooncore:docs:check` na raiz da Central.
+2. Se estiver desatualizado, rode `npm run ooncore:docs`.
+3. Leia `.ooncore/context.generated.md`.
+4. Identifique o recurso do Core que resolve a necessidade antes de criar código customizado.
+
+## Princípios obrigatórios
+
+- Escreva apenas o domínio da Central.
+- 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.
+- Não crie autenticação paralela.
+- Não duplique RBAC no frontend.
+- 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.
+
+## Ordem de decisão
+
+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.
+4. Override local pequeno e isolado.
+5. Código customizado somente quando o Core não oferecer extensão adequada.
+
+## Entrega segura
+
+Toda alteração deve manter:
+
+- rastreabilidade;
+- validação de entrada;
+- RBAC no backend;
+- ausência de segredo hardcoded;
+- separação entre domínio da Central e infraestrutura do Core;
+- compatibilidade com atualização futura dos pacotes `@oondemand/*`.

package/docs/COLLECTIONS_AND_PIPELINES.md

@@ -0,0 +1,66 @@
+# Coleções, Documentos e Esteiras
+
+Coleções, documentos e esteiras são a base operacional da Central Oon.
+
+## Coleções
+
+Use coleções para entidades de negócio:
+
+- clientes;
+- fornecedores;
+- pedidos;
+- pagamentos;
+- documentos fiscais;
+- serviços tomados;
+- serviços prestados;
+- integrações;
+- tickets operacionais.
+
+Cada coleção deve ter:
+
+- model no backend;
+- metadata para CRUD;
+- campos de status quando participar de esteira;
+- validações de negócio;
+- configuração de tela no frontend.
+
+## Documentos
+
+Use documentos para entidades que exigem governança documental, aprovação, anexos ou histórico específico.
+
+Exemplos:
+
+- NF;
+- contrato;
+- proposta;
+- comprovante;
+- ordem de serviço;
+- pedido de compra.
+
+## Esteiras de processo
+
+Use esteiras para fluxos operacionais com etapas claras.
+
+Boas práticas:
+
+- status/etapa deve estar no backend;
+- transições devem ser validadas;
+- ações devem registrar usuário e data;
+- exceções devem ter status próprio;
+- cada etapa deve representar uma decisão operacional real.
+
+## Esteiras de integração
+
+Use esteiras de integração para acompanhar comunicação com sistemas externos.
+
+Estados recomendados:
+
+- pendente;
+- em processamento;
+- enviado;
+- concluído;
+- falha;
+- aguardando retry;
+- cancelado.
+
+Integrações não devem ser caixas-pretas. O usuário operacional precisa enxergar o que aconteceu, qual erro ocorreu e qual ação pode ser tomada.

package/docs/CONNECTORS_AND_INTEGRATIONS.md

@@ -0,0 +1,66 @@
+# Conectores e Integrações
+
+Toda integração deve ser modelada como um processo rastreável, não como chamada solta dentro de controller.
+
+## Objetivo
+
+Transformar cada integração em:
+
+```txt
+configuração + mapping + execução + status + rastreabilidade
+```
+
+## Estrutura recomendada
+
+```txt
+backend/src/integrations/
+├── <sistema>/
+│   ├── client.js
+│   ├── mappings/
+│   ├── services/
+│   └── README.md
+```
+
+## Client
+
+O client deve concentrar:
+
+- URL base;
+- autenticação;
+- headers;
+- timeout;
+- retry técnico;
+- normalização de erro.
+
+Não coloque regra de negócio no client.
+
+## Mapping
+
+Mappings devem transformar dados entre a Central e o sistema externo.
+
+Regras:
+
+- mapping deve ser explícito;
+- campos obrigatórios devem ser validados antes do envio;
+- resposta externa deve ser normalizada;
+- erros devem ser compreensíveis para operação.
+
+## Esteira de integração
+
+Toda integração relevante deve gerar registro operacional com:
+
+- origem;
+- destino;
+- payload resumido ou referência;
+- status;
+- tentativas;
+- erro normalizado;
+- data/hora;
+- usuário ou processo responsável.
+
+## Segurança
+
+- Nunca versionar app key, secret, token ou credencial.
+- Não logar payloads sensíveis sem necessidade.
+- Não expor credenciais no frontend.
+- Usar `.env` e configuração de ambiente.

package/docs/DO_AND_DONT.md

@@ -0,0 +1,27 @@
+# Do and Don't
+
+## Faça
+
+- Use o Core antes de criar código novo.
+- Modele o domínio com clareza.
+- Prefira configuração e metadata.
+- Escreva validações explícitas.
+- Mantenha regras críticas no backend.
+- Use esteiras para processos com status.
+- Use conectores para integrações.
+- Registre erros de forma operacional.
+- Mantenha compatibilidade com atualização dos pacotes.
+- Atualize `.ooncore/` com `npm run ooncore:docs`.
+
+## Não faça
+
+- Não recrie CRUD.
+- Não recrie autenticação.
+- Não duplique RBAC no frontend.
+- Não criar um frontend inteiro se um override resolve.
+- Não chamar APIs externas direto de qualquer lugar.
+- Não hardcode tenant, app, usuário, URL sensível ou segredo.
+- Não colocar regra crítica apenas no frontend.
+- Não ignorar logs e rastreabilidade.
+- Não editar `.ooncore/context.generated.md` manualmente.
+- Não depender de documentação externa para codificar a arquitetura.