Merge pull request #8 from RubensGJ/dev

😍Merge: Refatoração do módulo de cotações, novas rotas analíticas e ajustes de documentação/logs

Author: RubensGJ

openapi.yaml

@@ -6,7 +6,7 @@
   "scripts": {
     "start": "node src/app.js",
     "dev": "node --watch src/app.js",
-    "postinstall": "npx puppeteer browsers install chrome",
+    "postinstall": "node scripts/installChrome.js",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [

package.json

@@ -0,0 +1,59 @@
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const puppeteer = require("puppeteer");
+
+// Escreve mensagens simples do postinstall no console.
+function log(message) {
+  console.log(`[POSTINSTALL] ${message}`);
+}
+
+// Descobre o caminho do CLI interno do Puppeteer usado na instalacao do Chrome.
+function getPuppeteerCliPath() {
+  const packageJsonPath = require.resolve("puppeteer/package.json");
+  return path.join(path.dirname(packageJsonPath), "lib", "cjs", "puppeteer", "node", "cli.js");
+}
+
+// Remove o cache quebrado quando a pasta existe, mas o executavel nao.
+function removeBrokenBrowserFolder(executablePath) {
+  const browserFolder = path.dirname(path.dirname(executablePath));
+
+  if (!fs.existsSync(browserFolder)) {
+    return;
+  }
+
+  log(`Cache incompleto detectado em ${browserFolder}. Removendo pasta corrompida.`);
+  fs.rmSync(browserFolder, { recursive: true, force: true });
+}
+
+// Executa o comando oficial do Puppeteer para instalar o Chrome.
+function installChrome() {
+  const cliPath = getPuppeteerCliPath();
+  const result = spawnSync(process.execPath, [cliPath, "browsers", "install", "chrome"], {
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+// Evita reinstalar o Chrome quando ele ja esta pronto e corrige cache quebrado.
+function main() {
+  const executablePath = puppeteer.executablePath();
+
+  if (fs.existsSync(executablePath)) {
+    log("Chrome do Puppeteer ja esta disponivel.");
+    return;
+  }
+
+  removeBrokenBrowserFolder(executablePath);
+  log("Instalando Chrome do Puppeteer.");
+  installChrome();
+}
+
+main();

scripts/installChrome.js

@@ -18,10 +18,12 @@ const OPENAPI_FILE = path.resolve(__dirname, "..", "openapi.yaml");
 const openApiDocument = YAML.load(OPENAPI_FILE);
 const logger = criarLogger("API");
 
+// Habilita middlewares globais usados por toda a aplicacao.
 app.use(cors());
 app.use(express.json());
 app.use(requestLogger);
 
+// Rota simples para monitoramento e health check.
 app.get("/health", (req, res) => {
   res.status(200).json({
     status: "ok",
@@ -30,6 +32,7 @@ app.get("/health", (req, res) => {
   });
 });
 
+// Rota inicial para indicar rapidamente se a API esta online.
 app.get("/", (req, res) => {
   res.status(200).json({
     status: "ok",
@@ -39,15 +42,22 @@ app.get("/", (req, res) => {
   });
 });
 
+// Entrega o arquivo OpenAPI bruto para quem quiser baixar ou integrar.
 app.get("/openapi.yaml", (req, res) => {
   res.sendFile(OPENAPI_FILE);
 });
+
+// Publica a documentacao Swagger da API.
 app.use("/docs", swaggerUi.serve, swaggerUi.setup(openApiDocument));
 
+// Registra as rotas protegidas de cotacoes.
 app.use("/api/cotacoes", authenticateToken, cotacoesRoutes);
+
+// Trata rotas inexistentes e erros da API.
 app.use(notFoundHandler);
 app.use(errorHandler);
 
+// Inicializa os recursos obrigatorios antes de a API aceitar requisicoes.
 async function bootstrap() {
   logger.info("Iniciando aplicacao.");
   validateAuthConfig();
@@ -56,6 +66,7 @@ async function bootstrap() {
   logger.sucesso("Aplicacao pronta para receber requisicoes.");
 }
 
+// Sobe o servidor HTTP e inicia o scheduler de coletas automaticas.
 async function startServer() {
   await bootstrap();
 
@@ -67,6 +78,7 @@ async function startServer() {
   startCotacaoScheduler();
 }
 
+// Encerra o processo se a aplicacao falhar ainda na subida.
 startServer().catch((error) => {
   logger.erro("Falha ao iniciar aplicacao.", error);
   process.exit(1);

src/app.js

@@ -1,6 +1,7 @@
 const { query } = require("./db");
 const { getNowInBrasiliaISO } = require("../utils/dateTime");
 
+// Converte o JSON salvo no banco para um array padrao usado pelos services.
 function parsePayload(payloadJson) {
   if (Array.isArray(payloadJson)) {
     return payloadJson;
@@ -18,6 +19,7 @@ function parsePayload(payloadJson) {
   }
 }
 
+// Mapeia uma linha do banco para o formato de snapshot usado na aplicacao.
 function mapSnapshotRow(row) {
   if (!row) return null;
 
@@ -34,6 +36,7 @@ function mapSnapshotRow(row) {
   };
 }
 
+// Salva um novo snapshot no historico e atualiza a tabela com a ultima coleta.
 async function saveSnapshot({
   source,
   payload,
@@ -85,6 +88,7 @@ async function saveSnapshot({
   };
 }
 
+// Busca o snapshot mais recente de uma fonte especifica.
 async function getLatestSnapshot(source) {
   const result = await query(
     `
@@ -99,6 +103,7 @@ async function getLatestSnapshot(source) {
   return mapSnapshotRow(row);
 }
 
+// Lista snapshots mais recentes, com ou sem filtro por fonte.
 async function listSnapshots({ source = null, limit = 50 }) {
   const parsedLimit = Number(limit);
   const safeLimit = Number.isFinite(parsedLimit) ? Math.min(Math.max(parsedLimit, 1), 500) : 50;
@@ -127,8 +132,48 @@ async function listSnapshots({ source = null, limit = 50 }) {
   return result.rows.map(mapSnapshotRow);
 }
 
+// Lista snapshots dentro de um periodo para montar consultas historicas.
+async function listSnapshotsByPeriod({ source = null, startDate = null, endDate = null, limit = 500 }) {
+  const parsedLimit = Number(limit);
+  const safeLimit = Number.isFinite(parsedLimit) ? Math.min(Math.max(parsedLimit, 1), 2000) : 500;
+  const values = [];
+  const conditions = [];
+
+  if (source) {
+    values.push(source);
+    conditions.push(`fonte = $${values.length}`);
+  }
+
+  if (startDate) {
+    values.push(startDate);
+    conditions.push(`coletado_em >= $${values.length}`);
+  }
+
+  if (endDate) {
+    values.push(endDate);
+    conditions.push(`coletado_em <= $${values.length}`);
+  }
+
+  values.push(safeLimit);
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const result = await query(
+    `
+      SELECT id, fonte, dados_json, quantidade_itens, coletado_em, janela_horario, tipo_disparo, criado_em
+      FROM cotacoes_historico
+      ${whereClause}
+      ORDER BY coletado_em ASC, id ASC
+      LIMIT $${values.length}
+    `,
+    values
+  );
+
+  return result.rows.map(mapSnapshotRow);
+}
+
 module.exports = {
   getLatestSnapshot,
   listSnapshots,
+  listSnapshotsByPeriod,
   saveSnapshot,
 };

src/database/cotacoesRepository.js

@@ -4,6 +4,7 @@ const { criarLogger } = require("../logs/logger");
 let pool = null;
 const logger = criarLogger("BANCO");
 
+// Converte variaveis de ambiente textuais para booleano.
 function parseBoolean(value, defaultValue = true) {
   if (value === undefined || value === null || value === "") {
     return defaultValue;
@@ -13,6 +14,7 @@ function parseBoolean(value, defaultValue = true) {
   return ["1", "true", "yes", "y", "on"].includes(normalized);
 }
 
+// Decide se a conexao com o banco deve usar SSL.
 function shouldUseSsl(connectionString) {
   const explicit = process.env.DATABASE_SSL;
   if (explicit !== undefined) {
@@ -22,6 +24,7 @@ function shouldUseSsl(connectionString) {
   return connectionString.includes("neon.tech");
 }
 
+// Cria o pool do Postgres uma unica vez e reaproveita nas proximas consultas.
 function getPool() {
   if (pool) {
     return pool;
@@ -42,10 +45,12 @@ function getPool() {
   return pool;
 }
 
+// Executa uma query simples usando o pool compartilhado da aplicacao.
 async function query(text, params = []) {
   return getPool().query(text, params);
 }
 
+// Garante que as tabelas e indices usados pela API existam no banco.
 async function initDatabase() {
   logger.info("Garantindo estrutura do banco.");
 

src/database/db.js

@@ -1,5 +1,6 @@
 const { query } = require("./db");
 
+// Salva no banco apenas os dados principais da requisicao HTTP concluida.
 async function saveRequestLog({ metodo, rota, statusCode, duracaoMs }) {
   await query(
     `

src/database/requestLogsRepository.js

@@ -1,3 +1,4 @@
+// Representa erros esperados da aplicacao com status HTTP e detalhes opcionais.
 class AppError extends Error {
   constructor(message, statusCode = 500, details = null) {
     super(message);

src/errors/AppError.js

@@ -4,7 +4,7 @@ const { criarLogger } = require("../logs/logger");
 
 const logger = criarLogger("SCHEDULER");
 
-//helper
+// Converte variaveis do .env para booleano no scheduler.
 function parseBoolean(value, defaultValue) {
   if (value === undefined || value === null || value === "") {
     return defaultValue;
@@ -14,21 +14,21 @@ function parseBoolean(value, defaultValue) {
   return ["1", "true", "yes", "y", "on"].includes(normalized);
 }
 
-//pega o tempo agendado do env
+// Le as expressoes cron configuradas para os horarios de coleta automatica.
 function getCronExpressions() {
   const first = (process.env.SCHEDULER_CRON_1 || "0 12 * * *").trim();
   const second = (process.env.SCHEDULER_CRON_2 || "0 15 * * *").trim();
   return [first, second];
 }
 
-//
+// Define o nome exibido no historico para cada horario agendado.
 function getSlotLabel(index, expression) {
   if (index === 0) return "12:00";
   if (index === 1) return "15:00";
   return expression;
 }
 
-//
+// Registra os jobs cron que atualizam as cotacoes automaticamente.
 function startCotacaoScheduler() {
   const enabled = parseBoolean(process.env.SCHEDULER_ENABLED, true);
   if (!enabled) {

src/jobs/cotacaoScheduler.js

@@ -1,7 +1,9 @@
+// Gera o timestamp padrao usado em todas as mensagens de log.
 function getTimestamp() {
   return new Date().toISOString();
 }
 
+// Extrai uma mensagem legivel quando o log recebe um erro.
 function getMensagemErro(error) {
   if (!error) {
     return "";
@@ -18,6 +20,7 @@ function getMensagemErro(error) {
   return String(error);
 }
 
+// Escreve uma linha de log com formato padronizado no console.
 function escrever(nivel, contexto, mensagem, error = null) {
   const linha = `[${getTimestamp()}] [${nivel}] [${contexto}] ${mensagem}`;
   const detalheErro = getMensagemErro(error);
@@ -35,6 +38,7 @@ function escrever(nivel, contexto, mensagem, error = null) {
   }
 }
 
+// Cria um objeto de log com o contexto informado para reutilizar no projeto.
 function criarLogger(contexto) {
   return {
     info(mensagem) {