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

Instale o exemplo em uma base limpa e abra **Primeira jornada** (`/jornada`) e **Recursos nativos** (`/recursos`):

```bash
npx --no-install create-central-oon example
npm run dev
```

O exemplo verifica colisões antes de escrever e não sobrescreve trabalho existente. As fontes ficam em `examples/first-journey` do gerador e são as mesmas executadas pelos testes do SDK com Core e MongoDB reais.

## O que usar e o que continua no App

| Necessidade | Recurso público | Fronteira |
|---|---|---|
| Cadastro, lista, formulário | `defineModel`, `fields`, CRUD, metadata, `CoreCollection` | Não salvar segredos no CRUD genérico |
| Regras do próprio registro | `central.domain.json`: `validations` e `computed` | AST fechada; o backend recalcula e recusa adulteração |
| Etapas e bloqueios | `central.process.json`: workflow; `CorePipeline` | PATCH direto também precisa satisfazer a regra |
| Valores relacionados | bindings `lookup`, `aggregate`, `expression` | Dependências e filtros declarados |
| Limite concorrente | `relatedSumLteParentField` | Transação MongoDB exige replica set |
| Documentos | `CoreDocument` | Cadastro de textos; não promete upload, aprovação ou assinatura |
| Indicadores | `CoreDashboard`: count, sum, groupCount | Agrega no backend |
| UX específica | Página React, `useOonApi`, componentes públicos | Não substituir shell, sessão, RBAC ou guards |
| Rota/dado autorizado | `defineRoutes`, `req.accessContext`, helpers de escopo | Contexto vem da autenticação |
| Rastreabilidade | Auditoria do CRUD, `audit`, requestLog, `sensitiveBody` | Nenhum desses recursos cifra dados de domínio |
| PDF / e-mail | `capabilities.pdf.render`, `capabilities.transactionalEmail.send` | Não são fila genérica de integração |
| Arquivos | `files` (GridFS por tenant) | Limite padrão de 25 MB por arquivo |

## Roteiro do exemplo

1. **Contratos** — crie título `Exemplo`, quantidade `2`, valor unitário `50`. O backend calcula `total=100`; uma validação limita o total a 1000; um PATCH com total adulterado é recusado.
2. **Parcelas** — selecione o contrato e informe 40. O *lookup* preenche `tituloContrato`, o *aggregate* atualiza `pago=40` e a *expression* produz `saldo=60`. Renomeie o contrato: o lookup é recalculado assincronamente.
3. **Feche o contrato** — `lockedFieldsByStage` impede alterar título, quantidade e valor; não é permitido voltar para Aberto. Uma parcela de 61 é recusada pela invariante; duas requisições simultâneas de 40 disputando saldo 60 resultam em uma inclusão e uma recusa; excluir o contrato com parcelas é bloqueado.

> [!NOTE]
> A invariante está na model filha: não garante que reduzir o total de um pai aberto preserve a soma anterior. A aplicação real precisa definir sua política de alteração do pai.

## Limites de execução

- `recalculate: "async"` e `drainProcessJobs()` atendem recálculos do processo; a fila interna **não** é um contrato público de enqueue/claim/retry.
- A fila transacional de e-mail é específica de e-mail.
- Integrações, mapeamentos fiscais, idempotência de efeitos externos e recuperação de negócio continuam no App.
- Não há API genérica de "integration runtime" (outbox/inbox, locks, webhooks) nesta release.

## Evidências

A suíte do SDK cobre fórmulas, adulteração, validação, lookup, agregado, recálculo assíncrono, transição/bloqueio, exclusão protegida, concorrência transacional, metadata, dashboard, escopo, auditoria, 401/403 e PDF indisponível. **Build, release npm, publicação e homologação do App são estados distintos.**

Fonte: https://sdk.oonapps.com/docs/fundamentos/recursos-nativos