@oondemand/oon-core-back

OonCore Back - ativação de instâncias

Runtime local desconectado

Com NODE_ENV=development e OON_RUNTIME_MODE=local, o Core escuta apenas em 127.0.0.1, cria uma sessão técnica local de até 30 dias e não consulta a Central de Ativações. Códigos independentes e de uso único atendem navegador e automação/seed. Apps com tenant usam o contexto virtual fixo local:tenant, sem criar um recurso. O estado é ativa_local; nenhuma instância, licença, Deployment ou credencial operacional é criada. Produção, Kubernetes, bind externo e identidade operacional falham no startup.

O scaffold configura esse fluxo. Não use DEV_TOKEN em uma Central nova.

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.

Catálogo público de perfis

Todo App com RBAC declarado expõe GET /core/role-catalog. O contrato schemaVersion: 1 contém appCode, enabled e roles[] com code, name, description e admin. Desde o SDK 0.7.1, a extensão aditiva opcional roles[].commercialPermissions publica nomes explícitos de permissões funcionais permitidas pelo papel. Wildcards são expandidos somente pelas permissões declaradas em rbac.permissions; wildcard literal e namespaces tenant, publications, homologation, production, apps, users e roles são excluídos. Políticas internas e permissões técnicas não são publicadas.

O campo permanece opcional no schemaVersion 1: catálogos anteriores são conformes para descoberta e fluxos existentes. O novo aceite comercial inicial requer essa capacidade e deve falhar fechado com APP_ROLE_CATALOG_UNAVAILABLE quando ausente; não se infere autoridade do nome admin. Consumidores antigos devem tolerar campos adicionais. O runtime continua intersectando cada grant explícito com a política local atual.

O endpoint é somente leitura, usa cache público de cinco minutos e não concede autorização.

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.

O campo deployment.environment usa exclusivamente APP_ENVIRONMENT. A variável NODE_ENV=production configura a execução técnica do Node dentro da imagem e não representa o ambiente lógico 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:

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.