@oondemand/create-central-oon 0.5.6 → 0.6.1

package/docs/FRONTEND_MANIFEST_REFERENCE.md

@@ -1,487 +0,0 @@
-# Referência do Manifesto Frontend OonCore
-
-Este documento é a referência operacional para qualquer Agent criar ou alterar manifestos do frontend OonCore.
-
-Use este arquivo junto com `FRONTEND_PATTERNS.md`. O arquivo de padrões explica como pensar a UI; este arquivo lista as opções do contrato atual e das extensões planejadas para UX avançada.
-
-Para modal com abas, grids relacionados editáveis e ações por linha, leia também:
-
-- `ADVANCED_UX_PATTERNS.md`
-- `DETAIL_MODAL_AND_RELATED_GRIDS.md`
-
-## Arquivos envolvidos
-
-```txt
-frontend/central.ui.json               # manifesto declarativo da Central
-frontend/src/main.tsx                   # bootstrap do frontend
-packages/oonCore-front/src/manifest.ts # conversão central.ui.json -> OonCoreFrontConfig
-packages/oonCore-front/src/types.ts    # tipos oficiais do contrato
-```
-
-## Regra principal
-
-O manifesto JSON não deve carregar componentes React. Ele só pode declarar dados e chaves de renderer, como:
-
-```txt
-custom:MeusAppsHeader
-fields.password
-cells.statusBadge
-cards.appLauncher
-actions.ativarApp
-menus.portal
-```
-
-Os componentes reais devem ser registrados em código TypeScript/React pelo `registry`.
-
-## Níveis de contrato
-
-Existem três níveis importantes:
-
-1. `central.ui.json`: entrada declarativa usada pelas Centrais geradas.
-2. `CentralUiManifest`: contrato lido por `startFromManifest`.
-3. `OonUiManifest` / `OonCoreFrontConfig`: contrato interno mais completo do Core Front.
-
-Para Agents, a ordem recomendada é:
-
-1. Começar pelo `central.ui.json`.
-2. Usar `pages` e `blocks` quando precisar de UI v2.
-3. Usar `collections[].list`, `collections[].detailModal`, `form.groups`, `relations` e `relatedGrid` para UX operacional avançada.
-4. Usar registry/overrides em TypeScript quando precisar de componentes customizados.
-5. Evitar recriar shell, rotas, menu, grid, cards ou formulários manualmente.
-
-## CentralUiManifest
-
-Contrato aceito por `startFromManifest(manifest, runtime)`.
-
-```ts
-interface CentralUiManifest {
-  name: string;
-  slug: string;
-  backend?: { metadataUrl?: string };
-  schemaVersion?: 1 | 2;
-  layout?: OonLayoutConfig;
-  registry?: OonComponentRegistry;
-  navigation?: OonNavigationConfig;
-  pages?: OonPageDef[];
-  collections?: OonCollectionManifestDef[];
-  pipelines?: Array<{
-    name?: string;
-    model?: string;
-    mode?: string;
-    stageField?: string;
-    path?: string;
-    label?: string;
-    section?: string;
-  }>;
-  documents?: Array<{
-    model: string;
-    mode?: string;
-    path?: string;
-    label?: string;
-    section?: string;
-    approval?: boolean;
-    attachments?: boolean;
-  }>;
-}
-```
-
-## Opções de raiz
-
-| Campo | Tipo | Uso |
-| --- | --- | --- |
-| `name` | `string` | Nome exibido da Central. |
-| `slug` | `string` | Identificador da Central/app. |
-| `backend.metadataUrl` | `string` | URL explícita de metadata, quando aplicável. |
-| `schemaVersion` | `1 \| 2` | Sem valor = compatibilidade v1. Use `2` para UI v2. |
-| `layout` | `OonLayoutConfig` | Shell, sidebar, topbar, header, footer e slots. |
-| `navigation` | `OonNavigationConfig` | Modo do menu e itens manuais. |
-| `pages` | `OonPageDef[]` | Páginas por blocos da UI v2. |
-| `collections` | `Array` | Views de coleção, simples ou avançadas. |
-| `pipelines` | `Array` | Atalho para gerar esteiras. |
-| `documents` | `Array` | Atalho para gerar documentos. |
-
-## Layout
-
-```ts
-type OonSlotConfig = "core" | "none" | `custom:${string}`;
-
-interface OonLayoutConfig {
-  shell?: "default" | "portal" | "content-only" | `custom:${string}`;
-  sidebar?: OonSlotConfig;
-  topbar?: OonSlotConfig;
-  header?: "none" | `custom:${string}`;
-  footer?: "core" | "none" | `custom:${string}`;
-  assistant?: "core" | "none" | `custom:${string}`;
-  main?: "core";
-}
-```
-
-### Valores de `layout.shell`
-
-| Valor | Comportamento |
-| --- | --- |
-| `default` | Shell operacional padrão com sidebar/topbar. |
-| `portal` | Shell para portal, útil para Meus Apps ou home de cards. |
-| `content-only` | Experiência focada em conteúdo. |
-| `custom:<key>` | Shell registrado em `registry.layoutSlots`. |
-
-## Navigation
-
-```ts
-type OonNavigationMode = "auto" | "manual" | "mixed";
-
-interface OonNavigationConfig {
-  mode?: OonNavigationMode;
-  items?: OonMenuItem[];
-}
-```
-
-## Collections no central.ui.json
-
-Atalho para coleções simples ou avançadas.
-
-```ts
-interface OonCollectionManifestDef {
-  model: string;
-  mode?: "full" | "minimal" | "dynamic";
-  path?: string;
-  label?: string;
-  section?: string;
-  list?: OonCollectionListConfig;
-  relations?: Record<string, OonRelationDef>;
-  detailModal?: OonDetailModalConfig;
-}
-```
-
-### Exemplo simples
-
-```json
-{
-  "collections": [
-    {
-      "model": "Cliente",
-      "mode": "dynamic",
-      "path": "/clientes",
-      "label": "Clientes",
-      "section": "Cadastros"
-    }
-  ]
-}
-```
-
-### Exemplo avançado
-
-```json
-{
-  "collections": [
-    {
-      "model": "OrcamentoProjeto",
-      "mode": "dynamic",
-      "path": "/orcamentos-projetos",
-      "label": "Orçamentos/Projetos",
-      "section": "Operação",
-      "list": {
-        "filters": [
-          {
-            "field": "tipoRegistro",
-            "label": "Tipo",
-            "type": "select",
-            "options": [
-              { "label": "Todos", "value": "" },
-              { "label": "Orçamento", "value": "Orçamento" },
-              { "label": "Projeto", "value": "Projeto" }
-            ]
-          }
-        ],
-        "rowActions": [
-          { "type": "openDetailModal", "icon": "edit", "label": "Editar", "initialTab": "resumo" }
-        ]
-      },
-      "relations": {
-        "itens": { "model": "OrcamentoItem", "foreignKey": "projetoId", "parentKey": "_id" },
-        "pagamentos": { "model": "Pagamento", "foreignKey": "projetoId", "parentKey": "_id" }
-      },
-      "detailModal": {
-        "enabled": true,
-        "titleField": "nome",
-        "defaultTab": "resumo",
-        "tabs": []
-      }
-    }
-  ]
-}
-```
-
-## list
-
-Configura filtros, colunas e ações do grid principal.
-
-```ts
-interface OonCollectionListConfig {
-  filters?: OonListFilterDef[];
-  columns?: Array<string | OonColumnDef>;
-  rowActions?: OonRowActionDef[];
-}
-```
-
-### list.filters
-
-```json
-{
-  "field": "tipoRegistro",
-  "label": "Tipo",
-  "type": "select",
-  "options": [
-    { "label": "Todos", "value": "" },
-    { "label": "Orçamento", "value": "Orçamento" }
-  ]
-}
-```
-
-Tipos previstos:
-
-- `text`
-- `select`
-- `date`
-- `dateRange`
-- `numberRange`
-- `boolean`
-- `ref`
-
-### list.rowActions
-
-```json
-{
-  "type": "openDetailModal",
-  "label": "Editar",
-  "icon": "edit",
-  "initialTab": "resumo"
-}
-```
-
-## relations
-
-Relações nomeadas entre model pai e models filhos.
-
-```json
-{
-  "relations": {
-    "itens": {
-      "model": "OrcamentoItem",
-      "foreignKey": "projetoId",
-      "parentKey": "_id"
-    }
-  }
-}
-```
-
-## detailModal
-
-Configura modal de detalhe/criação com abas.
-
-```ts
-interface OonDetailModalConfig {
-  enabled?: boolean;
-  titleField?: string;
-  size?: "md" | "lg" | "xl" | "full";
-  defaultTab?: string;
-  tabs: OonDetailTabDef[];
-}
-```
-
-### Abas suportadas
-
-- `summary`
-- `form`
-- `relatedGrid`
-- `readonlyGrid`
-- `customComponent`
-
-### Aba summary
-
-```json
-{
-  "id": "resumo",
-  "label": "Resumo",
-  "type": "summary",
-  "cards": [
-    { "label": "Itens", "source": "relatedCount", "relation": "itens" },
-    { "label": "Total", "field": "total", "format": "currency" }
-  ]
-}
-```
-
-### Aba form
-
-```json
-{
-  "id": "dados",
-  "label": "Dados Principais",
-  "type": "form",
-  "groups": [
-    { "label": "Identificação", "fields": ["codigo", "nome", "status"] }
-  ]
-}
-```
-
-### Aba relatedGrid
-
-```json
-{
-  "id": "itens",
-  "label": "Itens",
-  "type": "relatedGrid",
-  "relation": "itens",
-  "editable": true,
-  "editMode": "inline",
-  "columns": [
-    { "field": "item", "editable": true },
-    { "field": "status", "editable": true },
-    { "field": "total", "editable": true, "format": "currency" }
-  ],
-  "rowActions": []
-}
-```
-
-### Aba readonlyGrid
-
-```json
-{
-  "id": "pagamentos",
-  "label": "Pagamentos",
-  "type": "readonlyGrid",
-  "relation": "pagamentos",
-  "columns": ["codigo", "descricao", "status", "valor"]
-}
-```
-
-## rowActions
-
-Ações reutilizáveis em grid principal ou grids relacionados.
-
-```ts
-interface OonRowActionDef {
-  id?: string;
-  label: string;
-  icon?: string;
-  type: "openDetailModal" | "navigate" | "apiAction" | "customAction";
-  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-  endpoint?: string;
-  initialTab?: string;
-  confirm?: { title?: string; description?: string };
-  disabledWhen?: OonConditionDef;
-  hiddenWhen?: OonConditionDef;
-  refresh?: string[];
-  roles?: string[];
-  permissions?: string[];
-}
-```
-
-### apiAction
-
-```json
-{
-  "id": "gerarPagamento",
-  "label": "Gerar pagamento",
-  "type": "apiAction",
-  "method": "POST",
-  "endpoint": "/api/ss-eventos/orcamentos-itens/:id/gerar-pagamento",
-  "disabledWhen": { "field": "pagamentoId", "exists": true },
-  "refresh": ["self", "pagamentos", "resumo", "parent"]
-}
-```
-
-## CollectionViewDef completo
-
-Contrato interno completo quando a coleção já está em `ui.views` ou em blocos.
-
-```ts
-interface CollectionViewDef {
-  type: "collection";
-  id?: string;
-  model: string;
-  label?: string;
-  path?: string;
-  icon?: ReactNode;
-  section?: string;
-  mode?: "full" | "minimal" | "dynamic";
-  columns?: OonColumnDef[];
-  form?: OonFormFieldDef[];
-  importExport?: boolean;
-  renderer?: string;
-  cardRenderer?: string;
-  actions?: OonActionDef[];
-  permissions?: string[];
-  list?: OonCollectionListConfig;
-  relations?: Record<string, OonRelationDef>;
-  detailModal?: OonDetailModalConfig;
-}
-```
-
-## Compatibilidade
-
-- Os campos `list`, `relations` e `detailModal` são opcionais.
-- Manifestos existentes continuam funcionando.
-- Sem `detailModal`, o Core mantém comportamento atual.
-- Sem `form.groups`, o Core mantém formulário padrão.
-
-## UX avançada implementada
-
-Campos aceitos em `collections[]`:
-
-- `list.filters`: filtros acima do grid principal.
-- `list.columns`: colunas declarativas opcionais.
-- `list.rowActions`: ações por linha (`openDetailModal`, `navigate`, `apiAction`, `customAction`).
-- `relations`: mapa de relações `{ model, foreignKey, parentKey }`.
-- `detailModal`: modal genérica com `titleField`, `defaultTab`, `size` e `tabs`.
-
-Tipos de aba:
-
-- `summary`: cards com `field`, `relatedCount`, `relatedSum`, `relatedAvg` ou `customMetric`.
-- `form`: campos ou `groups` do registro principal.
-- `relatedGrid`: registros filhos, opcionalmente editáveis inline.
-- `readonlyGrid`: registros filhos sem edição.
-- `customComponent`: chave de componente registrado.
-
-`apiAction.endpoint` aceita `:id`, `:parentId`, `:fieldName` e `:parent.fieldName`. `refresh` aceita `self`, `parent`, `all` ou ids de abas.
-
-
-## Opções remotas em campos de formulário
-
-Campos `enum` podem carregar opções de um endpoint dependente do formulário atual ou do registro pai. O contrato funciona em formulários principais e em criação/edição de `relatedGrid`.
-
-```ts
-{
-  field: "roleCode",
-  label: "Perfil",
-  kind: "enum",
-  optionsEndpoint: "/control-plane/app-role-catalogs/:appId?tenantId=:parentId",
-  optionsResponsePath: "options",
-  optionsValueField: "value",
-  optionsLabelField: "label",
-  optionsDescriptionField: "description",
-  optionsEditablePath: "editable",
-  optionsDependsOn: ["appId", "tenantId"],
-  fallbackOptions: [{ value: "admin", label: "Administrador" }],
-  readonlyOnFallback: true,
-  optionsUnavailableMessage: "Catálogo indisponível; perfil admin aplicado."
-}
-```
-
-| Campo | Uso |
-| --- | --- |
-| `optionsEndpoint` | Endpoint relativo. Aceita `:field`, `:parentId` e `:parent.field`; valores são codificados para URL. |
-| `optionsResponsePath` | Caminho da lista na resposta. Sem valor, a própria resposta deve ser um array. |
-| `optionsValueField` | Campo usado como valor da opção; padrão `value`. |
-| `optionsLabelField` | Campo usado como rótulo; padrão `label`. |
-| `optionsDescriptionField` | Campo opcional de descrição. |
-| `optionsEditablePath` | Booleano remoto que permite ou bloqueia a edição. |
-| `optionsDependsOn` | Campos que precisam estar preenchidos e cuja mudança invalida a seleção atual. |
-| `fallbackOptions` | Opções seguras usadas quando o endpoint falha ou retorna lista vazia. |
-| `readonlyOnFallback` | Bloqueia a seleção durante o fallback; padrão `true`. |
-| `optionsUnavailableMessage` | Mensagem explicando o fallback ao usuário. |
-| `readonly` | Bloqueia o campo em qualquer estado. |
-
-Durante a edição, a interpolação também considera os valores iniciais completos do registro, inclusive campos somente leitura que não são renderizados no formulário. Valores alterados pelo usuário prevalecem sobre os valores iniciais.
-
-O backend continua responsável por validar o valor selecionado. Opções remotas melhoram a experiência, mas não substituem autorização nem validação de domínio.

