# OonCore Back - ativação de instâncias

O Core suporta `ecosystem.role` em `central.config.js`: `root` para a Central de Ativações e `member` (padrão) para demais Centrais. Aplicações `member` iniciam como `nao_ativada`, expõem apenas `/ativacao/*`, `/health` e `/version`, e só liberam autenticação/CRUD após ativação.

## Variáveis de ambiente

- `CENTRAL_ATIVACAO_URL`: URL pública/frontend da Central de Ativações.
- `CENTRAL_ATIVACAO_API_URL`: URL canônica do backend da Central de Ativações. Padrão: `https://central-ativacao.central.oondemand.online/api/`.
- `APP_CODE`: código do aplicativo no Ecossistema.
- `APP_ENVIRONMENT`: `desenvolvimento`, `homologacao` ou `producao`.
- `PUBLIC_APP_URL`: URL pública confirmada da Central.
- `INSTANCE_CREDENTIAL_ENCRYPTION_KEY`: chave para AES-256-GCM; obrigatória em produção.
- `AUTH_PROVIDER_TIMEOUT_MS`: timeout das chamadas à Central de Ativações.
- `INSTANCE_HEARTBEAT_INTERVAL_MS`: intervalo planejado para sincronização/heartbeat.

Compatibilidade temporária: `CENTRAL_ATIVACAO_BACKEND_URL` e `MEUS_APPS_BACKEND_URL` continuam aceitas como aliases da URL da API. Nunca aponte a URL da API para o próprio Core.

## Saúde operacional

- `GET /health/ready`: retorna HTTP 200 somente quando o MongoDB está conectado; retorna 503 enquanto o runtime não estiver pronto.
- `GET /health/version`: expõe as versões do OonCore e da Central, commit, release, build e ambiente da publicação.

Na imagem de entrega, essas rotas são publicadas pelo Nginx sob `/api/health/ready` e `/api/health/version`.

## Fluxo

`GET /ativacao/status` informa estado sem segredos. `POST /ativacao/validar-codigo` valida sem consumir. `POST /ativacao/concluir` revalida, chama `/ativar`, criptografa imediatamente o token da instância, executa hooks declarativos, chama `/concluir` e marca a instância como `ativa`. `POST /ativacao/tentar-novamente` retoma uma ativação já registrada sem exigir novo código.

Campos adicionais podem ser declarados em `activation.fields`; `password` e `secret` são sanitizados na configuração retornada ao frontend. Hooks opcionais: `validate`, `beforeComplete`, `afterComplete`.

## Imagem de entrega

O comando de delivery preserva `central.app.json` em dois pontos da imagem:

- `/src/central.app.json` durante o build do frontend declarativo;
- `/app/central.app.json` para descoberta pelo backend em runtime.

Centrais legadas sem o manifesto continuam suportadas. O empacotador cria uma pasta intermediária vazia, evitando tornar `central.app.json` obrigatório para aplicações que ainda usam somente `central.config.js`.

## Rótulos de campos relacionados

Por padrão, campos declarados com `fields.ref(...)` continuam sendo devolvidos pelo CRUD como `ObjectId`. Uma model pode optar pela população segura das referências usadas em grids e cards:

```js
defineModel({
  name: "Pedido",
  schema: {
    clienteId: fields.ref("Cliente", { required: true, label: "Cliente" }),
  },
  crud: {
    enabled: true,
    populateRefs: ["clienteId"],
  },
});
```

Use `populateRefs: true` para todas as referências da model ou informe uma lista explícita. O CRUD devolve somente `_id` e campos usuais de identificação, como nome, razão social, descrição, código, e-mail e campos pesquisáveis da model referenciada. Exportações mantêm os identificadores originais.