@oondemand/oon-core-back 0.1.0

package/LICENSE

@@ -0,0 +1,91 @@
+# LICENÇA DE USO RESTRITO DO CÓDIGO-FONTE OONDEMAND
+**ODR‑NC v1.0 — Non‑Commercial, Internal‑Use Only**
+
+Copyright (c) 2025 OonDemand. Todos os direitos reservados.
+
+## 1. Definições
+**“Licenciante”**: OonDemand.  
+**“Código”**: todo o conteúdo deste repositório e seus derivados.  
+**“Licenciada”** ou **“Usuário Autorizado”**: a pessoa jurídica nominalmente autorizada pela Licenciante (via contrato ou arquivo `AUTORIZACOES.md`).  
+**“Uso Interno Não Comercial”**: uso exclusivo dentro da organização da Licenciada, para suas próprias operações internas, sem disponibilização a terceiros e sem geração de receita direta ou indireta a partir do Código, incluindo sem se limitar a: revenda, prestação de serviços a terceiros, franquia, SaaS, consultoria, sublicenciamento, distribuição ou incorporação em produtos/serviços comercializados.
+
+## 2. Concessão Limitada
+Sujeito ao cumprimento integral desta Licença, a Licenciante concede à Licenciada uma licença **não exclusiva, intransferível e revogável** para **acessar, visualizar, modificar, compilar e executar** o Código **exclusivamente para Uso Interno Não Comercial**. Nenhum direito é concedido para **distribuir, publicar, sublicenciar, ceder** ou **oferecer a terceiros** o Código (ou obras derivadas).
+
+Qualquer **Uso Comercial** (incluindo oferta como serviço, SaaS, revenda, consultoria, integração para clientes externos ou uso em qualquer outra empresa do mesmo grupo econômico) **exige autorização prévia e expressa da Licenciante, por escrito** e com condições comerciais específicas. Na ausência de tal autorização, o Uso Comercial é **estritamente proibido**.
+
+## 3. Restrições e Obrigações
+A Licenciada se compromete a:
+1. **Não** remover ou alterar avisos de copyright, marcas, avisos de confidencialidade e desta Licença;
+2. **Não** publicar ou tornar o Código (ou parte significativa) acessível publicamente (incl. repositórios públicos, fóruns, pacotes);
+3. **Não** distribuir, vender, revender, licenciar, sublicenciar, alugar, arrendar, franquear, ceder ou transferir o Código a terceiros;
+4. **Não** utilizar o Código para treinar modelos de IA, realizar engenharia reversa de mecanismos de licenciamento ou produzir obra concorrente direta;
+5. Adotar controles de acesso (RBAC), registro de auditoria e medidas razoáveis de segurança para impedir uso não autorizado; e
+6. Garantir que terceiros (funcionários, prestadores) observem as mesmas obrigações de confidencialidade e uso restrito.
+
+## 4. Propriedade Intelectual
+O Código é protegido por leis de propriedade intelectual. **A titularidade integral permanece com a Licenciante**. Exceto pelos direitos limitados concedidos nesta Licença, **nenhum outro direito** (explícito, implícito, por estoppel) é concedido.
+
+## 5. Autorização Expressa para Uso Comercial
+Qualquer permissão de Uso Comercial deverá:
+- Ser **prévia e por escrito**, concedida pela Licenciante;
+- Constar em contrato específico **ou** no arquivo `AUTORIZACOES.md` deste repositório, com **razão social/CNPJ**, **escopo**, **prazo** e **condições comerciais**; e
+- Ser **revogável** por descumprimento.
+
+## 6. Cláusula Penal (Multa) por Uso Indevido
+O uso em desacordo com esta Licença (incluindo Uso Comercial sem autorização) sujeitará a Licenciada ao pagamento de **cláusula penal não compensatória** no valor de **R$ 600.000,00 (seiscentos mil reais) por infração**, **cumulável** com:
+- **R$ 5.000,00 (cinco mil reais) por dia** enquanto perdurar a infração; e
+- Indenização adicional por **perdas e danos** e **honorários advocatícios**.
+A aplicação desta cláusula penal **não limita** o direito da Licenciante de buscar tutela específica, inclusive **medidas liminares/inibitórias**.
+
+## 7. Confidencialidade
+O Código e a documentação correlata constituem **informação confidencial**. A Licenciada deve preservá-la com o mesmo grau de zelo usado para suas informações confidenciais, nunca inferior ao razoável.
+
+## 8. Ausência de Garantias; Limitação de Responsabilidade
+O Código é fornecido “**no estado em que se encontra**”, sem garantias de qualquer tipo. Na máxima extensão permitida em lei, a Licenciante **não responde** por danos indiretos, lucros cessantes, perda de dados ou danos especiais. A responsabilidade total da Licenciante, por qualquer teoria, **fica limitada ao valor total efetivamente pago** pela Licenciada em favor da Licenciante pelo direito de uso do Código, se houver.
+
+## 9. Vigência, Revogação e Auditoria
+Esta Licença vigora enquanto o Código estiver em posse da Licenciada e poderá ser **revogada** a qualquer tempo em caso de violação. A Licenciante poderá solicitar **evidências razoáveis de conformidade** (ex.: lista de usuários, ambientes de execução) mediante aviso prévio escrito de 5 dias úteis.
+
+## 10. Terceiros e Dependências
+Componentes de terceiros incluídos no repositório permanecem regidos por suas **próprias licenças**. Em caso de conflito, prevalece a licença do respectivo terceiro para tal componente.
+
+## 11. Lei Aplicável e Foro
+Aplica-se a legislação brasileira. Fica eleito o **Foro da Comarca de São Paulo/SP**, com renúncia a qualquer outro, por mais privilegiado que seja.
+
+## 12. Disposições Finais
+Se qualquer cláusula for considerada inválida, as demais permanecem válidas. Qualquer tolerância não implicará renúncia. Esta é a versão **ODR‑NC v1.0**. A Licenciante poderá publicar **atualizações** desta Licença; versões futuras não terão efeito retroativo sem aceite da Licenciada.
+
+---
+
+### Identificação de Autorização (opcional, para uso interno)
+> Este repositório está licenciado para uso interno por: **[RAZÃO SOCIAL]**, **CNPJ [XX.XXX.XXX/0001-XX]**, conforme autorização datada de **[DATA]** e/ou contrato específico. Escopo: **[DESCREVER]**.
+
+### Como cumprir esta Licença
+1) Mantenha este arquivo `LICENSE.md` na raiz do repositório;  
+2) Liste autorizações de uso comercial, se houver, em `AUTORIZACOES.md`; e  
+3) Inclua o cabeçalho de licença abaixo em **cada arquivo-fonte**.
+
+---
+
+## Cabeçalho de Licença para Arquivos-Fonte
+Copie e adapte o bloco conforme a linguagem:
+
+### Padrão (C/Java/JS/TS)
+/*
+ OonDemand — Código-Fonte Proprietário
+ Licença ODR‑NC v1.0 — Uso interno não comercial. Proibida revenda/redistribuição/uso comercial sem autorização expressa da OonDemand. Violação sujeita à multa, conforme LICENSE.md.
+ (c) 2025 OonDemand. Todos os direitos reservados.
+*/
+
+### Python
+"""
+OonDemand — Código-Fonte Proprietário
+Licença ODR‑NC v1.0 — Uso interno não comercial. Proibida revenda/redistribuição/uso comercial sem autorização expressa da OonDemand. Violação sujeita à multa, conforme LICENSE.md.
+(c) 2025 OonDemand. Todos os direitos reservados.
+"""
+
+### Shell/YAML
+# OonDemand — Código-Fonte Proprietário
+# Licença ODR‑NC v1.0 — Uso interno não comercial. Proibida revenda/redistribuição/uso comercial sem autorização expressa da OonDemand. Violação sujeita à multa, conforme LICENSE.md.
+# (c) 2025 OonDemand. Todos os direitos reservados.

