@ecdt/server-common 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Conjunto de ferramentas e configurações comuns nos servidores da Econodata",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -158,6 +158,99 @@ export declare function publicarEventoDaRequisicao(
   options?: PublicarEventoDaRequisicaoOptions
 ): void;
 
+/**
+ * Avaliação de gatilhos do motor — pura. As cinco leituras chegam em `fonte`, então a mesma função
+ * serve a Function (consultas reais) e o simulador do backoffice (eventos de mentira).
+ */
+export interface FonteDeLeitura {
+  levantouMaoRecentemente(email: string, desde: string): Promise<unknown>;
+  contagemAgrupada(
+    idUsuario: number | null,
+    tipos: string[],
+    campo: string,
+    valor: string,
+    desde: string,
+    ate: string
+  ): Promise<{ total: string | number } | undefined>;
+  contagemDeTipos(
+    idUsuario: number | null,
+    tipos: string[],
+    desde: string,
+    ate: string
+  ): Promise<{ total: string | number } | undefined>;
+  ultimoDisparo(
+    idUsuario: number | null,
+    gatilho: string
+  ): Promise<{ dt_gatilho: Date | string } | undefined>;
+  contagensNaJanela(
+    idUsuario: number | null,
+    desde: string,
+    ate: string
+  ): Promise<{ tipo: string; total: string | number }[]>;
+}
+
+export interface EventoAvaliado {
+  eventoId?: string;
+  tipo: string;
+  idUsuario: number | null;
+  dtEvento: Date;
+  payload: Record<string, unknown>;
+}
+
+export interface ParamsDoTipo {
+  peso?: number;
+  bucket?: number;
+}
+
+export interface GatilhoNoCatalogo {
+  nome: string;
+  disparo: 'imediato' | 'contagem' | 'pontuacao';
+  condicao: Record<string, unknown>;
+  acoes: { acao: string; ref?: string; usa?: Record<string, string>; params?: unknown }[];
+  cooldownH?: number | null;
+}
+
+export interface CatalogoDoMotor<G extends GatilhoNoCatalogo = GatilhoNoCatalogo> {
+  tipos: Record<string, ParamsDoTipo>;
+  acoes: Record<string, { canal: string; ativo: boolean; params: Record<string, unknown> }>;
+  gatilhos: G[];
+  janelaEmDias: number;
+}
+
+export interface PerfilDaConta {
+  temConta: boolean;
+  cargo: string | null;
+  porte: string | null;
+}
+
+export interface ResultadoDaAvaliacao<G extends GatilhoNoCatalogo = GatilhoNoCatalogo> {
+  /** Sem `gatilhoId`: a identidade determinística é do chamador, não da decisão. */
+  disparos: { gatilho: G; contexto: Record<string, unknown> }[];
+  recusas: { gatilho: string; motivo: string }[];
+}
+
+/**
+ * Genérica no tipo do gatilho para devolver ao chamador o MESMO tipo que ele passou. O catálogo de
+ * cada consumidor é mais rico que o mínimo exigido aqui, e um retorno fixo no tipo mínimo obrigaria
+ * a recontruir ou a fazer cast do que já se sabia.
+ */
+export declare function avaliarGatilhos<G extends GatilhoNoCatalogo>(
+  evento: EventoAvaliado,
+  catalogo: CatalogoDoMotor<G>,
+  perfil: PerfilDaConta,
+  emailDaConta: string | null,
+  fonte: FonteDeLeitura
+): Promise<ResultadoDaAvaliacao<G>>;
+
+/** Normaliza o porte às faixas canônicas do cadastro; valor irreconhecível volta vazio. */
+export declare function normalizarPorte(bruto: unknown): string;
+
+export declare function pontuar(
+  contagens: Record<string, number>,
+  tipos: Record<string, ParamsDoTipo>,
+  pesosDoGatilho?: Record<string, number>
+): { total: number; porTipo: Record<string, number> };
+
 export interface IdDoCookieOptions {
   maxLen?: number;
 }

package/src/index.js

@@ -4,6 +4,7 @@ const { expressCors } = require("./services/corsService.js");
 const { setupGracefulShutdown } = require("./services/shutdownService.js");
 const { setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics } = require("./services/redMetricsService.js");
 const { publicarEvento, publicarEventoDaRequisicao } = require("./services/motorEventosService.js");
