# 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:

```txt
 - 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

```json title="central.app.json"
{
  "$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](/docs/fundamentos/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).

> [!NOTE]
> A renderização de PDF é uma dependência de **infraestrutura** e é declarada em `oon.deploy.json`, não aqui. Veja [Capabilities](/docs/capabilities/visao-geral).

## Compatibilidade

```json
{ "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](/docs/backend/metricas-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

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

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

Fonte: https://sdk.oonapps.com/docs/fundamentos/manifesto-do-app