Documentação do OonCore

Introdução

• O que é o OonCore — A base para criar Centrais operacionais sob demanda — padronizadas, seguras e evolutivas — em que o seu código é apenas o domínio.
• Quickstart — Gere uma Central com o gerador oficial, rode localmente sem depender da plataforma e faça o primeiro cadastro.
• Estrutura do projeto — O que cada arquivo e pasta da Central gerada faz, o que é seu e o que pertence ao Core.
• Arquitetura — Como a Central, o oon-core-back, o oon-core-front e a Plataforma Oon dividem responsabilidades — e por que a fonte de verdade é sempre o backend.
• Primeira jornada — Uma pessoa abre uma página, executa uma ação e vê o resultado ou um erro útil — com endpoint privado, permissão e tratamento de erro.
• Desenvolvimento com IA/Agents — O OonCore distribui documentação canônica versionada em .ooncore/ para que Codex, Claude, ChatGPT, Kimi, Manus e outros Agents codifiquem dentro dos contratos.

Tutoriais

• Tutorial: central de compras com aprovação — Do zero a uma central de compras com fornecedores, pedidos com total calculado, esteira de aprovação com campos bloqueados e permissões por perfil — só com manifestos e duas páginas.
• Tutorial: do commit à Produção — O caminho completo de uma Central na Plataforma Oon — criar o App no Workspace, publicar em Desenvolvimento, homologar, promover para Produção, reverter e evoluir com novas versões.
• Tutorial: um App ao lado do ERP (clean core) — Mantenha o ERP no padrão e leve o processo específico para um App Oon — despesas com aprovação, credencial cifrada com core.secrets e lançamento idempotente no ERP por uma rota privada.

Fundamentos

• Manifesto central.app.json — Referência completa do manifesto do App (schemaVersion 2) — identidade, arquitetura, módulos, capabilities, compatibilidade, ativação, autenticação, RBAC e métricas de uso.
• Tipos de App e tenancy — appKind, disponibilidade, modo de acesso e tenancy — a matriz canônica de arquiteturas do Ecossistema Oon.
• Runtime local — Desenvolvimento desconectado em loopback, com sessão automática de até 30 dias, simulação de perfis e nenhuma dependência da Plataforma.
• Modos de runtime — As diferenças entre o runtime local desconectado e o runtime publicado na Plataforma.
• Ativação de instâncias — Como uma Central publicada se torna ativa na Plataforma Oon — estados, fluxo de ativação, campos de parametrização e variáveis injetadas pela publicação.
• Recursos nativos — O que usar do Core para cada necessidade, o que continua no App e os limites reais de isolamento, auditoria e execução — com o exemplo instalável /recursos.

Backend

• Models e CRUD — defineModel registra schema Mongoose, metadata, permissões e um router REST completo — listagem paginada, busca, leitura, criação, atualização, exclusão, import e export.
• Campos (fields) — As factories de campo do oon-core-back e os tipos equivalentes do manifesto de domínio, com metadata para o frontend.
• Manifesto de domínio — central.domain.json declara models, campos, fórmulas e validações sem um arquivo JavaScript por model — o Core constrói schema, metadata, CRUD e regras protegidas.
• Fórmulas e validações — Campos computed, a AST de expressões, validações entre campos e a prévia reativa nos formulários — uma única declaração, autoridade no backend.
• Esteiras e processos — central.process.json declara workflow, transições, bloqueios por etapa, bindings cross-model, proteção de exclusão e invariantes atômicas — executados pelo backend.
• Rotas privadas — defineRoutes registra endpoints próprios autenticados, com permissão declarada, auditoria opcional e omissão de corpo sensível nos logs.
• Validations e triggers — defineValidation valida o estado consolidado antes de persistir; defineTrigger registra efeitos antes e depois da mutação.
• Escopo e accessContext — req.accessContext carrega a identidade verificada; os helpers de escopo aplicam isolamento de tenant e usuário em consultas e mutações próprias.
• Erros — GenericError, o envelope de erro de domínio e como tratá-lo no frontend sem confundir 404 de proxy com sucesso vazio.
• Arquivos (GridFS) — files grava arquivos no MongoDB do App (bucket oon_files), isolados por tenant e compartilhados entre réplicas.
• Métricas de uso — Declare métricas no manifesto, registre consumo em lote com outbox resiliente e bloqueie operações quando o limite do plano for atingido.

Frontend

