@oondemand/oon-core-back 0.1.0

package/src/boot/startServer.js

@@ -0,0 +1,31 @@
+const ctx = require("../core/context");
+const { connectDB } = require("./database");
+const { createApp } = require("./createApp");
+const { loadCentral } = require("./loadCentral");
+
+/**
+ * Sobe a aplicação completa: carrega a Central do consumidor, conecta no
+ * banco, monta a app e escuta a porta. É o `start` da API pública e o
+ * alvo do `oonCore-back start`.
+ *
+ * @param {{ cwd?: string, listen?: boolean }} opts
+ */
+async function start({ cwd = process.cwd(), listen = true } = {}) {
+  loadCentral(cwd);
+  await connectDB();
+  const app = createApp();
+
+  if (!listen) return { app };
+
+  const port = ctx.config.port;
+  return new Promise((resolve) => {
+    const server = app.listen(port, () => {
+      console.log("****************************************************************");
+      console.log(`${ctx.config.serviceName} rodando na porta ${port} e conectado ao MongoDB`);
+      console.log("****************************************************************");
+      resolve({ app, server });
+    });
+  });
+}
+
+module.exports = { start };

package/src/core/context.js

@@ -0,0 +1,35 @@
+/**
+ * Estado de runtime do Core. Singleton de processo: guarda a config da
+ * Central resolvida no boot e dá acesso aos registries para as factories,
+ * rotas /core/* e CLI.
+ */
+const defaults = {
+  serviceName: process.env.SERVICE_NAME || "central-oon",
+  serviceVersion: process.env.SERVICE_VERSION || "0.0.0",
+  port: Number(process.env.PORT) || 4000,
+  // Função de verificação de token. Recebe (token, { sistema }) e deve
+  // resolver com o objeto `usuario` ({ tipo, nome, email }) ou lançar.
+  // Default: delega ao Meus Apps (comportamento histórico do CST).
+  auth: { verifyToken: null },
+  cors: { origin: "*" },
+};
+
+let config = { ...defaults };
+
+module.exports = {
+  get config() {
+    return config;
+  },
+  setConfig(partial = {}) {
+    config = {
+      ...config,
+      ...partial,
+      auth: { ...config.auth, ...(partial.auth || {}) },
+      cors: { ...config.cors, ...(partial.cors || {}) },
+    };
+    return config;
+  },
+  reset() {
+    config = { ...defaults };
+  },
+};

package/src/core/define.js