package/templates/_base/frontend/central.ui.json

@@ -1,58 +0,0 @@
-{
-  "schemaVersion": 2,
-  "backend": {
-    "metadataUrl": "/core/metadata"
-  },
-  "navigation": {
-    "mode": "auto"
-  },
-  "pages": [
-    {
-      "path": "/",
-      "label": "Início",
-      "title": "Boas-vindas ao __NAME__",
-      "order": 10,
-      "blocks": [
-        {
-          "type": "markdown",
-          "content": "Seu oon-app já está pronto para receber o domínio da solução. Esta Home é declarativa e renderizada pelo OonCore."
-        },
-        {
-          "type": "section",
-          "title": "O que o OonCore já entrega",
-          "description": "A base técnica comum está pronta para você concentrar a implementação nas regras do negócio.",
-          "blocks": [
-            {
-              "type": "markdown",
-              "content": "• Autenticação integrada, sessão e contexto do tenant.\n• Shell responsivo, navegação, roteamento e estados de carregamento e erro.\n• RBAC, catálogo de perfis e gestão de Usuários e Acessos.\n• Metadata, CRUD, formulários, tabelas, filtros, dashboards e esteiras declarativas.\n• Contratos para documentos, integrações, auditoria, validação e observabilidade."
-            }
-          ]
-        },
-        {
-          "type": "section",
-          "title": "O que a Plataforma Oon entrega",
-          "description": "O ciclo operacional do app permanece governado pela plataforma.",
-          "blocks": [
-            {
-              "type": "markdown",
-              "content": "• Repositório GitHub privado e código-fonte versionado.\n• Publicação automática em Dev a partir da branch main.\n• Ambiente isolado com aplicação, banco de dados, URL pública, certificado e secrets.\n• Acompanhamento no Workspace e no Meus Apps, com promoção controlada entre ambientes.\n• Documentação técnica e funcional centralizada no Oon Docs."
-            }
-          ]
-        },
-        {
-          "type": "section",
-          "title": "Próximos passos",
-          "blocks": [
-            {
-              "type": "markdown",
-              "content": "1. Rode npm install e npm run ooncore:docs para sincronizar a documentação local.\n2. Leia .ooncore/AGENTS.md e o contexto da versão instalada.\n3. Modele o domínio em backend/src/models e declare as telas em frontend/central.ui.json.\n4. Acrescente permissões de negócio e distribua-as entre os perfis no central.app.json.\n5. Rode npm run check, publique o repositório e acompanhe o ambiente de Dev."
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "collections": [],
-  "pipelines": [],
-  "documents": []
-}

package/templates/basic/backend/src/models/Pessoa.js

@@ -1,21 +0,0 @@
-const { defineModel, fields } = require("@oondemand/oon-core-back");
-
-/**
- * Pessoa — domínio puro: só schema + CRUD. Auth, RBAC, paginação, auditoria e
- * metadata vêm do Core. A tela é renderizada pelo front a partir da metadata.
- */
-defineModel({
-  name: "Pessoa",
-  singular: "pessoa",
-  basePath: "/pessoas",
-  schema: {
-    nome: fields.string({ required: true, label: "Nome" }),
-    email: fields.string({ label: "E-mail" }),
-    documento: fields.string({ label: "Documento" }),
-    tipo: fields.enum(["pf", "pj"], { label: "Tipo", default: "pf" }),
-    status: fields.enum(["ativo", "inativo"], { label: "Status", default: "ativo" }),
-  },
-  // A ativação de desenvolvimento concede o perfil "desenvolvedor".
-  // O papel "admin" permanece autorizado globalmente pelo RBAC do Core.
-  crud: { enabled: true, roles: { write: ["desenvolvedor"] } },
-});

package/templates/basic/frontend/central.ui.json

@@ -1,8 +0,0 @@
-{
-  "schemaVersion": 2,
-  "backend": { "metadataUrl": "/core/metadata" },
-  "navigation": { "mode": "auto" },
-  "collections": [{ "model": "Pessoa", "mode": "dynamic" }],
-  "pipelines": [],
-  "documents": []
-}

package/templates/documentos-fiscais/backend/central.config.js

@@ -1,32 +0,0 @@
-/**
- * Central __NAME__ — template documentos-fiscais. Liga o módulo de documentos
- * do Core (aprovação, anexos, status).
- */
-module.exports = {
-  ecosystem: { role: "member" },
-  activation: { enabled: true, configurationVersion: 1, fields: [] },
-  name: "__NAME__",
-  slug: "__SLUG__",
-
-  modules: {
-    collections: true,
-    documents: true,
-    pipelines: false,
-    integrations: false,
-    omie: false,
-    assistants: false,
-    currencies: false,
-  },
-
-  domain: {
-    models: "src/models",
-    validations: "src/validations",
-    triggers: "src/triggers",
-    hooks: "src/hooks",
-    mappings: "src/mappings",
-    documents: "src/documents",
-    pipelines: "src/pipelines",
-    integrations: "src/integrations",
-    routes: "src/routes",
-  },
-};

package/templates/documentos-fiscais/backend/src/models/DocumentoFiscal.js

@@ -1,23 +0,0 @@
-const { defineModel, fields } = require("@oondemand/oon-core-back");
-
-/**
- * Documento fiscal com fluxo de aprovação. O front (CoreDocument) usa o
- * `status` para badge e as actions RESTful approve/reject do Core.
- */
-defineModel({
-  name: "DocumentoFiscal",
-  singular: "documentoFiscal",
-  basePath: "/documentos-fiscais",
-  schema: {
-    numero: fields.string({ required: true, label: "Número" }),
-    tipo: fields.enum(["nfe", "nfse", "nfce", "outro"], { label: "Tipo", default: "nfe" }),
-    emitente: fields.string({ label: "Emitente" }),
-    valor: fields.currency({ label: "Valor" }),
-    dataEmissao: fields.date({ label: "Emissão" }),
-    status: fields.enum(["pendente", "aprovado", "reprovado"], {
-      default: "pendente",
-      label: "Status",
-    }),
-  },
-  crud: { enabled: true, roles: { write: ["admin"] } },
-});

package/templates/documentos-fiscais/frontend/central.ui.json

@@ -1,16 +0,0 @@
-{
-  "schemaVersion": 2,
-  "backend": { "metadataUrl": "/core/metadata" },
-  "navigation": { "mode": "auto" },
-  "collections": [],
-  "pipelines": [],
-  "documents": [
-    {
-      "model": "DocumentoFiscal",
-      "label": "Documentos fiscais",
-      "approval": true,
-      "attachments": true,
-      "section": "Fiscal"
-    }
-  ]
-}

package/templates/multi-moedas/backend/central.config.js

@@ -1,32 +0,0 @@
-/**
- * Central __NAME__ — template multi-moedas. Liga o módulo de moedas do Core
- * (cotações, conversão).
- */
-module.exports = {
-  ecosystem: { role: "member" },
-  activation: { enabled: true, configurationVersion: 1, fields: [] },
-  name: "__NAME__",
-  slug: "__SLUG__",
-
-  modules: {
-    collections: true,
-    documents: false,
-    pipelines: false,
-    integrations: false,
-    omie: false,
-    assistants: false,
-    currencies: true,
-  },
-
-  domain: {
-    models: "src/models",
-    validations: "src/validations",
-    triggers: "src/triggers",
-    hooks: "src/hooks",
-    mappings: "src/mappings",
-    documents: "src/documents",
-    pipelines: "src/pipelines",
-    integrations: "src/integrations",
-    routes: "src/routes",
-  },
-};