• defineOonApp e bootstrap — O contrato code-first do frontend — defineOonApp valida identidade, API, rotas, navegação e segurança; startOonApp monta providers, autenticação, tenant, shell e router.
• Rotas e navegação — defineOonRoutes e defineOonNavigation — rotas com guards de permissão, lazy loading, layouts por rota, rotas públicas, rotas reservadas e menu por seções.
• Shell e layouts — Variações do shell do Core, slots de layout, layouts por rota e páginas por blocos declarativos.
• Temas — createOonTheme, tokens semânticos, densidade, contraste e troca de tema em runtime com useOonTheme.
• Hooks e cliente HTTP — useOonApi, useOonResource, useCoreMetadata, useModelSchema, useOonAuth, useOonTenant e o gating de permissões com Can.
• Coleções (CoreCollection) — Grid, busca, filtros, formulário derivado da metadata, ações por linha, import/export e modal de detalhe — como componente ou como view declarativa.
• Modal de detalhe e grids — detailModal com abas summary, form, relatedGrid, readonlyGrid e customComponent; edição inline por linha; rowActions com interpolação, condições e refresh entre abas.
• Formulários e overrides — Formulários derivados da metadata com overrides pontuais — checkbox com valores de domínio, grupos, opções remotas dependentes e filtros de referência.
• Esteiras (CorePipeline) — Quadro kanban e lista para models com etapas — filtros, inclusão, modal de ticket com abas, ações padrão de aprovação e status de trabalho, e ações próprias.
• Documentos e dashboards — CoreDocument em modo CRUD ou biblioteca, e CoreDashboard com agregações count, sum, groupCount e groupSum executadas no backend.
• UI Kit (Core*) — Os componentes de interface do OonCore — status com vocabulário único, KPIs, tabela de dados responsiva, drawer de detalhe, confirmação, seções de formulário, estados e mais.

Segurança e acesso

• Autenticação e RBAC — Como o backend autentica, resolve tenant e acesso, aplica o RBAC declarado e publica o catálogo de perfis — e o que o frontend faz (e não faz) com isso.
• Usuários e Acessos — A gestão de usuários e convites que todo App member-central já traz — permissões nativas, quem convida, convites pela Central, página própria e endpoints.
• Fronteira de segurança local — As garantias do runtime local — loopback, cookies HttpOnly, CSRF, códigos de uso único — e suas limitações explícitas.
• Boas práticas — Regras obrigatórias de segurança, o checklist para Agents e o "faça / não faça" do OonCore.

Capabilities

• Visão geral — O catálogo de capacidades do OonCore — o que é declarado em manifesto, o que roda localmente e o que é resolvido pela Plataforma.
• E-mail transacional — core.transactional-email — configuração protegida, templates versionados, preview, envio idempotente, fila com retentativas e painel administrativo.
• Renderização de PDF — capabilities.pdf.render transforma HTML em PDF sem conhecer endpoint, credencial ou implementação — com limites, cancelamento e erros com retryable.
• Segredos (core.secrets) — Credenciais de integrações cifradas com AES-256-GCM, com chave por runtime e ambiente — put, status, use e remove a partir do contexto autorizado.

Operação

• Testes, doctor e conformance — Uma entrada de checks para o App — doctor reúne versões, lockfiles, manifestos, cache de docs e conformance — e o que cada prova cobre (e não cobre).
• Empacotamento da imagem — O que vai (e o que não vai) para a imagem do Oon-App, como assets e dependências devem ser declarados e como a imagem é validada antes do deploy.
• Publicação e ambientes — Do commit ao ambiente de Dev pelo Workspace e pela Central de Ativações; promoção para HML e Produção, réplicas, domínios personalizados e diagnóstico.
• Atualizando o Core — Atualização coordenada de oon-core-back, oon-core-front e create-central-oon — sempre juntos, com cache de docs, compatibilidade e validação.
• Contenção do MongoDB — A política interna de pool e tempo de execução do Core, os erros DATABASE_POOL_BUSY e DATABASE_OPERATION_TIMEOUT e como recuperar sem repetir escritas.
• Troubleshooting — Sintomas comuns no desenvolvimento local e na publicação, com a verificação e a correção de cada um.

Referência

• CLI — Referência dos comandos de create-central-oon, oonCore-back e oonCore-front.
• API oon-core-back — Todos os exports públicos de @oondemand/oon-core-back, agrupados por finalidade.
• API oon-core-front — Todos os exports públicos de @oondemand/oon-core-front e de seus subpaths ui, routing, theme, hooks e testing.
• Endpoints /core — As rotas HTTP fornecidas pelo backend do Core — status, autenticação, ativação, runtime local, metadata, acesso e e-mail transacional.
• Códigos de erro — Todos os códigos de erro públicos do OonCore, agrupados por origem, com status HTTP e significado.
• Variáveis de ambiente — As variáveis lidas pelo backend e pelo frontend — quais você configura localmente e quais são injetadas pela Plataforma.
• Glossário — Os termos do OonCore e da Plataforma Oon.