@ecdt/server-common 1.7.0 → 2.0.0

package/README.md

@@ -158,89 +158,6 @@ export default defineEventHandler(async (event) => {
 
 ---
 
-### `publicarEvento(options)`
-
-Envia um evento para o coletor de eventos configurado, sem bloquear o fluxo que o gerou.
-
-```js
-const { publicarEvento } = require('@ecdt/server-common');
-
-publicarEvento({
-  tipo: 'meu_evento',
-  autorizacao: req.headers.authorization,
-  payload: { campo: 'valor' },
-});
-```
-
-| Opção | Default | Descrição |
-|---|---|---|
-| `tipo` | — | Nome do evento, em `snake_case` |
-| `autorizacao` | — | Header `Authorization` da requisição que originou o evento |
-| `idVisitante` | — | Identificador anônimo, para quando não há token |
-| `payload` | `{}` | Campos do evento |
-| `url` | `process.env.MOTOR_EVENTOS_URL` | URL completa do coletor; a função não monta caminho nenhum |
-| `timeoutMs` | `2000` | Aborta a requisição |
-| `aoFalhar` | `console.error` | Recebe a mensagem quando a publicação não acontece |
-
-A identidade do usuário sai do token, nunca do corpo: o coletor a resolve a partir do `Authorization`
-repassado. Quando não há token — rota pública, visitante anônimo — vale o `idVisitante`, que vai no
-corpo como `id_visitante`. Ele não é identidade autenticada, é um identificador de correlação: forjá-lo
-não atribui nada à conta de ninguém, e por isso pode vir do corpo da requisição. Basta um dos dois.
-
-Sem `tipo`, ou sem nenhum dos dois identificadores, a função não faz nada; sem `url` ela ainda registra
-um `console.warn`, porque url ausente é configuração faltando e não um evento que não se aplica.
-
-**A função nunca lança e nunca devolve promise.** O evento é secundário ao fluxo que o gerou —
-falha de publicação não pode virar erro de quem chamou, e o retorno `undefined` impede que alguém
-consiga dar `await` e acoplar a latência do request ao motor.
-
----
-
-### `publicarEventoDaRequisicao(req, options)`
-
-O mesmo publish, montado a partir da requisição que gerou o evento. Resolve o token pelo header
-`Authorization` e o identificador anônimo pelo corpo (`id_visitante`) ou pelo cookie, nessa ordem.
-
-```js
-const { publicarEventoDaRequisicao } = require('@ecdt/server-common');
-
-publicarEventoDaRequisicao(req, {
-  tipo: 'meu_evento',
-  payload: { campo: 'valor' },
-});
-```
-
-| Opção | Default | Descrição |
-|---|---|---|
-| `tipo`, `payload`, `url`, `timeoutMs`, `aoFalhar` | — | Idênticos ao `publicarEvento` |
-| `cookieVisitante` | `process.env.MOTOR_EVENTOS_COOKIE_VISITANTE` | Nome do cookie que guarda o identificador anônimo |
-
-Sem `cookieVisitante` configurado, só o corpo alimenta o `id_visitante`. Também não lança em
-nenhuma hipótese, inclusive com `req` sem `headers` nem `body`.
-
----
-
-### `lerCookie`, `idDoCookie` e `sanitizarId`
-
-Leitura do header `Cookie` no servidor, sem dependência de framework.
-
-```js
-const { idDoCookie } = require('@ecdt/server-common');
-
-const idVisitante = idDoCookie(req.headers.cookie, 'nome_do_cookie');
-```
-
-| Função | Devolve |
-|---|---|
-| `lerCookie(cabecalho, nome)` | Valor cru do cookie, ou `null` |
-| `idDoCookie(cabecalho, nome, { maxLen })` | O identificador: aceita o cookie como string simples ou como JSON com campo `id`, decodifica o valor e corta em `maxLen` (100 por padrão) |
-| `sanitizarId(valor, maxLen)` | O mesmo corte e validação, para identificador que veio de outro lugar |
-
-O match do nome é exato, então `nome_antigo` não casa com `nome`. Nenhuma das três lança: entrada
-que não é string vira `null`.
-
----
-
 ## Instalação
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.7.0",
+  "version": "2.0.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

@@ -136,38 +136,95 @@ export declare function renderMetrics(
   registry?: MetricsRegistry
 ): Promise<{ contentType: string; body: string }>;
 
-export interface PublicarEventoOptions {
-  tipo: string;
-  autorizacao?: string;
-  idVisitante?: string;
-  payload?: Record<string, unknown>;
-  url?: string;
-  timeoutMs?: number;
-  aoFalhar?: (mensagem: string) => 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 declare function publicarEvento(options?: PublicarEventoOptions): void;
+export interface EventoAvaliado {
+  eventoId?: string;
+  tipo: string;
+  idUsuario: number | null;
+  dtEvento: Date;
+  payload: Record<string, unknown>;
+}
 
-export interface PublicarEventoDaRequisicaoOptions
-  extends Omit<PublicarEventoOptions, 'autorizacao' | 'idVisitante'> {
-  cookieVisitante?: string;
+export interface ParamsDoTipo {
+  peso?: number;
+  bucket?: number;
 }
 
-export declare function publicarEventoDaRequisicao(
-  req: unknown,
-  options?: PublicarEventoDaRequisicaoOptions
-): void;
+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 IdDoCookieOptions {
-  maxLen?: number;
+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 declare function lerCookie(cabecalho: unknown, nome: string): string | null;
+export interface PerfilDaConta {
+  temConta: boolean;
+  cargo: string | null;
+  porte: string | null;
+}
 
-export declare function idDoCookie(
-  cabecalho: unknown,
-  nome: string,
-  options?: IdDoCookieOptions
-): 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 }[];
+}
 
-export declare function sanitizarId(valor: unknown, maxLen?: number): string | null;
+/**
+ * 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> };

package/src/index.js

@@ -3,8 +3,7 @@ const { devMktTokenSanitaze } = require("./services/tokenService.js");
 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 { lerCookie, idDoCookie, sanitizarId } = require("./services/cookieService.js");
+const { avaliarGatilhos, pontuar, normalizarPorte } = require("./services/motorAvaliadorService.js");
 
 function expressCommonMiddlewares({ cookieName } = {}){
     return [bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}), devMktTokenSanitaze({ cookieName })];
@@ -13,4 +12,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, avaliarGatilhos, pontuar, normalizarPorte }

package/src/services/motorAvaliadorService.js

@@ -0,0 +1,443 @@
+/**
+ * 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.
+ */
+
+// ── 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,
+};