package/README.md

@@ -0,0 +1,130 @@
+# @oondemand/oon-core-back
+
+Core runtime para **Centrais Oon**. O backend de uma Central passa a ser
+apenas domínio: você escreve `central.config.js` + `src/models` (e, quando
+preciso, `validations / triggers / pipelines / documents / integrations /
+routes`) e sobe tudo com `oonCore-back start`.
+
+Toda a infraestrutura — boot, banco, auth, RBAC, logs, auditoria, paginação,
+metadata, CRUD, módulos opinativos (Omie, Assistentes, Multi-moedas, Esteiras,
+Documentos) e deploy (Docker + k8s) — vive aqui dentro.
+
+## Instalação
+
+```bash
+npm install @oondemand/oon-core-back
+```
+
+## Uso mínimo
+
+`central.config.js`:
+
+```js
+module.exports = {
+  serviceName: "minha-central",
+  // opcional: provedor de auth (default = Meus Apps)
+  // auth: { verifyToken: async (token) => ({ tipo, nome, email }) },
+};
+```
+
+`src/models/Produto.js`:
+
+```js
+const { defineModel, fields } = require("@oondemand/oon-core-back");
+
+defineModel({
+  name: "Produto",
+  schema: {
+    nome: fields.string({ required: true }),
+    preco: fields.currency(),
+    moeda: fields.currencyCode(),
+  },
+  crud: { enabled: true, roles: { write: ["admin"] } },
+});
+```
+
+Subir:
+
+```bash
+npx oonCore-back start   # produção
+npx oonCore-back dev     # watch/reload
+```
+
+Isso já expõe, para `Produto`:
+
+```
+GET    /produtos            (list + paginação/filtros/busca/ordenação)
+GET    /produtos/:id
+POST   /produtos
+PUT    /produtos/:id
+PATCH  /produtos/:id
+DELETE /produtos/:id
+POST   /produtos/import
+GET    /produtos/export
+```
+
+Todas privadas (auth obrigatório), com RBAC e auditoria nas mutações.
+
+## API pública
+
+```js
+const {
+  start, createApp, activate,
+  defineCentral, defineModel, fields,
+  defineCollection, defineDocument, definePipeline,
+  defineOmieMapping, defineRoutes, defineValidation, defineTrigger,
+  omie, GenericError, registry,
+} = require("@oondemand/oon-core-back");
+```
+
+### `defineRoutes` — rotas customizadas com o contrato de segurança
+
+Nunca se usa `express.Router()` cru. `router.private.*` aplica auth + RBAC
+(+ auditoria opcional); `router.public.*` é aberto.
+
+```js
+const { defineRoutes } = require("@oondemand/oon-core-back");
+
+defineRoutes("/relatorios", (router) => {
+  router.private.get("/resumo", { roles: ["admin"] }, async (req, res) => {
+    res.json({ ok: true, usuario: req.usuario });
+  });
+  router.public.get("/health", async (_req, res) => res.json({ up: true }));
+});
+```
+
+## Rotas `/core/*` (contrato com o oonCore-front)
+
+```
+GET /core/metadata     GET /core/models      GET /core/models/:name
+GET /core/collections  GET /core/documents   GET /core/pipelines
+GET /core/integrations GET /core/permissions GET /core/actions
+GET /core/menus        GET /core/features
+```
+
+## CLI
+
+```bash
+oonCore-back start        # produção
+oonCore-back dev          # watch/reload
+oonCore-back activate     # seed/ativação (singleton Sistema + hook)
+oonCore-back build:image  # renderiza Dockerfile + docker build
+oonCore-back k8s:render   # renderiza manifests a partir de central.manifest.json
+oonCore-back deploy       # kubectl apply dos manifests
+```
+
+O consumidor não escreve YAML: ajusta `central.manifest.json` e o Core
+renderiza Dockerfile + ConfigMap/Secret/Deployment/Service/Ingress/HPA/Certificate.
+
+## Testes
+
+```bash
+npm test                 # invariantes de segurança (offline)
+MONGO_URI=... npm test   # inclui CRUD + auditoria (requer Mongo)
+```
+
+## Variáveis de ambiente principais
+
+`SERVICE_NAME`, `SERVICE_VERSION`, `PORT`, `NODE_ENV`,
+`DB_SERVER`/`DB_NAME`/`DB_USER`/`DB_PASSWORD`/`DB_AUTH_SOURCE`/`DB_REPLICA_SET`/`DB_TSL`
+(ou `MONGO_URI`), `MEUS_APPS_BACKEND_URL`, `OMIE_APP_KEY`/`OMIE_APP_SECRET`.

