@oondemand/create-central-oon 0.3.10 → 0.3.12

package/docs/FRONTEND_PATTERNS.md

@@ -1,8 +1,9 @@
 # Padrões Frontend
 
-O frontend da Central deve ser declarativo. Shell, providers, rotas, menu, datagrid, formulários, documentos e esteiras pertencem ao `@oondemand/oon-core-front`.
+O frontend da Central deve ser declarativo. Shell, providers, rotas, menu, datagrid, formulários, documentos, esteiras, modais de detalhe e grids relacionados pertencem ao `@oondemand/oon-core-front`.
 
 Para a lista completa de opções do manifesto, use `FRONTEND_MANIFEST_REFERENCE.md`.
+Para UX avançada com abas e itens relacionados, use também `ADVANCED_UX_PATTERNS.md` e `DETAIL_MODAL_AND_RELATED_GRIDS.md`.
 
 ## Estrutura esperada
 
@@ -34,14 +35,79 @@ Use `central.ui.json` como entrada principal para declarar:
 - agrupamentos;
 - layout v2;
 - páginas por blocos;
-- renderers por chave.
+- renderers por chave;
+- modais de detalhe;
+- abas;
+- relações;
+- grids relacionados;
+- edição inline;
+- ações por linha.
 
 ## Manifesto v1 e v2
 
 - Manifesto sem `schemaVersion` mantém compatibilidade v1.
-- Manifesto com `schemaVersion: 2` habilita composição por `layout`, `navigation`, `pages` e `blocks`.
+- Manifesto com `schemaVersion: 2` habilita composição por `layout`, `navigation`, `pages`, `blocks`, coleções avançadas e componentes declarativos.
 - Componentes React não devem ser serializados no JSON; use chaves e registre os componentes no `registry` em TypeScript.
 
+## Padrão de tela operacional
+
+A tela principal de uma coleção operacional deve ser simples:
+
+```txt
+Título
+Filtros
+Busca
+Botão novo
+Grid principal
+Ações por linha
+```
+
+Ela não deve acumular detalhe de filhos, formulários longos ou fluxos complexos abaixo do grid. Use `detailModal` para concentrar a operação do registro.
+
+## Padrão de detalhe avançado
+
+Quando a operação envolve um registro principal e seus relacionamentos, use:
+
+```txt
+CoreDetailModal
+├── Resumo
+├── Dados Principais
+├── RelatedGrid editável
+└── ReadonlyGrid
+```
+
+Exemplos:
+
+- Projeto -> Itens -> Pagamentos
+- Pedido -> Produtos -> Entregas
+- Contrato -> Parcelas -> Documentos
+- Cliente -> Atividades -> Histórico
+
+## Formulários agrupados
+
+Campos longos devem ser agrupados por sentido de negócio:
+
+- Identificação;
+- Evento/Faturamento;
+- Equipe;
+- Regras;
+- Totais;
+- Observações.
+
+Prefira `form.groups` em vez de criar uma tela customizada apenas para organizar campos.
+
+## Grids relacionados
+
+Quando o usuário precisa operar filhos do registro principal, use `relatedGrid`.
+
+Regras:
+
+- Relação deve usar `foreignKey` + `parentKey`.
+- Edição inline deve ser usada para ajustes rápidos de muitos itens.
+- Ação por linha deve ser declarada como `rowActions`.
+- A regra de negócio da ação fica no backend da Central.
+- O Core deve executar e atualizar a interface.
+
 ## Regras
 
 - Não recrie layout completo se o Core já renderiza.
@@ -50,6 +116,7 @@ Use `central.ui.json` como entrada principal para declarar:
 - Não hardcode endpoints quando a metadata puder fornecer.
 - Não crie variações visuais fora do padrão sem necessidade real.
 - Use overrides pequenos, específicos e documentados.
+- Não crie página React customizada para resolver apenas: filtro, modal, abas, agrupamento de campos, grid relacionado ou ação por linha.
 
 ## Overrides
 
@@ -60,7 +127,8 @@ Overrides são permitidos para:
 - card customizado;
 - cabeçalho customizado;
 - dashboard customizado;
-- integração visual pontual.
+- integração visual pontual;
+- aba customizada dentro de `detailModal`.
 
 Overrides não devem virar uma reimplementação do Core.
 
@@ -74,4 +142,10 @@ A Central deve manter o padrão OonCore:
 - feedback visual;
 - status por badges;
 - ações rastreáveis;
-- responsividade.
+- responsividade;
+- edição inline quando melhora a produtividade;
+- detalhe em modal quando o registro possui relações operacionais.
+
+## Contrato avançado implementado
+
+Para telas mestre-detalhe, declare `detailModal` diretamente na coleção. A aba `form` salva o registro principal, `relatedGrid` busca filhos por `foreignKey=parent[parentKey]` e permite edição inline quando `editable: true` e `editMode: "inline"`, e `readonlyGrid` lista relações sem edição. Use `refresh` nas ações para coordenar recarga de `self`, `parent`, `all` ou abas específicas.

package/docs/PORTAL_COCKPIT_PATTERNS.md

