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

Capabilities são recursos técnicos que o App **consome sem conhecer a implementação**: endpoints, credenciais e serviços de infraestrutura são resolvidos pelo Core e pela Plataforma na publicação.

## Catálogo

| Capacidade | Backend | Frontend | Declaração | Local | Plataforma |
|---|---|---|---|---|---|
| Models e CRUD | `defineModel`, domain manifest | `CoreCollection`, hooks | models / `central.domain.json` | ✅ | ✅ |
| Metadata | `/core/metadata` | `useCoreMetadata` | models | ✅ | ✅ |
| Validações e fórmulas | `defineValidation`, regras | prévia reativa | domain manifest | ✅ | ✅ |
| Esteiras | process runtime | `CorePipeline` | `central.process.json` | ✅ | ✅ |
| Documentos | `defineDocument` | `CoreDocument` | UI | ✅ | ✅ |
| Dashboards | agregações | `CoreDashboard` | UI | ✅ | ✅ |
| RBAC | policy, `requirePermission` | `Can`, `PermissionGate` | `central.app.json` | Simulado | Identidade real |
| Tenant e escopo | access context, helpers | `TenantProvider` | `central.app.json` | Contexto técnico | Contexto autorizado |
| Auditoria | CRUD e request context | headers do SDK | automática | Local | Operacional |
| Rotas customizadas | `defineRoutes` | `useOonApi` | `backend/src/routes` | ✅ | ✅ |
| Arquivos | `files` (GridFS) | `useOonApi` | — | ✅ | ✅ |
| Métricas de uso | `usage` | — | `usageMetrics` | Não envia | ✅ |
| **E-mail transacional** | `capabilities.transactionalEmail` | `CoreTransactionalEmail` | `capabilities` + `capabilitySettings` | Fail-closed | Resolvido pelo Core |
| **Segredos V1** | `capabilities.secrets` | Formulário do App | `capabilities` + `capabilitySettings` | Chave local explícita | Chave por runtime/ambiente |
| **PDF** | `capabilities.pdf.render` | `useOonApi` (blob) | `oon.deploy.json` | Fail-closed | Resolvido pelo runtime |
| Publicação/promoção | serviço da Plataforma | Workspace | fluxo existente | ❌ | ✅ |
| Runtime local | sessão e guardas locais | bootstrap/banner | `OON_RUNTIME_MODE=local` | ✅ | — |

## Onde declarar

| Capability | Arquivo | Chave |
|---|---|---|
| `core.transactional-email` | `central.app.json` | `capabilities[]` + `capabilitySettings["core.transactional-email"]` |
| `core.secrets` | `central.app.json` | `capabilities[]` + `capabilitySettings["core.secrets"]` |
| `pdfRendering` | `oon.deploy.json` | `capabilities.pdfRendering` |

> [!IMPORTANT]
> O App **nunca** configura URL, credencial interna ou implementação de uma capability. A única exceção é a injeção de dublês documentada para testes automatizados.

## O que não existe (ainda)

- Não há contrato público genérico de **integration runtime** (outbox/inbox, locks, retry, webhooks).
- Workers de e-mail e jobs de recálculo são específicos — não são fila genérica.
- Execução durável genérica e diagnóstico padronizado de integrações são propostas separadas.

Se uma capability não tiver contrato suficiente, registre a lacuna — não descubra o contrato lendo fonte privada.

```cards
[
  { "title": "E-mail transacional", "href": "/docs/capabilities/email-transacional", "description": "Templates, envio idempotente, fila e painel." },
  { "title": "Renderização de PDF", "href": "/docs/capabilities/pdf", "description": "HTML → PDF sem conhecer a infraestrutura." },
  { "title": "Segredos (core.secrets)", "href": "/docs/capabilities/segredos", "description": "Credenciais cifradas por App, ambiente e tenant." },
  { "title": "Arquivos", "href": "/docs/backend/arquivos", "description": "GridFS por tenant, compartilhado entre réplicas." }
]
```

Fonte: https://sdk.oonapps.com/docs/capabilities/visao-geral