Docs › 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.

O central.app.json fica na raiz do App (ou em backend/) e é a declaração de quem o App é e o que ele pode fazer. É validado no boot do backend, pela conformance e pela publicação. Um manifesto inválido interrompe o startup listando cada problema:

 - compatibility.core.minVersion: requer OonCore 0.8.0 ou superior; instalado 0.7.43.
 - rbac.roles[1].permissions[0]: permissão não declarada: pedidos.aprovar.

Exemplo completo

{
  "$schema": "./node_modules/@oondemand/create-central-oon/schemas/central.app.schema.json",
  "schemaVersion": 2,
  "id": "central-compras",
  "name": "Central de Compras",
  "slug": "central-compras",
  "appKind": "member-central",
  "tenancyModel": "single_tenant",
  "availability": "self",
  "accessMode": "explicit_users",
  "authorizationMode": "rbac",
  "modules": {
    "collections": true,
    "documents": false,
    "pipelines": true,
    "assistants": false,
    "currencies": false
  },
  "capabilities": ["core.transactional-email"],
  "capabilitySettings": {
    "core.transactional-email": {
      "enabled": true,
      "scopePolicy": "tenant_override",
      "retentionDays": 30,
      "attachmentsPolicy": { "allowed": false },
      "templates": [{ "code": "pedido-aprovado", "definition": "./backend/emails/pedido-aprovado.json", "initialStatus": "active" }]
    }
  },
  "compatibility": {
    "core": { "minVersion": "0.7.43", "maxVersionExclusive": "0.8.0" }
  },
  "activation": { "enabled": true, "configurationVersion": 1, "fields": [] },
  "auth": { "invitations": "central" },
  "rbac": {
    "invitationTtlHours": 72,
    "permissions": ["pedidos.read", "pedidos.write", "pedidos.approve"],
    "roles": [
      { "code": "admin", "name": "Administrador", "admin": true, "permissions": ["*"] },
      { "code": "comprador", "name": "Comprador", "permissions": ["pedidos.read", "pedidos.write"] },
      { "code": "gestor", "name": "Gestor", "permissions": ["pedidos.read", "pedidos.approve", "users.read", "users.invite"] },
      { "code": "viewer", "name": "Consulta", "permissions": ["pedidos.read"] }
    ]
  },
  "usageMetrics": [
    { "code": "pedidos", "name": "Pedidos emitidos", "unit": "pedido", "defaults": { "included": 500, "onLimit": "block" } }
  ]
}

Identidade

Campo Regra
schemaVersion Obrigatório; deve ser 2.
id Letras minúsculas, números, ., - ou _. Usado como app.id no frontend.
name Texto não vazio.
slug Minúsculas separadas por hífen.
appKind member-central, root-central ou portal-cockpit.

Arquitetura

Campo Valores
tenancyModel none, single_tenant, multi_tenant
availability system, common, self, licensed
accessMode tenant_members, explicit_users, authenticated_users
authorizationMode none, rbac
deploymentMode Omitir em manifestos novos — o Core deriva do tenancy.

As combinações são validadas por appArchitecture.resolveAppArchitecture. Veja a matriz em Tipos de App e tenancy.

Módulos

modules é um objeto de booleanos com as chaves collections, documents, pipelines, assistants e currencies. Chaves desconhecidas são rejeitadas.

Capabilities

  • capabilities — lista de identificadores namespaced e únicos, como core.transactional-email ou core.secrets.
  • capabilitySettings — configuração por capability (nunca credenciais).

Compatibilidade

{ "compatibility": { "core": { "minVersion": "0.7.43", "maxVersionExclusive": "0.8.0" } } }

Ambos usam versão semântica. O scaffold gera minVersion igual à release e maxVersionExclusive igual à próxima minor. Só aumente o mínimo depois de validar a migração.

Ativação

Campo Regra
activation.enabled Booleano.
activation.configurationVersion Inteiro ≥ 1.
activation.fields Lista de campos de parametrização da instância.

Autenticação

Campo Valores
auth.invitations local (padrão) ou central — convites geridos pela Central de Ativações.
auth.sessionScope ecosystem — sessão de ecossistema para portais globais.

RBAC

Campo Regra
rbac.permissions Lista de permissões no formato recurso.acao (^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$), sem duplicatas.
rbac.roles Pelo menos um perfil; pelo menos um administrativo.
roles[].code Código estável em minúsculas (^[a-z][a-z0-9_-]*$).
roles[].name Obrigatório. description opcional.
roles[].permissions Somente permissões declaradas em rbac.permissions, nativas do Core ou "*".
roles[].admin Booleano; obrigatório true quando o perfil usa "*".
rbac.invitationTtlHours Inteiro entre 1 e 720.

Permissões nativas do Core não precisam ser declaradas: users.read, users.invite, users.update, users.disable, roles.read.

Métricas de uso

usageMetrics aceita até 10 métricas que a Central usa para pré-preencher os limites dos planos. Veja Métricas de uso.

Campo Regra
code ^[a-z][a-z0-9_.-]{1,62}$, único
name Obrigatório, até 80 caracteres
unit, description Opcionais
defaults.included Inteiro ≥ 0
defaults.onLimit block ou auto_addon
defaults.overage { mode: "unit" | "block", priceMinor, blockSize? }

Validação programática

const { validateAppManifest, loadAppManifest, AppManifestError } = require("@oondemand/oon-core-back");

try {
  loadAppManifest(process.cwd());
} catch (error) {
  if (error instanceof AppManifestError) console.error(error.issues);
}