@@ -0,0 +1,150 @@
+# Portal/Cockpit com OonCore
+
+Este padrão atende aplicações como **Meus Apps**, Portal do Cliente, Portal de Parceiros, Suporte, Copilotos e outros Cockpits first-party.
+
+O objetivo é evitar que um portal precise recriar Shell, Router, AuthProvider, Menu, Guards e SDK HTTP. O portal deve usar o `central.ui.json` + `startFromManifest` e registrar apenas os componentes realmente customizados.
+
+## Perfis arquiteturais
+
+O OonCore diferencia três perfis:
+
+| Perfil | Uso |
+| --- | --- |
+| `root-central` | Central de Ativações, raiz de confiança. |
+| `member-central` | Central cliente/licenciada, ativada por instância. |
+| `portal-cockpit` | Portal/Cockpit first-party, autenticado por AppClient/BFF. |
+
+## Auth modes
+
+| `auth.mode` | Uso |
+| --- | --- |
+| `bearer` | Token local simples, compatível com Centrais existentes. |
+| `cookie` | Sessão futura via cookie HTTP-only. |
+| `external-sso` | Redireciona para login externo. |
+| `central-instance` | Central membro usando instância ativada. |
+| `central-client` | Portal/Cockpit usando AppClient/BFF. |
+
+## Capabilities no manifesto
+
+Além de `permissions`, o manifesto pode declarar `capabilities`. Elas são permissões dinâmicas vindas da Central de Ativações e evitam criar campos fixos para cada produto.
+
+Exemplos:
+
+```txt
+apps:read
+users:manage
+tickets:read
+tickets:assign
+copilots:read
+copilots:test
+billing:read
+```
+
+O Core trata `permissions` e `capabilities` como requisitos de UI. A segurança real continua no backend.
+
+## Manifesto recomendado
+
+```json
+{
+  "schemaVersion": 2,
+  "name": "Portal Cliente",
+  "slug": "portal-cliente",
+  "appKind": "portal-cockpit",
+  "auth": {
+    "mode": "central-client",
+    "tokenParam": "code"
+  },
+  "layout": {
+    "shell": "portal",
+    "sidebar": "core",
+    "topbar": "none",
+    "header": "none",
+    "footer": "core"
+  },
+  "navigation": {
+    "mode": "manual",
+    "items": [
+      { "label": "Meus Apps", "href": "/apps", "capabilities": ["apps:read"], "order": 10 },
+      { "label": "Suporte", "href": "/suporte", "capabilities": ["tickets:read"], "order": 20 },
+      { "label": "Copilotos", "href": "/copilotos", "capabilities": ["copilots:read"], "order": 30 },
+      { "label": "Usuários", "href": "/usuarios", "capabilities": ["users:manage"], "order": 40 }
+    ]
+  },
+  "pages": [
+    { "path": "/apps", "label": "Meus Apps", "component": "AppsPortalPage", "capabilities": ["apps:read"] },
+    { "path": "/suporte", "label": "Suporte", "component": "SupportPage", "capabilities": ["tickets:read"] },
+    { "path": "/copilotos", "label": "Copilotos", "component": "CopilotsPage", "capabilities": ["copilots:read"] },
+    { "path": "/usuarios", "label": "Usuários", "component": "UsersPermissionsPage", "capabilities": ["users:manage"] }
+  ],
+  "collections": [],
+  "pipelines": [],
+  "documents": []
+}
+```
+
+## Bootstrap recomendado
+
+```ts
+import { startFromManifest } from "@oondemand/oon-core-front";
+import manifest from "../central.ui.json";
+import { AppsPortalPage } from "./custom/AppsPortalPage";
+import { SupportPage } from "./custom/SupportPage";
+import { CopilotsPage } from "./custom/CopilotsPage";
+import { UsersPermissionsPage } from "./custom/UsersPermissionsPage";
+
+startFromManifest(manifest, {
+  apiBaseUrl: import.meta.env.VITE_API_URL,
+  appKind: "portal-cockpit",
+  auth: {
+    mode: "central-client"
+  },
+  customComponents: {
+    AppsPortalPage,
+    SupportPage,
+    CopilotsPage,
+    UsersPermissionsPage
+  }
+});
+```
+
+## Contrato esperado do BFF
+
+O frontend conversa apenas com o BFF do portal. O BFF fala com a Central de Ativações usando AppClient.
+
+Rotas genéricas esperadas no BFF podem espelhar a Central de Ativações:
+
+```http
+GET /api/portal/contexto
+GET /api/portal/apps
+GET /api/portal/apps/:appCode
+GET /api/portal/apps/:appCode/capabilities
+POST /api/portal/apps/:appCode/authorize
+```
+
+O BFF também pode expor rotas de domínio próprias, como:
+
+```http
+GET /api/suporte/tickets
+POST /api/suporte/tickets
+GET /api/copilotos/assistentes
+POST /api/copilotos/assistentes/:id/testar
+```
+
+Essas rotas de domínio validam capability na Central de Ativações antes de executar a ação.
+
+## Regra de segurança
+
+O frontend nunca deve receber `clientSecret`, `x-oon-instance-token`, hash de credencial ou segredo completo. Portais devem falar com um BFF próprio, e o BFF fala com a Central de Ativações usando AppClient.
+
+## Quando usar página custom
+
+Use página custom apenas quando a tela não for CRUD/esteira/documento declarativo, por exemplo:
+
+- cards de apps licenciados;
+- matriz de permissões;
+- cockpit de status;
+- tickets de suporte;
+- gestão de copilotos;
+- onboarding orientado por negócio.
+
+Mesmo nesses casos, o Shell, Router, Auth, Menu, Guards e SDK HTTP devem continuar no Core.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "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.10"
+    "@oondemand/oon-core-back": "^0.3.12"
   }
 }

package/templates/_base/frontend/package.json

@@ -10,7 +10,7 @@
     "sync:metadata": "oonCore-front sync:metadata"
   },
   "dependencies": {
-    "@oondemand/oon-core-front": "^0.3.10",
+    "@oondemand/oon-core-front": "^0.3.12",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",