+const { avaliarGatilhos, pontuar, normalizarPorte } = require("./services/motorAvaliadorService.js");
 const { lerCookie, idDoCookie, sanitizarId } = require("./services/cookieService.js");
 
 function expressCommonMiddlewares({ cookieName } = {}){
@@ -13,4 +14,4 @@ function expressCommonMiddlewares({ cookieName } = {}){
 
 
 
-module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics, publicarEvento, publicarEventoDaRequisicao, lerCookie, idDoCookie, sanitizarId }
+module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, initRedMetrics, redMetricsMiddleware, metricsHandler, renderMetrics, publicarEvento, publicarEventoDaRequisicao, avaliarGatilhos, pontuar, normalizarPorte, lerCookie, idDoCookie, sanitizarId }

package/src/services/motorAvaliadorService.js

@@ -0,0 +1,447 @@
+/**
+ * Avaliação de gatilhos do motor de eventos — PURA.
+ *
+ * Nada aqui toca banco, fila ou variável de ambiente: as cinco leituras que a avaliação precisa
+ * chegam no parâmetro `fonte`. É isso que permite a mesma função decidir em dois lugares — a
+ * `events-engine`, que passa as consultas reais, e o simulador do backoffice, que passa uma
+ * implementação em memória sobre eventos de mentira.
+ *
+ * Mora aqui, e não num pacote novo, porque o lado PRODUTOR do mesmo contrato já mora: o
+ * `motorEventosService.js`, ao lado, é quem publica o evento. Produtor e avaliador do mesmo motor
+ * no mesmo pacote é coerência; um repositório novo para duas dezenas de funções puras, não.
+ */
+
+// ── porte ─────────────────────────────────────────────────────────────────────────────────────
+
+// Faixas canônicas dos formulários de cadastro do site (site-vue3/utils/normalizeQtdFuncionarios.ts).
+const FAIXAS = ["1-4", "5-10", "11-20", "21-50", "51-200", "201-500", "Mais que 500"];
+
+/**
+ * O porte chega do banco em mais de uma grafia: `1-4` convive com o legado `01-04`, e são 60.861
+ * usuários na segunda forma. Comparar a string crua faz o gate de perfil deixar passar exatamente a
+ * coorte que ele existe para barrar.
+ *
+ * Valor irreconhecível volta vazio, e não a primeira faixa: público é filtro, e chutar a faixa
+ * incluiria quem não deveria entrar.
+ */
+const normalizarPorte = (bruto) => {
+  if (!bruto) return "";
+  const texto = String(bruto).trim();
+  if (FAIXAS.includes(texto)) return texto;
+
+  const faixa = /^0*(\d+)\s*-\s*0*(\d+)$/.exec(texto);
+  if (faixa) {
+    const candidato = `${Number(faixa[1])}-${Number(faixa[2])}`;
+    if (FAIXAS.includes(candidato)) return candidato;
+  }
+
+  if (/(mais|acima).*500|500\s*\+|>\s*500/i.test(texto)) return "Mais que 500";
+  return "";
+};
+
+// ── público ───────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Casa o público do gatilho com o perfil da conta e devolve a ESPECIFICIDADE — quantos critérios o
+ * público declara. É ela que decide o A24: quem casa dois gatilhos por pontuação dispara só o mais
+ * específico, e o sem critério é fallback.
+ *
+ * `plano` na v1: todo usuário do site é gratuito (A28/A39). Um público só de `premium` não casa
+ * ninguém, e dizer isso no motivo evita que alguém procure o defeito na pontuação.
+ */
+const casaPublico = (publico, perfil) => {
+  if (!publico || Object.keys(publico).length === 0) {
+    return { casa: true, especificidade: 0, motivo: "sem critério (fallback)" };
+  }
+
+  let especificidade = 0;
+
+  if (publico.com_conta !== undefined) {
+    if (publico.com_conta !== perfil.temConta) {
+      return { casa: false, motivo: `com_conta=${publico.com_conta} não casa` };
+    }
+    especificidade += 1;
+  }
+
+  if (publico.cargo) {
+    if (!perfil.cargo || !publico.cargo.includes(perfil.cargo)) {
+      return { casa: false, motivo: `cargo "${perfil.cargo ?? "vazio"}" fora da lista` };
+    }
+    especificidade += 1;
+  }
+
+  if (publico.porte) {
+    const porte = normalizarPorte(perfil.porte);
+    if (!porte || !publico.porte.map(normalizarPorte).includes(porte)) {
+      return { casa: false, motivo: `porte "${perfil.porte ?? "vazio"}" fora da lista` };
+    }
+    especificidade += 1;
+  }
+
+  if (publico.plano) {
+    if (!publico.plano.includes("gratuito")) {
+      return {
+        casa: false,
+        motivo: "plano premium não casa ninguém na v1: o usuário do site é gratuito",
+      };
+    }
+    especificidade += 1;
+  }
+
+  if (publico.excluir) {
+    if (perfil.cargo && publico.excluir.cargo?.includes(perfil.cargo)) {
+      return { casa: false, motivo: `excluído pelo cargo "${perfil.cargo}"` };
+    }
+    const porte = normalizarPorte(perfil.porte);
+    if (porte && publico.excluir.porte?.map(normalizarPorte).includes(porte)) {
+      return { casa: false, motivo: `excluído pelo porte "${perfil.porte}"` };
+    }
+    especificidade += 1;
+  }
+
+  return { casa: true, especificidade, motivo: `casa ${especificidade} critério(s)` };
+};
+
+// ── horário comercial ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * 9h–17h, segunda a sexta, sem feriado nacional, em `America/Sao_Paulo`.
+ *
+ * É a QUARTA cópia da regra no ecossistema (`site-vue3`, `lps-site` e `ecdt-lead-segmentation`) —
+ * veio do `dev-mkt-functions`, não é uma quinta. Mudar a janela exige mudar as quatro, e não há gate
+ * que cruze os repositórios.
+ *
+ * A janela é a do widget (fim exclusivo às 17h), não a do outbound de WhatsApp do
+ * `ecdt-lead-segmentation`, que é inclusiva até 17h00 de propósito.
+ *
+ * O dia e a hora saem do MESMO `Intl`: ler o dia do relógio do processo e a hora do fuso faz o
+ * feriado cair no dia errado num contêiner em UTC depois das 21h BRT.
+ */
+const FUSO = "America/Sao_Paulo";
+const HORA_INICIO = 9;
+const HORA_FIM = 17;
+const FERIADOS_FIXOS = ["1-1", "4-21", "5-1", "9-7", "10-12", "11-2", "11-15", "11-20", "12-25"];
+
+const partesEmSaoPaulo = (quando) => {
+  const formatador = new Intl.DateTimeFormat("en-US", {
+    timeZone: FUSO,
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    weekday: "short",
+    hour12: false,
+  });
+  const partes = {};
+  for (const parte of formatador.formatToParts(quando)) partes[parte.type] = parte.value;
+
+  return {
+    ano: Number(partes.year),
+    mes: Number(partes.month),
+    dia: Number(partes.day),
+    // `hour12: false` devolve 24 para a meia-noite em algumas versões do ICU.
+    hora: Number(partes.hour) % 24,
+    semana: String(partes.weekday),
+  };
+};
+
+// Meeus/Jones/Butcher.
+const pascoa = (ano) => {
+  const a = ano % 19;
+  const b = Math.floor(ano / 100);
+  const c = ano % 100;
+  const d = Math.floor(b / 4);
+  const e = b % 4;
+  const f = Math.floor((b + 8) / 25);
+  const g = Math.floor((b - f + 1) / 3);
+  const h = (19 * a + b - d - g + 15) % 30;
+  const i = Math.floor(c / 4);
+  const k = c % 4;
+  const l = (32 + 2 * e + 2 * i - h - k) % 7;
+  const m = Math.floor((a + 11 * h + 22 * l) / 451);
+  const mes = Math.floor((h + l - 7 * m + 114) / 31);
+  const dia = ((h + l - 7 * m + 114) % 31) + 1;
+  return new Date(Date.UTC(ano, mes - 1, dia));
+};
+
+const ehFeriadoNacional = (ano, mes, dia) => {
+  if (FERIADOS_FIXOS.includes(`${mes}-${dia}`)) return true;
+
+  const base = pascoa(ano);
+  const deslocado = (dias) => {
+    const data = new Date(base);
+    data.setUTCDate(data.getUTCDate() + dias);
+    return `${data.getUTCMonth() + 1}-${data.getUTCDate()}`;
+  };
+  // Terça de Carnaval, Sexta-feira Santa, Corpus Christi.
+  return [deslocado(-47), deslocado(-2), deslocado(60)].includes(`${mes}-${dia}`);
+};
+
+const horarioComercial = (quando) => {
+  const { ano, mes, dia, hora, semana } = partesEmSaoPaulo(quando);
+  if (semana === "Sat" || semana === "Sun") return { dentro: false, motivo: "fim de semana" };
+  if (ehFeriadoNacional(ano, mes, dia)) return { dentro: false, motivo: "feriado nacional" };
+  if (hora < HORA_INICIO || hora >= HORA_FIM)
+    return { dentro: false, motivo: `${hora}h BRT, fora de 9h-17h` };
+  return { dentro: true };
+};
+
+// ── pontuação ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Pontuação da janela: para cada tipo, `floor(ocorrências / bucket) × peso`.
+ *
+ * O bucket é o que reproduz o widget — 25 pontos a cada 3 listas, não 25 por lista. Peso vem do
+ * catálogo e pode ser sobrescrito pelo gatilho (A25); tipo sem peso conta zero, e é assim que o
+ * `fishing_score` fica gravado sem mexer em pontuação nenhuma.
+ */
+const pontuar = (contagens, tipos, pesosDoGatilho = {}) => {
+  const porTipo = {};
+  let total = 0;
+
+  for (const [tipo, ocorrencias] of Object.entries(contagens)) {
+    const params = tipos[tipo];
+    if (!params) continue;
+
+    const peso = pesosDoGatilho[tipo] ?? params.peso ?? 0;
+    const bucket = params.bucket && params.bucket >= 1 ? params.bucket : 1;
+    const soma = Math.floor(ocorrencias / bucket) * peso;
+    if (soma > 0) {
+      porTipo[tipo] = soma;
+      total += soma;
+    }
+  }
+
+  return { total, porTipo };
+};
+
+/**
+ * Começo da janela de pontuação: a global de N dias, ou o último disparo por pontuação deste gatilho
+ * para esta conta, o que for mais recente. É o que substitui o "score zera ao exibir" do widget por um
+ * marco derivado — sem coluna de estado, e correto mesmo se o evento for reprocessado (P9).
+ */
+const inicioDaJanela = (agora, dias, ultimoDisparo) => {
+  const janela = new Date(agora.getTime() - dias * 86400000);
+  if (ultimoDisparo && ultimoDisparo > janela) return ultimoDisparo;
+  return janela;
+};
+
+// ── avaliador ─────────────────────────────────────────────────────────────────────────────────
+
+const DIA_EM_MS = 86400000;
+
+const duracaoEmMs = (texto) => {
+  const casado = /^([1-9][0-9]*)(h|d)$/.exec(texto ?? "");
+  if (!casado) return null;
+  return Number(casado[1]) * (casado[2] === "h" ? 3600000 : DIA_EM_MS);
+};
+
+const temAcaoInPage = (gatilho, catalogo) =>
+  gatilho.acoes.some((item) => catalogo.acoes[item.acao]?.canal === "in_page");
+
+const tipoConta = (tipo, catalogo) => catalogo.tipos[tipo] !== undefined;
+
+const METODOS_DA_FONTE = [
+  "levantouMaoRecentemente",
+  "contagemAgrupada",
+  "contagemDeTipos",
+  "ultimoDisparo",
+  "contagensNaJanela",
+];
+
+/**
+ * Avalia os gatilhos publicados para a conta do evento.
+ *
+ * A ordem das verificações é por custo: público e horário são memória, e só quem passa por eles chega
+ * a consultar a janela. O gate pós-levantada vem antes da contagem pelo mesmo motivo.
+ *
+ * `fonte` traz as cinco leituras. Num simulador elas respondem sobre eventos de mentira; note que
+ * `ultimoDisparo` e `levantouMaoRecentemente` não têm equivalente numa simulação sem passado, e
+ * devolver vazio ali faz o intervalo entre disparos e o gate pós-levantada NUNCA barrarem — quem
+ * apresenta o resultado precisa dizer isso, senão "não barrou" é lido como "o gate está quebrado".
+ */
+const avaliarGatilhos = async (evento, catalogo, perfil, emailDaConta, fonte) => {
+  const faltando = METODOS_DA_FONTE.filter((m) => typeof fonte?.[m] !== "function");
+  if (faltando.length) {
+    throw new TypeError(`avaliarGatilhos: fonte sem os métodos ${faltando.join(", ")}`);
+  }
+
+  const disparos = [];
+  const recusas = [];
+  const janela = horarioComercial(evento.dtEvento);
+  let levantouMao = null;
+
+  // Candidato: para `imediato` e `contagem`, o tipo do evento tem de estar na condição. Para
+  // `pontuacao`, qualquer evento que pontue pode fechar o limiar.
+  const candidatos = catalogo.gatilhos.filter((g) =>
+    g.disparo === "pontuacao" ? true : (g.condicao.tipos ?? []).includes(evento.tipo),
+  );
+
+  const porPontuacao = [];
+
+  for (const gatilho of candidatos) {
+    const publico = casaPublico(gatilho.condicao.publico, perfil);
+    if (!publico.casa) {
+      recusas.push({ gatilho: gatilho.nome, motivo: publico.motivo });
+      continue;
+    }
+
+    // Gate pós-levantada (D26): quem levantou a mão nos últimos 30 dias não recebe convite de página.
+    if (temAcaoInPage(gatilho, catalogo) && emailDaConta) {
+      if (levantouMao === null) {
+        const desde = new Date(evento.dtEvento.getTime() - 30 * DIA_EM_MS).toISOString();
+        levantouMao = Boolean(await fonte.levantouMaoRecentemente(emailDaConta, desde));
+      }
+      if (levantouMao) {
+        recusas.push({ gatilho: gatilho.nome, motivo: "levantou a mão nos últimos 30 dias" });
+        continue;
+      }
+    }
+
+    // Os três ramos abaixo sempre atribuem os dois; inicializar aqui seria valor morto.
+    let fecha;
+    let detalhe;
+
+    if (gatilho.disparo === "imediato") {
+      fecha = tipoConta(evento.tipo, catalogo);
+      detalhe = { evento: evento.tipo };
+    } else if (gatilho.disparo === "contagem") {
+      const duracao = duracaoEmMs(gatilho.condicao.janela);
+      const quantidade = gatilho.condicao.quantidade ?? Number.POSITIVE_INFINITY;
+      if (duracao === null) {
+        recusas.push({ gatilho: gatilho.nome, motivo: "janela inválida no cadastro" });
+        continue;
+      }
+      const desde = new Date(evento.dtEvento.getTime() - duracao).toISOString();
+      const ate = evento.dtEvento.toISOString();
+      const tipos = gatilho.condicao.tipos ?? [];
+      const campo = gatilho.condicao.agrupar_por?.replace("payload.", "");
+      const valor = campo ? evento.payload[campo] : undefined;
+
+      if (campo && (valor === undefined || valor === null)) {
+        recusas.push({
+          gatilho: gatilho.nome,
+          motivo: `evento sem o campo ${campo} do agrupamento`,
+        });
+        continue;
+      }
+
+      const linha = campo
+        ? await fonte.contagemAgrupada(evento.idUsuario, tipos, campo, String(valor), desde, ate)
+        : await fonte.contagemDeTipos(evento.idUsuario, tipos, desde, ate);
+      const total = Number(linha?.total ?? 0);
+      fecha = total >= quantidade;
+      detalhe = { contagem: total, quantidade, janela: gatilho.condicao.janela };
+      if (campo) detalhe.agrupamento = { [campo]: valor };
+    } else {
+      const ultimo = await fonte.ultimoDisparo(evento.idUsuario, gatilho.nome);
+      const desde = inicioDaJanela(
+        evento.dtEvento,
+        catalogo.janelaEmDias,
+        ultimo?.dt_gatilho ? new Date(ultimo.dt_gatilho) : null,
+      );
+      const contagens = await fonte.contagensNaJanela(
+        evento.idUsuario,
+        desde.toISOString(),
+        evento.dtEvento.toISOString(),
+      );
+      const porTipo = {};
+      for (const linha of contagens) porTipo[linha.tipo] = Number(linha.total);
+
+      const { total, porTipo: decomposicao } = pontuar(
+        porTipo,
+        catalogo.tipos,
+        gatilho.condicao.pesos ?? {},
+      );
+      const limiar = gatilho.condicao.limiar ?? Number.POSITIVE_INFINITY;
+      fecha = total >= limiar;
+      detalhe = {
+        pontuacao: total,
+        limiar,
+        pesos_aplicados: decomposicao,
+        janela_desde: desde.toISOString(),
+      };
+    }
+
+    if (!fecha) {
+      recusas.push({
+        gatilho: gatilho.nome,
+        motivo: `condição não fechou: ${JSON.stringify(detalhe)}`,
+      });
+      continue;
+    }
+
+    // A32: fora do horário o gatilho não dispara, e a pontuação continua contando — o próximo evento
+    // dentro da janela dispara com o acumulado.
+    if (gatilho.condicao.horario_comercial && !janela.dentro) {
+      recusas.push({
+        gatilho: gatilho.nome,
+        motivo: `barrado pelo horário comercial: ${janela.motivo}`,
+      });
+      continue;
+    }
+
+    if (gatilho.cooldownH) {
+      const ultimo = await fonte.ultimoDisparo(evento.idUsuario, gatilho.nome);
+      if (ultimo?.dt_gatilho) {
+        const desdeOUltimo = evento.dtEvento.getTime() - new Date(ultimo.dt_gatilho).getTime();
+        if (desdeOUltimo < gatilho.cooldownH * 3600000) {
+          recusas.push({
+            gatilho: gatilho.nome,
+            motivo: `em intervalo de ${gatilho.cooldownH}h desde o último disparo`,
+          });
+          continue;
+        }
+      }
+    }
+
+    const contexto = {
+      ...detalhe,
+      publico_casado: publico.motivo,
+      especificidade: publico.especificidade,
+    };
+
+    if (gatilho.disparo === "pontuacao") {
+      porPontuacao.push({ gatilho, especificidade: publico.especificidade, contexto });
+    } else {
+      disparos.push({ gatilho, contexto });
+    }
+  }
+
+  // A24: entre os gatilhos por pontuação que fecharam, vence o de público mais específico; empate
+  // resolve por prioridade e, por fim, pelo nome, para ser determinístico.
+  if (porPontuacao.length > 0) {
+    const ordenados = [...porPontuacao].sort(
+      (a, b) =>
+        b.especificidade - a.especificidade ||
+        (b.gatilho.condicao.prioridade ?? 0) - (a.gatilho.condicao.prioridade ?? 0) ||
+        a.gatilho.nome.localeCompare(b.gatilho.nome),
+    );
+    const vencedor = ordenados[0];
+    const preteridos = ordenados.slice(1).map((p) => p.gatilho.nome);
+    for (const p of preteridos) {
+      recusas.push({
+        gatilho: p,
+        motivo: `preterido por ${vencedor.gatilho.nome}, de público mais específico`,
+      });
+    }
+    disparos.push({
+      gatilho: vencedor.gatilho,
+      contexto: {
+        ...vencedor.contexto,
+        ...(preteridos.length ? { gatilhos_preteridos: preteridos } : {}),
+      },
+    });
+  }
+
+  return { disparos, recusas };
+};
+
+module.exports = {
+  avaliarGatilhos,
+  pontuar,
+  inicioDaJanela,
+  casaPublico,
+  normalizarPorte,
+  horarioComercial,
+};