@@ -0,0 +1,171 @@
+const mongoose = require("mongoose");
+const express = require("express");
+const registry = require("./registry");
+const ctx = require("./context");
+const { asyncHandler } = require("./utils/helpers");
+const auth = require("./middlewares/auth");
+const { rbac } = require("./middlewares/rbac");
+const { mutationAudit } = require("./middlewares/mutationAudit");
+
+/**
+ * Constrói o schema Mongoose a partir dos descriptors de `fields`,
+ * separando o bloco `__meta` (consumido apenas por /core/metadata).
+ */
+function buildSchema(schemaDef, options = {}) {
+  const mongooseShape = {};
+  const metaFields = {};
+  const searchableFields = [];
+
+  for (const [key, descriptor] of Object.entries(schemaDef)) {
+    if (descriptor && typeof descriptor === "object" && descriptor.__meta) {
+      const { __meta, ...mongooseDef } = descriptor;
+      mongooseShape[key] = mongooseDef;
+      metaFields[key] = { name: key, ...__meta };
+      if (__meta.kind === "string" && __meta.searchable) searchableFields.push(key);
+    } else {
+      // Descriptor cru (compatível com Mongoose puro).
+      mongooseShape[key] = descriptor;
+      metaFields[key] = { name: key, kind: "raw" };
+    }
+  }
+
+  const schema = new mongoose.Schema(mongooseShape, {
+    timestamps: true,
+    ...options,
+  });
+
+  return { schema, metaFields, searchableFields };
+}
+
+/**
+ * defineModel — registra a model e gera derivações automáticas
+ * (schema, CRUD, RBAC, paginação, validação, auditoria, metadata).
+ */
+function defineModel(definition) {
+  if (!definition?.name) throw new Error("defineModel requer `name`.");
+  if (!definition?.schema) throw new Error(`defineModel("${definition.name}") requer \`schema\`.`);
+
+  const { schema, metaFields, searchableFields } = buildSchema(
+    definition.schema,
+    definition.options
+  );
+
+  // Hooks de domínio (defineTrigger) ligados ao ciclo do documento.
+  schema.pre("save", async function (next) {
+    try {
+      const { before } = registry.getTriggers(definition.name);
+      for (const fn of before) await fn(this, { op: this.isNew ? "create" : "update" });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });
+  schema.post("save", async function (doc) {
+    const { after } = registry.getTriggers(definition.name);
+    for (const fn of after) await fn(doc, { op: "save" });
+  });
+
+  const mongooseModel =
+    mongoose.models[definition.name] || mongoose.model(definition.name, schema);
+
+  const entry = registry.registerModel({
+    name: definition.name,
+    singular: (definition.singular || definition.name).toLowerCase(),
+    mongooseModel,
+    definition,
+    metaFields,
+    searchableFields,
+  });
+
+  // Permissões/actions derivadas para o front.
+  if (definition.crud?.enabled !== false) {
+    registry.registerFeature(definition.name, {
+      model: definition.name,
+      crud: true,
+      roles: definition.crud?.roles || {},
+    });
+  }
+
+  return entry;
+}
+
+/**
+ * defineCentral — declara metadados da Central (módulos ativos + paths de
+ * domínio). Mescla na config de runtime.
+ */
+function defineCentral(config = {}) {
+  ctx.setConfig(config);
+  return ctx.config;
+}
+
+function defineValidation(modelName, fn) {
+  registry.registerValidation(modelName, fn);
+}
+
+function defineTrigger(modelName, hooks) {
+  registry.registerTrigger(modelName, hooks);
+}
+
+function defineCollection(name, config) {
+  return registry.registerCollection(name, { name, ...config });
+}
+
+function defineDocument(name, config) {
+  return registry.registerDocument(name, { name, ...config });
+}
+
+function definePipeline(name, config) {
+  return registry.registerPipeline(name, { name, ...config });
+}
+
+function defineOmieMapping(name, config) {
+  return registry.registerOmieMapping(name, { name, ...config });
+}
+
+/**
+ * defineRoutes — rotas customizadas com o contrato de segurança do Core.
+ * Entrega `router.private.*` (auth + RBAC + mutationAudit) e
+ * `router.public.*`. NUNCA expõe `express.Router()` cru.
+ */
+function defineRoutes(basePath, builder) {
+  const expressRouter = express.Router();
+
+  const wrapPrivate = (method) => (path, opts = {}, handler) => {
+    if (typeof opts === "function") {
+      handler = opts;
+      opts = {};
+    }
+    const chain = [auth, rbac(opts.roles || [])];
+    if (["post", "put", "patch", "delete"].includes(method) && opts.audit) {
+      chain.push(mutationAudit(opts.audit));
+    }
+    expressRouter[method](path, ...chain, asyncHandler(handler));
+  };
+
+  const wrapPublic = (method) => (path, handler) => {
+    expressRouter[method](path, asyncHandler(handler));
+  };
+
+  const methods = ["get", "post", "put", "patch", "delete"];
+  const router = { private: {}, public: {} };
+  for (const m of methods) {
+    router.private[m] = wrapPrivate(m);
+    router.public[m] = wrapPublic(m);
+  }
+
+  builder(router);
+  registry.registerRoutes({ basePath, expressRouter });
+  return expressRouter;
+}
+
+module.exports = {
+  defineModel,
+  defineCentral,
+  defineValidation,
+  defineTrigger,
+  defineCollection,
+  defineDocument,
+  definePipeline,
+  defineOmieMapping,
+  defineRoutes,
+};

package/src/core/errors/GenericError.js

@@ -0,0 +1,14 @@
+/**
+ * Erro de domínio reconhecido pelo error middleware do Core.
+ * Permite que services/triggers sinalizem statusCode e detalhes.
+ */
+class GenericError extends Error {
+  constructor(message, { statusCode = 400, details = null } = {}) {
+    super(message);
+    this.name = "GenericError";
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+}
+
+module.exports = GenericError;

package/src/core/factories/crudController.js

@@ -0,0 +1,66 @@
+const Helpers = require("../utils/helpers");
+const registry = require("../registry");
+
+/**
+ * Controllers HTTP de CRUD ligados a um service. Aplica validação
+ * declarada via `defineValidation` antes de create/update.
+ */
+function createCrudController(entry, service) {
+  const runValidation = async (data, op) => {
+    const validate = registry.getValidation(entry.name);
+    if (validate) await validate(data, { op });
+  };
+
+  return {
+    async list(req, res) {
+      const { pageIndex, pageSize, searchTerm, sort, ...filtros } = req.query;
+      const { results, pagination } = await service.listPaginated({
+        pageIndex,
+        pageSize,
+        searchTerm,
+        sort,
+        filtros,
+      });
+      Helpers.sendPaginatedResponse({ res, statusCode: 200, results, pagination });
+    },
+
+    async getById(req, res) {
+      const registro = await service.getById(req.params.id);
+      Helpers.sendResponse({ res, statusCode: 200, [entry.singular]: registro });
+    },
+
+    async create(req, res) {
+      await runValidation(req.body, "create");
+      const registro = await service.create(req.body);
+      Helpers.sendResponse({ res, statusCode: 201, [entry.singular]: registro });
+    },
+
+    async update(req, res) {
+      await runValidation(req.body, "update");
+      const registro = await service.update(req.params.id, req.body);
+      Helpers.sendResponse({ res, statusCode: 200, [entry.singular]: registro });
+    },
+
+    async patch(req, res) {
+      const registro = await service.update(req.params.id, req.body);
+      Helpers.sendResponse({ res, statusCode: 200, [entry.singular]: registro });
+    },
+
+    async remove(req, res) {
+      const registro = await service.remove(req.params.id);
+      Helpers.sendResponse({ res, statusCode: 200, [entry.singular]: registro });
+    },
+
+    async importMany(req, res) {
+      const result = await service.importMany(req.body?.rows || req.body);
+      Helpers.sendResponse({ res, statusCode: 201, ...result });
+    },
+
+    async exportAll(req, res) {
+      const results = await service.exportAll(req.query);
+      Helpers.sendResponse({ res, statusCode: 200, results });
+    },
+  };
+}
+
+module.exports = { createCrudController };

package/src/core/factories/crudService.js

@@ -0,0 +1,96 @@
+const GenericError = require("../errors/GenericError");
+
+/**
+ * Gera um service de CRUD genérico para uma model registrada.
+ * Cobre paginação, filtros, busca textual, ordenação, import e export.
+ */
+function createCrudService(entry) {
+  const { mongooseModel: Model, searchableFields } = entry;
+
+  async function listPaginated({ pageIndex = 0, pageSize = 20, searchTerm, sort, filtros = {} } = {}) {
+    const page = Math.max(0, Number(pageIndex) || 0);
+    const limit = Math.min(200, Math.max(1, Number(pageSize) || 20));
+
+    const query = { ...cleanFilters(filtros) };
+    if (searchTerm && searchableFields.length) {
+      const rx = new RegExp(escapeRegex(searchTerm), "i");
+      query.$or = searchableFields.map((f) => ({ [f]: rx }));
+    }
+
+    const sortSpec = parseSort(sort);
+    const [results, totalItems] = await Promise.all([
+      Model.find(query).sort(sortSpec).skip(page * limit).limit(limit).lean(),
+      Model.countDocuments(query),
+    ]);
+
+    return {
+      results,
+      pagination: {
+        currentPage: page,
+        itemsPerPage: limit,
+        totalItems,
+        totalPages: Math.ceil(totalItems / limit) || 1,
+      },
+    };
+  }
+
+  async function getById(id) {
+    const doc = await Model.findById(id);
+    if (!doc) throw new GenericError("Registro não encontrado.", { statusCode: 404 });
+    return doc;
+  }
+
+  async function create(data) {
+    return Model.create(data);
+  }
+
+  async function update(id, data) {
+    const doc = await Model.findByIdAndUpdate(id, data, {
+      new: true,
+      runValidators: true,
+    });
+    if (!doc) throw new GenericError("Registro não encontrado.", { statusCode: 404 });
+    return doc;
+  }
+
+  async function remove(id) {
+    const doc = await Model.findByIdAndDelete(id);
+    if (!doc) throw new GenericError("Registro não encontrado.", { statusCode: 404 });
+    return doc;
+  }
+
+  async function importMany(rows = []) {
+    if (!Array.isArray(rows)) {
+      throw new GenericError("Esperado um array de registros.", { statusCode: 400 });
+    }
+    const docs = await Model.insertMany(rows, { ordered: false });
+    return { inserted: docs.length };
+  }
+
+  async function exportAll(filtros = {}) {
+    return Model.find(cleanFilters(filtros)).lean();
+  }
+
+  return { listPaginated, getById, create, update, remove, importMany, exportAll };
+}
+
+function cleanFilters(filtros) {
+  const out = {};
+  for (const [k, v] of Object.entries(filtros || {})) {
+    if (v !== undefined && v !== "" && v !== null) out[k] = v;
+  }
+  return out;
+}
+
+function parseSort(sort) {
+  if (!sort) return { createdAt: -1 };
+  // "campo:asc" | "campo:desc" | "campo"
+  const [field, dir] = String(sort).split(":");
+  return { [field]: dir === "asc" ? 1 : -1 };
+}
+
+function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+module.exports = { createCrudService };

package/src/core/factories/modelRouter.js

@@ -0,0 +1,67 @@
+const express = require("express");
+const { asyncHandler } = require("../utils/helpers");
+const auth = require("../middlewares/auth");
+const { rbac } = require("../middlewares/rbac");
+const { mutationAudit } = require("../middlewares/mutationAudit");
+const { createCrudService } = require("./crudService");
+const { createCrudController } = require("./crudController");
+
+/**
+ * Monta o router de CRUD de uma model. Todas as rotas são privadas
+ * (auth obrigatório). Mutações passam por RBAC + mutationAudit.
+ *
+ * Endpoints (Seção 2.9): GET list, GET :id, POST, PUT :id, PATCH :id,
+ * DELETE :id, POST /import, GET /export.
+ */
+function buildModelRouter(entry) {
+  const router = express.Router();
+  const service = createCrudService(entry);
+  const controller = createCrudController(entry, service);
+
+  const crud = entry.definition.crud || {};
+  const roles = crud.roles || {};
+  const readRoles = roles.read || [];
+  const writeRoles = roles.write || [];
+  const entidade = entry.name;
+
+  router.use(auth);
+
+  router.get("/", rbac(readRoles), asyncHandler(controller.list));
+  router.get("/export", rbac(readRoles), asyncHandler(controller.exportAll));
+  router.get("/:id", rbac(readRoles), asyncHandler(controller.getById));
+
+  router.post(
+    "/import",
+    rbac(writeRoles),
+    mutationAudit({ entidade, acao: "adicionado" }),
+    asyncHandler(controller.importMany)
+  );
+  router.post(
+    "/",
+    rbac(writeRoles),
+    mutationAudit({ entidade, acao: "adicionado" }),
+    asyncHandler(controller.create)
+  );
+  router.put(
+    "/:id",
+    rbac(writeRoles),
+    mutationAudit({ entidade, acao: "alterado" }),
+    asyncHandler(controller.update)
+  );
+  router.patch(
+    "/:id",
+    rbac(writeRoles),
+    mutationAudit({ entidade, acao: "alterado" }),
+    asyncHandler(controller.patch)
+  );
+  router.delete(
+    "/:id",
+    rbac(writeRoles),
+    mutationAudit({ entidade, acao: "excluido" }),
+    asyncHandler(controller.remove)
+  );
+
+  return router;
+}
+
+module.exports = { buildModelRouter };

package/src/core/fields.js

@@ -0,0 +1,92 @@
+/**
+ * `fields` — tipos prontos para declarar schemas em `defineModel` (Seção 2.4).
+ *
+ * Cada helper retorna um descriptor `{ ...mongoose, __meta }`. O bloco
+ * `__meta` é consumido pelo registry para gerar metadata/OpenAPI para o
+ * front, sem vazar para o schema Mongoose final.
+ */
+const mongoose = require("mongoose");
+
+const withMeta = (mongooseDef, meta) => ({ ...mongooseDef, __meta: meta });
+
+const string = (opts = {}) =>
+  withMeta(
+    { type: String, required: !!opts.required, default: opts.default, trim: true },
+    { kind: "string", label: opts.label, searchable: opts.searchable !== false }
+  );
+
+const number = (opts = {}) =>
+  withMeta(
+    { type: Number, required: !!opts.required, default: opts.default },
+    { kind: "number", label: opts.label }
+  );
+
+const boolean = (opts = {}) =>
+  withMeta(
+    { type: Boolean, required: !!opts.required, default: opts.default ?? false },
+    { kind: "boolean", label: opts.label }
+  );
+
+const date = (opts = {}) =>
+  withMeta(
+    { type: Date, required: !!opts.required, default: opts.default },
+    { kind: "date", label: opts.label }
+  );
+
+const ref = (modelName, opts = {}) =>
+  withMeta(
+    {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: modelName,
+      required: !!opts.required,
+    },
+    { kind: "ref", ref: modelName, label: opts.label }
+  );
+
+const enumField = (values, opts = {}) =>
+  withMeta(
+    {
+      type: String,
+      enum: values,
+      required: !!opts.required,
+      default: opts.default,
+    },
+    { kind: "enum", options: values, label: opts.label }
+  );
+
+const currency = (opts = {}) =>
+  withMeta(
+    { type: Number, required: !!opts.required, default: opts.default ?? 0, min: 0 },
+    { kind: "currency", label: opts.label }
+  );
+
+const currencyCode = (opts = {}) =>
+  withMeta(
+    {
+      type: String,
+      uppercase: true,
+      minlength: 3,
+      maxlength: 3,
+      default: opts.default || "BRL",
+      required: !!opts.required,
+    },
+    { kind: "currencyCode", label: opts.label }
+  );
+
+const currencyConverted = (opts = {}) =>
+  withMeta(
+    { type: Number, default: opts.default ?? 0, min: 0 },
+    { kind: "currencyConverted", base: opts.base || "BRL", label: opts.label }
+  );
+
+module.exports = {
+  string,
+  number,
+  boolean,
+  date,
+  ref,
+  enum: enumField,
+  currency,
+  currencyCode,
+  currencyConverted,
+};

package/src/core/middlewares/auth.js

@@ -0,0 +1,65 @@
+const axios = require("axios");
+const Sistema = require("../models/Sistema");
+const Helpers = require("../utils/helpers");
+const ctx = require("../context");
+
+/**
+ * Verificador padrão: delega ao Meus Apps (comportamento histórico do CST).
+ * Pode ser sobrescrito via `central.config.js -> auth.verifyToken`.
+ */
+async function defaultVerifyToken(token) {
+  const sistema = await Sistema.findOne().catch(() => null);
+  const baseUrl = process.env.MEUS_APPS_BACKEND_URL;
+  if (!baseUrl) {
+    const err = new Error("MEUS_APPS_BACKEND_URL não configurada.");
+    err.statusCode = 401;
+    throw err;
+  }
+
+  const response = await axios.get(
+    `${baseUrl}/auth/autenticar-aplicativo/`,
+    { headers: { Authorization: `Bearer ${token}`, origin: sistema?.appKey } }
+  );
+
+  const data = response.data.usuario;
+  return {
+    tipo:
+      data.aplicativo.tipoAcesso === "master" ? "admin" : data.aplicativo.tipoAcesso,
+    nome: data.nome,
+    email: data.email,
+  };
+}
+
+/**
+ * Middleware de autenticação. Sem token => 401 (invariante de segurança).
+ * Resolve `req.usuario` e segue.
+ */
+const authMiddleware = async (req, res, next) => {
+  const token = req.headers.authorization?.split(" ")[1];
+
+  if (!token) {
+    return Helpers.sendErrorResponse({
+      res,
+      message: "Acesso não autorizado. Token ausente.",
+      statusCode: 401,
+    });
+  }
+
+  const verify = ctx.config.auth?.verifyToken || defaultVerifyToken;
+
+  try {
+    const usuario = await verify(token, { req });
+    if (!usuario) throw new Error("Usuário não resolvido.");
+    req.usuario = usuario;
+    next();
+  } catch (error) {
+    return Helpers.sendErrorResponse({
+      res,
+      message: "Token inválido ou erro na autenticação.",
+      statusCode: error.statusCode || 401,
+    });
+  }
+};
+
+module.exports = authMiddleware;
+module.exports.defaultVerifyToken = defaultVerifyToken;

package/src/core/middlewares/correlationId.js

@@ -0,0 +1,12 @@
+const crypto = require("node:crypto");
+
+/**
+ * Garante um correlationId por requisição (header `x-correlation-id` ou
+ * gerado). Exposto em `req.correlationId` e ecoado na resposta.
+ */
+module.exports = function correlationId(req, res, next) {
+  const id = req.headers["x-correlation-id"] || crypto.randomUUID();
+  req.correlationId = id;
+  res.setHeader("x-correlation-id", id);
+  next();
+};

package/src/core/middlewares/error.js

@@ -0,0 +1,46 @@
+const helpers = require("../utils/helpers");
+const GenericError = require("../errors/GenericError");
+
+/**
+ * Error handler central. Trata GenericError (domínio), erros de validação
+ * do Mongoose e cai num 500 genérico para o resto.
+ */
+const errorMiddleware = (error, _req, res, next) => {
+  if (!error) return next();
+
+  if (error instanceof GenericError) {
+    return helpers.sendErrorResponse({
+      res,
+      statusCode: error.statusCode,
+      error: error.details,
+      message: error.message,
+    });
+  }
+
+  if (error.name === "ValidationError") {
+    return helpers.sendErrorResponse({
+      res,
+      statusCode: 422,
+      error: Object.values(error.errors || {}).map((e) => e.message),
+      message: "Erro de validação.",
+    });
+  }
+
+  if (error.name === "CastError") {
+    return helpers.sendErrorResponse({
+      res,
+      statusCode: 400,
+      message: "Identificador inválido.",
+    });
+  }
+
+  console.log("🆘 [UNHANDLED ERROR]:", error?.message || error);
+  return helpers.sendErrorResponse({
+    res,
+    statusCode: 500,
+    error: error.message,
+    message: "Houve um erro inesperado!",
+  });
+};
+
+module.exports = errorMiddleware;