package/bin/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const cmd = process.argv[2];
+const cwd = process.cwd();
+
+function loadManifest() {
+  return require("../src/deploy/render").loadManifest(cwd);
+}
+
+function run(bin, args) {
+  const r = spawnSync(bin, args, { stdio: "inherit", cwd });
+  if (r.error) {
+    console.error(`Falha ao executar ${bin}:`, r.error.message);
+    process.exit(1);
+  }
+  process.exit(r.status || 0);
+}
+
+async function main() {
+  switch (cmd) {
+    case "start": {
+      const { start } = require("../src");
+      await start({ cwd });
+      break;
+    }
+
+    case "dev": {
+      // Watch + restart usando o próprio Node (>=18.11 tem --watch).
+      process.env.NODE_ENV = process.env.NODE_ENV || "development";
+      const bootstrap = path.join(__dirname, "dev-runner.js");
+      run(process.execPath, ["--watch", bootstrap]);
+      break;
+    }
+
+    case "activate": {
+      const { activate } = require("../src");
+      await activate({ cwd });
+      process.exit(0);
+      break;
+    }
+
+    case "build:image": {
+      const m = loadManifest();
+      require("../src/deploy/render").renderDockerfile({ cwd });
+      const tag = `${m.IMAGE}:${m.IMAGE_TAG}`;
+      console.log(`Construindo imagem ${tag}...`);
+      run("docker", [
+        "build",
+        "--build-arg",
+        `SERVICE_VERSION=${m.IMAGE_TAG}`,
+        "-t",
+        tag,
+        ".",
+      ]);
+      break;
+    }
+
+    case "k8s:render": {
+      const files = require("../src/deploy/render").renderK8s({ cwd });
+      console.log("Manifests gerados:");
+      files.forEach((f) => console.log(" -", path.relative(cwd, f)));
+      process.exit(0);
+      break;
+    }
+
+    case "deploy": {
+      const files = require("../src/deploy/render").renderK8s({ cwd });
+      console.log("Aplicando manifests no cluster...");
+      run("kubectl", ["apply", ...files.flatMap((f) => ["-f", f])]);
+      break;
+    }
+
+    default:
+      console.log(`oonCore-back <comando>
+
+Comandos:
+  start         Sobe a Central (produção).
+  dev           Sobe com watch/reload.
+  activate      Executa seed/ativação (singleton Sistema + hook).
+  build:image   Renderiza o Dockerfile e roda 'docker build'.
+  k8s:render    Renderiza os manifests k8s a partir de central.manifest.json.
+  deploy        Renderiza e aplica os manifests com 'kubectl apply'.
+`);
+      process.exit(cmd ? 1 : 0);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/bin/dev-runner.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Bootstrap usado por `oonCore-back dev` sob `node --watch`.
+const { start } = require("../src");
+
+start({ cwd: process.cwd() }).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@oondemand/oon-core-back",
+  "version": "0.1.0",
+  "description": "Core runtime para Centrais Oon: Model Registry, CRUD/RBAC automáticos, módulos opinativos (Omie, Assistentes, Multi-moedas, Esteiras, Documentos) e deploy embutido.",
+  "main": "src/index.js",
+  "bin": {
+    "oonCore-back": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "oondemand",
+    "ooncore",
+    "central",
+    "model-registry",
+    "express",
+    "mongoose"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": { "access": "public" },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "axios": "^1.7.7",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.2",
+    "helmet": "^8.0.0",
+    "mongoose": "^8.5.4",
+    "morgan": "^1.10.0"
+  },
+  "peerDependencies": {
+    "xlsx": "^0.18.5"
+  },
+  "peerDependenciesMeta": {
+    "xlsx": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "mongodb-memory-server": "^11.2.0"
+  }
+}

package/src/api/auth.routes.js

@@ -0,0 +1,20 @@
+const express = require("express");
+const auth = require("../core/middlewares/auth");
+const { asyncHandler, sendResponse } = require("../core/utils/helpers");
+
+/**
+ * Rotas de autenticação do Core. O login propriamente dito é delegado ao
+ * provedor configurado (Meus Apps por padrão); aqui validamos o token e
+ * devolvemos o usuário resolvido.
+ */
+const router = express.Router();
+
+router.get(
+  "/validar-token",
+  auth,
+  asyncHandler(async (req, res) => {
+    sendResponse({ res, statusCode: 200, usuario: req.usuario });
+  })
+);
+
+module.exports = router;

package/src/api/core.routes.js

@@ -0,0 +1,75 @@
+const express = require("express");
+const registry = require("../core/registry");
+const ctx = require("../core/context");
+
+/**
+ * Rotas /core/* — contrato de metadata com o oonCore-front (Seção 2.5/21).
+ * Expõem o que o registry conhece, sem domínio hardcoded.
+ */
+const router = express.Router();
+
+function modelSummary(entry) {
+  return {
+    name: entry.name,
+    singular: entry.singular,
+    // basePath em que o CRUD está montado — consumido pelo oonCore-front para
+    // resolver a URL do recurso no modo "dynamic" (default = /<singular>s).
+    basePath: entry.definition.basePath || `/${entry.singular}s`,
+    crud: entry.definition.crud?.enabled !== false,
+    roles: entry.definition.crud?.roles || {},
+    fields: Object.values(entry.metaFields),
+    searchable: entry.searchableFields,
+  };
+}
+
+router.get("/metadata", (_req, res) => {
+  res.json({
+    service: { name: ctx.config.serviceName, version: ctx.config.serviceVersion },
+    models: registry.listModels().map(modelSummary),
+    collections: registry.listCollections(),
+    documents: registry.listDocuments(),
+    pipelines: registry.listPipelines(),
+    integrations: registry.listIntegrations(),
+    features: registry.listFeatures(),
+    menus: registry.listMenus(),
+  });
+});
+
+router.get("/models", (_req, res) => {
+  res.json({ results: registry.listModels().map(modelSummary) });
+});
+
+router.get("/models/:name", (req, res) => {
+  const entry = registry.getModel(req.params.name);
+  if (!entry) return res.status(404).json({ message: "Model não registrada." });
+  res.json(modelSummary(entry));
+});
+
+router.get("/collections", (_req, res) => res.json({ results: registry.listCollections() }));
+router.get("/documents", (_req, res) => res.json({ results: registry.listDocuments() }));
+router.get("/pipelines", (_req, res) => res.json({ results: registry.listPipelines() }));
+router.get("/integrations", (_req, res) => res.json({ results: registry.listIntegrations() }));
+
+router.get("/permissions", (_req, res) => {
+  const permissions = registry.listModels().flatMap((entry) => {
+    const roles = entry.definition.crud?.roles || {};
+    return [
+      { resource: entry.name, action: "read", roles: roles.read || [] },
+      { resource: entry.name, action: "write", roles: roles.write || [] },
+    ];
+  });
+  res.json({ results: permissions });
+});
+
+router.get("/actions", (_req, res) => {
+  const actions = registry.listModels().map((entry) => ({
+    model: entry.name,
+    actions: ["list", "getById", "create", "update", "patch", "delete", "import", "export"],
+  }));
+  res.json({ results: actions });
+});
+
+router.get("/menus", (_req, res) => res.json({ results: registry.listMenus() }));
+router.get("/features", (_req, res) => res.json({ results: registry.listFeatures() }));
+
+module.exports = router;

package/src/api/status.routes.js

@@ -0,0 +1,21 @@
+const express = require("express");
+const mongoose = require("mongoose");
+const ctx = require("../core/context");
+
+const router = express.Router();
+
+router.get("/", (_req, res) => {
+  const states = {
+    0: "Desconectado",
+    1: "Conectado",
+    2: "Conectando",
+    3: "Desconectando",
+  };
+  const dbState = mongoose.connection.readyState;
+  res.status(200).json({
+    message: `${ctx.config.serviceName} rodando - vs ${ctx.config.serviceVersion}`,
+    database: states[dbState] || "Status desconhecido",
+  });
+});
+
+module.exports = router;

package/src/boot/activation.js

@@ -0,0 +1,31 @@
+const ctx = require("../core/context");
+const { connectDB } = require("./database");
+const { loadCentral } = require("./loadCentral");
+const Sistema = require("../core/models/Sistema");
+
+/**
+ * Ativação/seed da Central. Substitui o antigo seedRouter + seeds/.
+ * Garante o singleton Sistema e executa o `activate` declarado em
+ * `central.config.js` (se houver), passando o contexto do Core.
+ */
+async function activate({ cwd = process.cwd() } = {}) {
+  loadCentral(cwd);
+  await connectDB();
+
+  let sistema = await Sistema.findOne();
+  if (!sistema) {
+    sistema = await Sistema.create({ appKey: process.env.APP_KEY });
+    console.log("Sistema (singleton) criado.");
+  }
+
+  const hook = ctx.config.activate;
+  if (typeof hook === "function") {
+    await hook({ Sistema, sistema, registry: require("../core/registry") });
+    console.log("Hook de ativação da Central executado.");
+  }
+
+  console.log("Ativação concluída.");
+  return sistema;
+}
+
+module.exports = { activate };

package/src/boot/createApp.js

@@ -0,0 +1,56 @@
+const express = require("express");
+const cors = require("cors");
+const helmet = require("helmet");
+const morgan = require("morgan");
+
+const ctx = require("../core/context");
+const registry = require("../core/registry");
+const correlationId = require("../core/middlewares/correlationId");
+const requestLog = require("../core/middlewares/requestLog");
+const errorMiddleware = require("../core/middlewares/error");
+const { buildModelRouter } = require("../core/factories/modelRouter");
+
+const coreRoutes = require("../api/core.routes");
+const statusRoutes = require("../api/status.routes");
+const authRoutes = require("../api/auth.routes");
+
+/**
+ * Cria a app Express do Core: middlewares transversais, rotas públicas,
+ * /core/*, routers de CRUD gerados pelo registry e rotas customizadas
+ * (defineRoutes). Tudo derivado do que foi registrado — sem domínio fixo.
+ */
+function createApp() {
+  const app = express();
+
+  app.use(cors(ctx.config.cors));
+  app.use(helmet());
+  app.use(express.json({ limit: "10mb" }));
+  app.use(express.urlencoded({ extended: true, limit: "10mb" }));
+  app.use(correlationId);
+  if (process.env.NODE_ENV === "development") app.use(morgan("dev"));
+
+  // Públicas.
+  app.use("/", statusRoutes);
+  app.use("/auth", authRoutes);
+  app.use("/core", coreRoutes);
+
+  // Log de mutações (após status/core que são GET, antes do domínio).
+  app.use(requestLog);
+
+  // CRUD gerado por model registrada.
+  for (const entry of registry.listModels()) {
+    if (entry.definition.crud?.enabled === false) continue;
+    const basePath = entry.definition.basePath || `/${entry.singular}s`;
+    app.use(basePath, buildModelRouter(entry));
+  }
+
+  // Rotas customizadas (defineRoutes).
+  for (const { basePath, expressRouter } of registry.listRoutes()) {
+    app.use(basePath, expressRouter);
+  }
+
+  app.use(errorMiddleware);
+  return app;
+}
+
+module.exports = { createApp };

package/src/boot/database.js

@@ -0,0 +1,35 @@
+const mongoose = require("mongoose");
+
+/**
+ * Conexão com o MongoDB a partir das envs padrão da Central.
+ * Extraído de `config/db.js`, sem acoplamento ao domínio.
+ */
+function buildMongoUri() {
+  const cfg = {
+    dbServer: process.env.DB_SERVER,
+    dbName: process.env.DB_NAME,
+    dbAuthSource: process.env.DB_AUTH_SOURCE,
+    dbReplicaSet: process.env.DB_REPLICA_SET,
+    dbTsl: process.env.DB_TSL,
+  };
+
+  if (process.env.MONGO_URI) return process.env.MONGO_URI;
+
+  let uri = `${cfg.dbServer}/${cfg.dbName}?`;
+  if (cfg.dbAuthSource) uri += `authSource=${cfg.dbAuthSource}&`;
+  if (cfg.dbTsl) uri += `tls=true&`;
+  if (cfg.dbReplicaSet) uri += `replicaSet=${cfg.dbReplicaSet}`;
+  return uri;
+}
+
+async function connectDB() {
+  const uri = buildMongoUri();
+  await mongoose.connect(uri, {
+    user: process.env.DB_USER,
+    pass: process.env.DB_PASSWORD,
+  });
+  console.log(`Conectado ao MongoDB (${process.env.DB_NAME || uri})`);
+  return mongoose.connection;
+}
+
+module.exports = { connectDB, buildMongoUri };

package/src/boot/loadCentral.js

@@ -0,0 +1,51 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const ctx = require("../core/context");
+
+/**
+ * Descobre e carrega a Central do consumidor:
+ *   1. `central.config.js` na raiz do projeto (mescla na config do Core);
+ *   2. arquivos de domínio em `src/{models,validations,triggers,routes,
+ *      pipelines,documents,integrations,mappings}` (apenas `require`,
+ *      o efeito colateral é registrar via `define*`).
+ */
+const DOMAIN_DIRS = [
+  "models",
+  "validations",
+  "triggers",
+  "routes",
+  "pipelines",
+  "documents",
+  "integrations",
+  "mappings",
+  "hooks",
+];
+
+function loadCentral(cwd = process.cwd()) {
+  const configPath = path.join(cwd, "central.config.js");
+  if (fs.existsSync(configPath)) {
+    const config = require(configPath);
+    ctx.setConfig(typeof config === "function" ? config() : config);
+  }
+
+  const srcDir = path.join(cwd, "src");
+  for (const dir of DOMAIN_DIRS) {
+    const full = path.join(srcDir, dir);
+    if (fs.existsSync(full)) requireDir(full);
+  }
+
+  return ctx.config;
+}
+
+function requireDir(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      requireDir(full);
+    } else if (/\.(js|cjs)$/.test(entry.name)) {
+      require(full);
+    }
+  }
+}
+
+module.exports = { loadCentral, DOMAIN_DIRS };