package/test/motorAvaliadorService.test.js

@@ -0,0 +1,222 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+    avaliarGatilhos,
+    pontuar,
+    casaPublico,
+    normalizarPorte,
+    horarioComercial,
+} = require('../src/services/motorAvaliadorService.js');
+
+// Fonte de leitura dublada. Sem os cinco metodos a avaliacao recusa a chamada, entao o dublê
+// declara todos e o teste sobrescreve o que interessa.
+const fonteDe = (respostas = {}) => ({
+    levantouMaoRecentemente: async () => respostas.levantouMao ?? null,
+    contagemAgrupada: async () => respostas.contagem ?? { total: 0 },
+    contagemDeTipos: async () => respostas.contagem ?? { total: 0 },
+    ultimoDisparo: async () => respostas.ultimoDisparo ?? undefined,
+    contagensNaJanela: async () => respostas.contagens ?? [],
+});
+
+const EVENTO = {
+    eventoId: 'e1',
+    tipo: 'desbloqueou_empresa',
+    idUsuario: 1,
+    // Terca-feira, 14h BRT: dentro do horario comercial e fora de feriado.
+    dtEvento: new Date('2026-09-22T17:00:00.000Z'),
+    payload: { setor: 'farmacias' },
+};
+
+const PERFIL = { temConta: true, cargo: null, porte: null };
+
+const catalogoCom = (gatilhos, tipos = { desbloqueou_empresa: { peso: 10 } }) => ({
+    tipos,
+    acoes: { acao_x: { canal: 'n8n', ativo: true, params: {} } },
+    gatilhos,
+    janelaEmDias: 30,
+});
+
+const gatilho = (extra) => ({
+    nome: 'g',
+    disparo: 'imediato',
+    condicao: { tipos: ['desbloqueou_empresa'] },
+    acoes: [{ acao: 'acao_x' }],
+    cooldownH: null,
+    ...extra,
+});
+
+describe('a fonte e contrato, nao sugestao', () => {
+    test('fonte sem um dos cinco metodos e recusada, dizendo qual falta', async () => {
+        const incompleta = { ...fonteDe() };
+        delete incompleta.contagensNaJanela;
+        await assert.rejects(
+            () => avaliarGatilhos(EVENTO, catalogoCom([gatilho()]), PERFIL, null, incompleta),
+            /fonte sem os métodos contagensNaJanela/
+        );
+    });
+
+    test('fonte ausente tambem e recusada, e nao estoura no meio da avaliacao', async () => {
+        await assert.rejects(
+            () => avaliarGatilhos(EVENTO, catalogoCom([gatilho()]), PERFIL, null, undefined),
+            /fonte sem os métodos/
+        );
+    });
+});
+
+describe('catalogo e casos de borda', () => {
+    test('catalogo vazio nao dispara e nao lanca', async () => {
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([]), PERFIL, null, fonteDe());
+        assert.deepEqual(r, { disparos: [], recusas: [] });
+    });
+
+    test('tipo fora do catalogo nao fecha o imediato', async () => {
+        const catalogo = catalogoCom([gatilho()], {});
+        const r = await avaliarGatilhos(EVENTO, catalogo, PERFIL, null, fonteDe());
+        assert.equal(r.disparos.length, 0);
+        assert.match(r.recusas[0].motivo, /condição não fechou/);
+    });
+
+    test('contagem com janela invalida recusa com motivo, sem consultar', async () => {
+        const g = gatilho({ disparo: 'contagem', condicao: { tipos: ['desbloqueou_empresa'], quantidade: 2, janela: 'semana' } });
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([g]), PERFIL, null, fonteDe());
+        assert.equal(r.recusas[0].motivo, 'janela inválida no cadastro');
+    });
+
+    test('agrupamento sem o campo no payload recusa dizendo qual campo', async () => {
+        const g = gatilho({
+            disparo: 'contagem',
+            condicao: { tipos: ['desbloqueou_empresa'], quantidade: 2, janela: '7d', agrupar_por: 'payload.regiao' },
+        });
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([g]), PERFIL, null, fonteDe());
+        assert.equal(r.recusas[0].motivo, 'evento sem o campo regiao do agrupamento');
+    });
+
+    test('pontuacao sem pesos no gatilho cai no peso do catalogo', async () => {
+        const g = gatilho({ disparo: 'pontuacao', condicao: { limiar: 30 } });
+        const fonte = fonteDe({ contagens: [{ tipo: 'desbloqueou_empresa', total: '3' }] });
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([g]), PERFIL, null, fonte);
+        assert.equal(r.disparos.length, 1);
+        assert.equal(r.disparos[0].contexto.pontuacao, 30);
+    });
+});
+
+describe('as tres formas de disparo', () => {
+    test('imediato fecha com o tipo no catalogo', async () => {
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([gatilho()]), PERFIL, null, fonteDe());
+        assert.equal(r.disparos.length, 1);
+        assert.equal(r.disparos[0].contexto.evento, 'desbloqueou_empresa');
+    });
+
+    test('contagem fecha no limite e nao abaixo', async () => {
+        const g = gatilho({ disparo: 'contagem', condicao: { tipos: ['desbloqueou_empresa'], quantidade: 3, janela: '24h' } });
+        const abaixo = await avaliarGatilhos(EVENTO, catalogoCom([g]), PERFIL, null, fonteDe({ contagem: { total: '2' } }));
+        assert.equal(abaixo.disparos.length, 0);
+        const noLimite = await avaliarGatilhos(EVENTO, catalogoCom([g]), PERFIL, null, fonteDe({ contagem: { total: '3' } }));
+        assert.equal(noLimite.disparos.length, 1);
+        assert.equal(noLimite.disparos[0].contexto.contagem, 3);
+    });
+
+    test('o disparo NAO carrega identificador: a identidade e do chamador', async () => {
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([gatilho()]), PERFIL, null, fonteDe());
+        assert.deepEqual(Object.keys(r.disparos[0]).sort(), ['contexto', 'gatilho']);
+    });
+});
+
+describe('gates', () => {
+    test('horario comercial barra fora da janela e a pontuacao segue contando', async () => {
+        const g = gatilho({ condicao: { tipos: ['desbloqueou_empresa'], horario_comercial: true } });
+        const domingo = { ...EVENTO, dtEvento: new Date('2026-09-20T17:00:00.000Z') };
+        const r = await avaliarGatilhos(domingo, catalogoCom([g]), PERFIL, null, fonteDe());
+        assert.match(r.recusas[0].motivo, /horário comercial: fim de semana/);
+    });
+
+    test('intervalo entre disparos barra dentro da janela', async () => {
+        const g = gatilho({ cooldownH: 24 });
+        const fonte = fonteDe({ ultimoDisparo: { dt_gatilho: new Date('2026-09-22T10:00:00.000Z') } });
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([g]), PERFIL, null, fonte);
+        assert.match(r.recusas[0].motivo, /em intervalo de 24h/);
+    });
+
+    test('sem ultimo disparo, o intervalo nao barra — e o caso da simulacao', async () => {
+        const g = gatilho({ cooldownH: 24 });
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([g]), PERFIL, null, fonteDe());
+        assert.equal(r.disparos.length, 1);
+    });
+
+    test('gate pos-levantada so consulta quando ha acao in_page e e-mail', async () => {
+        let consultas = 0;
+        const fonte = { ...fonteDe(), levantouMaoRecentemente: async () => { consultas += 1; return true; } };
+        const catalogo = catalogoCom([gatilho()]);
+        catalogo.acoes.acao_x.canal = 'in_page';
+        const comEmail = await avaliarGatilhos(EVENTO, catalogo, PERFIL, 'a@b.c', fonte);
+        assert.equal(consultas, 1);
+        assert.match(comEmail.recusas[0].motivo, /levantou a mão/);
+        await avaliarGatilhos(EVENTO, catalogo, PERFIL, null, fonte);
+        assert.equal(consultas, 1, 'sem e-mail nao consulta');
+    });
+});
+
+describe('A24 — o mais especifico vence', () => {
+    test('o preterido aparece como preterido, dizendo por quem perdeu', async () => {
+        const geral = gatilho({ nome: 'geral', disparo: 'pontuacao', condicao: { limiar: 10 } });
+        const especifico = gatilho({
+            nome: 'especifico', disparo: 'pontuacao',
+            condicao: { limiar: 10, publico: { com_conta: true } },
+        });
+        const fonte = fonteDe({ contagens: [{ tipo: 'desbloqueou_empresa', total: '3' }] });
+        const r = await avaliarGatilhos(EVENTO, catalogoCom([geral, especifico]), PERFIL, null, fonte);
+        assert.equal(r.disparos.length, 1);
+        assert.equal(r.disparos[0].gatilho.nome, 'especifico');
+        assert.deepEqual(r.disparos[0].contexto.gatilhos_preteridos, ['geral']);
+    });
+
+    test('empate de especificidade desempata por nome, e e deterministico', async () => {
+        const a = gatilho({ nome: 'aaa', disparo: 'pontuacao', condicao: { limiar: 10 } });
+        const b = gatilho({ nome: 'bbb', disparo: 'pontuacao', condicao: { limiar: 10 } });
+        const fonte = fonteDe({ contagens: [{ tipo: 'desbloqueou_empresa', total: '3' }] });
+        for (const ordem of [[a, b], [b, a]]) {
+            const r = await avaliarGatilhos(EVENTO, catalogoCom(ordem), PERFIL, null, fonte);
+            assert.equal(r.disparos[0].gatilho.nome, 'aaa');
+        }
+    });
+});
+
+describe('as funcoes puras que o avaliador usa', () => {
+    test('bucket agrupa antes de pontuar, e o resto e descartado', () => {
+        const tipos = { lista: { peso: 25, bucket: 3 } };
+        assert.equal(pontuar({ lista: 2 }, tipos).total, 0);
+        assert.equal(pontuar({ lista: 3 }, tipos).total, 25);
+        assert.equal(pontuar({ lista: 5 }, tipos).total, 25);
+        assert.equal(pontuar({ lista: 6 }, tipos).total, 50);
+    });
+
+    test('peso do gatilho sobrescreve o do catalogo (A25)', () => {
+        assert.equal(pontuar({ a: 1 }, { a: { peso: 5 } }, { a: 50 }).total, 50);
+    });
+
+    test('porte legado com zero a esquerda casa a faixa canonica', () => {
+        assert.equal(normalizarPorte('01-04'), '1-4');
+        assert.equal(normalizarPorte('acima de 500'), 'Mais que 500');
+        assert.equal(normalizarPorte('sei la'), '', 'irreconhecivel volta vazio, nao a primeira faixa');
+    });
+
+    test('publico sem criterio e fallback com especificidade zero', () => {
+        assert.deepEqual(casaPublico(undefined, PERFIL), {
+            casa: true, especificidade: 0, motivo: 'sem criterio (fallback)'.replace('criterio', 'critério'),
+        });
+    });
+
+    test('plano premium nao casa ninguem na v1, e o motivo diz por que', () => {
+        const r = casaPublico({ plano: ['premium'] }, PERFIL);
+        assert.equal(r.casa, false);
+        assert.match(r.motivo, /usuário do site é gratuito/);
+    });
+
+    test('feriado nacional fecha a janela mesmo em dia util', () => {
+        // 7 de setembro de 2026 e uma segunda-feira.
+        assert.deepEqual(horarioComercial(new Date('2026-09-07T17:00:00.000Z')), {
+            dentro: false, motivo: 'feriado nacional',
+        });
+    });
+});