@kaikybrofc/omnizap-system 2.2.5 → 2.2.7

package/.prettierrc

@@ -0,0 +1,16 @@
+{
+  "printWidth": 12000,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "bracketSameLine": false,
+  "proseWrap": "preserve",
+  "htmlWhitespaceSensitivity": "css",
+  "quoteProps": "as-needed",
+  "embeddedLanguageFormatting": "auto"
+}

package/README.md

@@ -53,26 +53,26 @@ Atualização em cache: **30 minutos** por padrão (`README_SUMMARY_CACHE_SECOND
 <!-- README_SNAPSHOT:START -->
 ### Snapshot do Sistema
 
-> Atualizado em `2026-02-28T04:28:50.529Z` | cache `1800s`
+> Atualizado em `2026-02-28T09:29:12.922Z` | cache `1800s`
 
 | Métrica | Valor |
 | --- | ---: |
 | Usuários (lid_map) | 5.504 |
 | Grupos | 116 |
-| Packs | 294 |
-| Stickers | 6.796 |
-| Mensagens registradas | 440.582 |
+| Packs | 295 |
+| Stickers | 6.811 |
+| Mensagens registradas | 441.124 |
 
 #### Tipos de mensagem mais usados (amostra: 25.000)
 | Tipo | Total |
 | --- | ---: |
-| `texto` | 16.293 |
-| `figurinha` | 4.718 |
-| `reacao` | 1.506 |
-| `imagem` | 1.286 |
-| `outros` | 744 |
-| `video` | 232 |
-| `audio` | 216 |
+| `texto` | 16.180 |
+| `figurinha` | 4.806 |
+| `reacao` | 1.502 |
+| `imagem` | 1.298 |
+| `outros` | 769 |
+| `video` | 227 |
+| `audio` | 213 |
 | `documento` | 5 |
 
 <details><summary>Comandos disponíveis (62)</summary>

package/app/modules/stickerPackModule/autoPackCollectorService.js

@@ -8,6 +8,8 @@ const DEFAULT_AUTO_PACK_NAME = process.env.STICKER_PACK_AUTO_PACK_NAME || 'pack'
 const AUTO_PACK_TARGET_VISIBILITY = 'unlisted';
 const AUTO_COLLECT_ENABLED = process.env.STICKER_PACK_AUTO_COLLECT_ENABLED !== 'false';
 const AUTO_PACK_NAME_MAX_LENGTH = 120;
+const AUTO_PACK_DESCRIPTION_MARKER = '[auto-pack:collector]';
+const AUTO_PACK_DESCRIPTION_TEXT = 'Coleção automática de figurinhas criadas pelo usuário.';
 const normalizeVisibility = (value) => String(value || '').trim().toLowerCase();
 
 /**
@@ -43,6 +45,42 @@ const normalizeAutoPackName = (value, { fallback = 'pack', maxLength = AUTO_PACK
   return normalized || fallback;
 };
 
+const buildAutoPackDescription = () => `${AUTO_PACK_DESCRIPTION_TEXT} ${AUTO_PACK_DESCRIPTION_MARKER}`.trim();
+
+const isThemeCurationAutoPack = (pack) => {
+  if (!pack || typeof pack !== 'object') return false;
+  const description = String(pack.description || '').toLowerCase();
+  if (description.includes('[auto-theme:') || description.includes('[auto-tag:')) return true;
+  if (String(pack.name || '').trim().toLowerCase().startsWith('[auto]')) return true;
+  return Boolean(String(pack.pack_theme_key || '').trim());
+};
+
+const isAutoCollectorPack = (pack) => {
+  if (!pack || typeof pack !== 'object') return false;
+  if (isThemeCurationAutoPack(pack)) return false;
+
+  const description = String(pack.description || '').toLowerCase();
+  if (description.includes(AUTO_PACK_DESCRIPTION_MARKER)) return true;
+  if (description.includes('coleção automática de figurinhas criadas pelo usuário.')) return true;
+
+  const normalizedName = normalizeAutoPackName(pack.name, { fallback: '', maxLength: AUTO_PACK_NAME_MAX_LENGTH });
+  if (!normalizedName) return false;
+
+  const base = normalizeAutoPackName(DEFAULT_AUTO_PACK_NAME, { fallback: 'pack', maxLength: AUTO_PACK_NAME_MAX_LENGTH });
+  const matcher = new RegExp(`^${escapeRegex(base.toLowerCase())}\\d+$`, 'i');
+  const looksLikeLegacyCollector = matcher.test(normalizedName);
+  if (looksLikeLegacyCollector) return true;
+
+  return pack.is_auto_pack === true || Number(pack.is_auto_pack || 0) === 1;
+};
+
+const isUserManagedPackCandidate = (pack) => {
+  if (!pack || typeof pack !== 'object') return false;
+  if (isThemeCurationAutoPack(pack)) return false;
+  if (isAutoCollectorPack(pack)) return false;
+  return Number(pack.is_auto_pack || 0) !== 1;
+};
+
 /**
  * Monta candidato incremental para nome de pack automático.
  *
@@ -177,21 +215,37 @@ export function createAutoPackCollector(options = {}) {
   const ensureTargetPack = async ({ ownerJid, senderName }) => {
     const packs = await deps.stickerPackService.listPacks({ ownerJid, limit: 30 });
     if (packs.length > 0) {
+      // Prioriza pack gerenciado pelo usuário (pack atual/manual).
+      const userManagedPacks = packs.filter((entry) => isUserManagedPackCandidate(entry));
+      if (userManagedPacks.length > 0) {
+        return {
+          pack: userManagedPacks[0],
+          packs,
+        };
+      }
+
+      const managedAutoPacks = packs.filter((entry) => isAutoCollectorPack(entry));
       const preferredPack =
-        packs.find((entry) => normalizeVisibility(entry?.visibility) === AUTO_PACK_TARGET_VISIBILITY) || packs[0];
-      const ensuredPack = await ensureAutoPackVisibility({ ownerJid, pack: preferredPack });
-      return {
-        pack: ensuredPack,
-        packs,
-      };
+        managedAutoPacks.find((entry) => normalizeVisibility(entry?.visibility) === AUTO_PACK_TARGET_VISIBILITY)
+        || managedAutoPacks[0]
+        || null;
+
+      if (preferredPack) {
+        const ensuredPack = await ensureAutoPackVisibility({ ownerJid, pack: preferredPack });
+        return {
+          pack: ensuredPack,
+          packs,
+        };
+      }
     }
 
     const created = await deps.stickerPackService.createPack({
       ownerJid,
       name: makeAutoPackName([]),
       publisher: sanitizeText(senderName, 120, { allowEmpty: true }) || 'OmniZap',
-      description: 'Coleção automática de figurinhas criadas pelo usuário.',
+      description: buildAutoPackDescription(),
       visibility: AUTO_PACK_TARGET_VISIBILITY,
+      isAutoPack: true,
     });
 
     return {
@@ -250,8 +304,9 @@ export function createAutoPackCollector(options = {}) {
           ownerJid,
           name: makeAutoPackName(packs),
           publisher: sanitizeText(senderName, 120, { allowEmpty: true }) || targetPack.publisher || 'OmniZap',
-          description: 'Coleção automática de figurinhas criadas pelo usuário.',
+          description: buildAutoPackDescription(),
           visibility: AUTO_PACK_TARGET_VISIBILITY,
+          isAutoPack: true,
         });
 
         const updated = await deps.stickerPackService.addStickerToPack({

package/app/observability/metrics.js

@@ -1,10 +1,6 @@
 import 'dotenv/config';
 
-import http from 'node:http';
-import { randomUUID } from 'node:crypto';
-import { URL } from 'node:url';
 import client from 'prom-client';
-import logger from '../utils/logger/loggerModule.js';
 
 const parseEnvBool = (value, fallback) => {
   if (value === undefined || value === null || value === '') return fallback;
@@ -39,23 +35,12 @@ const QUERY_THRESHOLDS_MS = parseThresholds(process.env.DB_QUERY_ALERT_THRESHOLD
 
 const registry = new client.Registry();
 let metrics = null;
-let server = null;
-let serverStarted = false;
-let stickerCatalogModulePromise = null;
 
 const normalizeLabel = (value, fallback = 'unknown') => {
   if (value === undefined || value === null || value === '') return fallback;
   return String(value);
 };
 
-const normalizeRequestId = (value) => {
-  const token = String(value || '')
-    .trim()
-    .replace(/[^a-zA-Z0-9._:-]/g, '')
-    .slice(0, 120);
-  return token || randomUUID();
-};
-
 const normalizeHttpMethod = (method) => {
   const normalized = String(method || '').trim().toUpperCase();
   if (!normalized) return 'UNKNOWN';
@@ -70,7 +55,7 @@ const toStatusClass = (statusCode) => {
   return `${head}xx`;
 };
 
-const resolveRouteGroup = ({ pathname, metricsPath, catalogConfig = null } = {}) => {
+export const resolveRouteGroup = ({ pathname, metricsPath, catalogConfig = null } = {}) => {
   if (pathname?.startsWith(metricsPath)) return 'metrics';
   if (pathname === '/sitemap.xml') return 'sitemap';
   if (pathname === '/api/marketplace/stats') return 'marketplace_stats';
@@ -390,137 +375,23 @@ const ensureMetrics = () => {
   return metrics;
 };
 
-const loadStickerCatalogModule = async () => {
-  if (!stickerCatalogModulePromise) {
-    stickerCatalogModulePromise = import('../modules/stickerPackModule/stickerPackCatalogHttp.js');
-  }
-  return stickerCatalogModulePromise;
-};
-
 export const isMetricsEnabled = () => METRICS_ENABLED;
 
-export const startMetricsServer = () => {
-  if (!METRICS_ENABLED || serverStarted) return;
-  ensureMetrics();
-  server = http.createServer(async (req, res) => {
-    const requestStartedAt = Date.now();
-    const requestId = normalizeRequestId(req.headers['x-request-id']);
-    res.setHeader('X-Request-Id', requestId);
-
-    const host = req.headers.host || `${METRICS_HOST}:${METRICS_PORT}`;
-    let parsedUrl;
-    try {
-      parsedUrl = new URL(req.url || '/', `http://${host}`);
-    } catch {
-      parsedUrl = new URL(req.url || '/', 'http://localhost');
-    }
-    const pathname = parsedUrl.pathname;
-    let routeGroup = resolveRouteGroup({
-      pathname,
-      metricsPath: METRICS_PATH,
-      catalogConfig: null,
-    });
-
-    res.once('finish', () => {
-      recordHttpRequest({
-        durationMs: Date.now() - requestStartedAt,
-        method: req.method,
-        statusCode: res.statusCode,
-        routeGroup,
-      });
-    });
-
-    try {
-      const stickerCatalogModule = await loadStickerCatalogModule();
-      const catalogConfig =
-        typeof stickerCatalogModule.getStickerCatalogConfig === 'function'
-          ? stickerCatalogModule.getStickerCatalogConfig()
-          : null;
-      routeGroup = resolveRouteGroup({
-        pathname,
-        metricsPath: METRICS_PATH,
-        catalogConfig,
-      });
-      const handledByCatalog = await stickerCatalogModule.maybeHandleStickerCatalogRequest(req, res, {
-        pathname,
-        url: parsedUrl,
-      });
+export const getMetricsServerConfig = () => ({
+  enabled: METRICS_ENABLED,
+  host: METRICS_HOST,
+  port: METRICS_PORT,
+  path: METRICS_PATH,
+});
 
-      if (handledByCatalog) {
-        return;
-      }
-    } catch (error) {
-      logger.error('Erro ao inicializar rotas web de sticker packs.', {
-        error: error.message,
-      });
-    }
-
-    if (!pathname.startsWith(METRICS_PATH)) {
-      res.statusCode = 404;
-      res.end('Not Found');
-      return;
-    }
-
-    try {
-      const body = await registry.metrics();
-      res.statusCode = 200;
-      res.setHeader('Content-Type', registry.contentType);
-      res.end(body);
-    } catch (error) {
-      res.statusCode = 500;
-      res.end('Metrics error');
-      logger.error('Erro ao gerar /metrics', { error: error.message });
-    }
-  });
-
-  server.listen(METRICS_PORT, METRICS_HOST, () => {
-    serverStarted = true;
-    logger.info('Servidor /metrics iniciado', {
-      host: METRICS_HOST,
-      port: METRICS_PORT,
-      path: METRICS_PATH,
-    });
-
-    loadStickerCatalogModule()
-      .then((module) => {
-        const config = typeof module.getStickerCatalogConfig === 'function' ? module.getStickerCatalogConfig() : null;
-        if (!config?.enabled) return;
-        logger.info('Catalogo web de sticker packs habilitado', {
-          web_path: config.webPath,
-          api_base_path: config.apiBasePath,
-          orphan_api_path: config.orphanApiPath,
-          data_public_path: config.dataPublicPath,
-          data_public_dir: config.dataPublicDir,
-          host: METRICS_HOST,
-          port: METRICS_PORT,
-        });
-      })
-      .catch((error) => {
-        logger.warn('Nao foi possivel carregar configuracao do catalogo de sticker packs.', {
-          error: error.message,
-        });
-      });
-  });
-
-  server.on('error', (error) => {
-    logger.error('Falha ao iniciar servidor /metrics', { error: error.message });
-  });
-};
-
-export const stopMetricsServer = async () => {
-  if (!serverStarted || !server) return;
-  const current = server;
-  server = null;
-  serverStarted = false;
-  await new Promise((resolve, reject) => {
-    current.close((error) => {
-      if (error) {
-        reject(error);
-        return;
-      }
-      resolve();
-    });
-  });
+export const getMetricsPayload = async () => {
+  if (!METRICS_ENABLED) return null;
+  ensureMetrics();
+  const body = await registry.metrics();
+  return {
+    body,
+    contentType: registry.contentType,
+  };
 };
 
 export const recordError = (scope = 'app') => {

package/index.js

@@ -3,7 +3,7 @@
  *
  * Responsabilidades principais:
  * - Inicializar o banco (garantindo DB e tabelas).
- * - Subir servidor de métricas.
+ * - Subir servidor HTTP (catálogo web + endpoint de métricas).
  * - Rodar backfill do lid_map (opcional, em background).
  * - Conectar ao WhatsApp (Baileys).
  * - Iniciar serviços auxiliares (ex: broadcast de notícias).
@@ -25,7 +25,7 @@ import {
   stopNewsBroadcastService,
 } from './app/services/newsBroadcastService.js';
 import initializeDatabase from './database/init.js';
-import { startMetricsServer, stopMetricsServer } from './app/observability/metrics.js';
+import { startHttpServer, stopHttpServer } from './server/index.js';
 import {
   startStickerClassificationBackground,
   stopStickerClassificationBackground,
@@ -198,7 +198,7 @@ async function closeDatabasePool() {
  *
  * Fluxo de startup:
  * 1) Inicializa DB (cria/verifica DB/tabelas)
- * 2) Sobe servidor de métricas
+ * 2) Sobe servidor HTTP (catálogo + métricas)
  * 3) Inicia backfill (opcional) em background
  * 4) Conecta no WhatsApp
  * 5) Inicia serviços auxiliares (news broadcast)
@@ -216,8 +216,8 @@ async function startApp() {
     await withTimeout(initializeDatabase(), DB_INIT_TIMEOUT_MS, 'Inicializacao do banco');
     logger.info('Banco de dados pronto.');
 
-    logger.info('Inicializando servidor de metricas...');
-    startMetricsServer();
+    logger.info('Inicializando servidor HTTP...');
+    startHttpServer();
     if (isStickerWorkerPipelineEnabled()) {
       startStickerWorkerPipeline();
     } else {
@@ -274,7 +274,7 @@ startApp();
  * - serviço de notícias (se stop existir)
  * - aguarda backfill (com timeout curto)
  * - encerra socket do WhatsApp
- * - encerra servidor de métricas
+ * - encerra servidor HTTP
  * - encerra pool do MySQL
  *
  * Regras:
@@ -339,14 +339,14 @@ async function shutdown(signal, error) {
       }
     }
 
-    // 4) Encerrar servidor de métricas
-    if (typeof stopMetricsServer === 'function') {
+    // 4) Encerrar servidor HTTP
+    if (typeof stopHttpServer === 'function') {
       try {
-        logger.info('Encerrando servidor de metricas...');
-        await withTimeout(stopMetricsServer(), 8000, 'Encerramento metricas');
-        logger.info('Servidor de metricas encerrado.');
-      } catch (metricsError) {
-        logger.warn('Falha ao encerrar servidor de metricas.', { error: metricsError.message });
+        logger.info('Encerrando servidor HTTP...');
+        await withTimeout(stopHttpServer(), 8000, 'Encerramento HTTP');
+        logger.info('Servidor HTTP encerrado.');
+      } catch (httpError) {
+        logger.warn('Falha ao encerrar servidor HTTP.', { error: httpError.message });
       }
     }
 

package/observability/sticker-catalog-slo.md

@@ -0,0 +1,83 @@
+# Sticker Catalog 10x Baseline e SLOs
+
+Este documento define a baseline operacional da camada HTTP + pipeline de classificação para o módulo de stickers.
+
+## 1. Metas SLO (fase inicial)
+
+### HTTP catálogo (`/api/sticker-packs*`, `/stickers*`, `/api/marketplace/stats`)
+
+- **Latência p95**: `<= 750ms`
+- **Latência p99**: `<= 1500ms`
+- **Taxa de erro (5xx + timeout)**: `<= 2%` por janela de 5 minutos
+- **Throughput alvo**: escalar linearmente com workers/processos sem aumento abrupto do p95
+
+### Classificação de stickers
+
+- **Duração média do ciclo**: `<= 10s`
+- **Throughput mínimo (assets classificados/min)**: `>= 300` (ajustar por hardware)
+- **Backlog de fila (`sticker_reprocess_pending`)**: tendência de queda após picos; alerta se cresce por mais de 15 min
+
+## 2. Métricas instrumentadas
+
+### HTTP
+
+- `omnizap_http_requests_total{route_group,method,status_class}`
+- `omnizap_http_request_duration_ms{route_group,method,status_class}`
+- `omnizap_http_slo_violation_total{route_group,method}`
+
+`route_group` segmenta tráfego em:
+
+- `catalog_api_public`
+- `catalog_api_auth`
+- `catalog_api_admin`
+- `catalog_api_upload`
+- `catalog_web`
+- `catalog_data_asset`
+- `catalog_user_profile`
+- `marketplace_stats`
+- `metrics`
+- `other`
+
+### Classificação
+
+- `omnizap_sticker_classification_cycle_duration_ms{status}`
+- `omnizap_sticker_classification_cycle_total{status}`
+- `omnizap_sticker_classification_assets_total{outcome}`
+- `omnizap_queue_depth{queue}`
+
+## 3. Tracing mínimo
+
+- Cada request HTTP agora recebe/propaga `X-Request-Id`.
+- Se o cliente enviar `X-Request-Id`, o valor é reaproveitado.
+- Sem header, o servidor gera UUID.
+
+## 4. Baseline de carga (script local)
+
+Script: `scripts/sticker-catalog-loadtest.mjs`
+
+Exemplo:
+
+```bash
+node scripts/sticker-catalog-loadtest.mjs \
+  --base-url http://127.0.0.1:9102 \
+  --duration-seconds 60 \
+  --concurrency 40 \
+  --paths "/api/sticker-packs?limit=24&sort=popular,/api/sticker-packs/stats,/api/sticker-packs/creators?limit=25" \
+  --out /tmp/sticker-loadtest-report.json
+```
+
+Interpretação rápida:
+
+- `latency_ms.p95 <= 750` = SLO de latência cumprido
+- `error_rate <= 0.02` = estabilidade aceitável
+- `throughput_rps` = referência para comparar antes/depois de otimizações
+
+## 5. Gate de rollout sugerido
+
+1. Capturar baseline com carga atual.
+2. Aplicar mudança de arquitetura/índice/cache.
+3. Reexecutar carga com mesmos parâmetros.
+4. Aprovar rollout apenas se:
+   - p95 não piorar mais de 10%
+   - erro não subir acima de 2%
+   - backlog voltar ao patamar normal em até 15 min

package/observability/sticker-scale-hardening-rollout.md

@@ -0,0 +1,128 @@
+# Sticker 10x Hardening And Rollout
+
+## Scope
+
+This runbook covers phases 4-8 of the sticker-pack scale plan:
+
+1. ranking snapshot read path
+2. internal outbox/event consumer
+3. dedicated workers (classification/curation/rebuild)
+4. object storage delivery with secure URLs
+5. canary rollout, rollback, and final tuning
+
+## Feature Flags
+
+Flags are stored in `feature_flag`:
+
+- `enable_ranking_snapshot_read`
+- `enable_domain_event_outbox`
+- `enable_worker_dedicated_processes`
+- `enable_object_storage_delivery`
+
+### Query Current Status
+
+```sql
+SELECT flag_name, is_enabled, rollout_percent, updated_at
+FROM feature_flag
+WHERE flag_name IN (
+  'enable_ranking_snapshot_read',
+  'enable_domain_event_outbox',
+  'enable_worker_dedicated_processes',
+  'enable_object_storage_delivery'
+)
+ORDER BY flag_name;
+```
+
+### Update Rollout Percent
+
+```sql
+UPDATE feature_flag
+SET is_enabled = 1, rollout_percent = 25, updated_by = 'ops'
+WHERE flag_name = 'enable_worker_dedicated_processes';
+```
+
+### Emergency Disable
+
+```sql
+UPDATE feature_flag
+SET is_enabled = 0, rollout_percent = 0, updated_by = 'ops'
+WHERE flag_name IN (
+  'enable_worker_dedicated_processes',
+  'enable_object_storage_delivery',
+  'enable_domain_event_outbox'
+);
+```
+
+## Canary Sequence
+
+1. `enable_ranking_snapshot_read`: 10% -> 50% -> 100%
+2. `enable_domain_event_outbox`: 10% -> 50% -> 100%
+3. start dedicated worker processes and set `enable_worker_dedicated_processes`: 10% -> 50% -> 100%
+4. `enable_object_storage_delivery`: 5% -> 25% -> 100%
+
+Promotion gate for each step:
+
+- HTTP p95 within target
+- queue backlog stable (`pending`, `failed`)
+- outbox DLQ not growing unexpectedly
+- no sustained error-rate increase
+
+## Dedicated Workers
+
+Run workers as isolated processes:
+
+```bash
+npm run worker:sticker:classification
+npm run worker:sticker:curation
+npm run worker:sticker:rebuild
+```
+
+PM2 production profile includes these workers in `ecosystem.prod.config.cjs`.
+
+## 10x Validation
+
+### HTTP Stress
+
+```bash
+npm run loadtest:stickers -- --base-url http://127.0.0.1:9102 --duration-seconds 120 --concurrency 200 --slo-ms 750
+```
+
+### Queue/Worker Validation
+
+Monitor:
+
+- `sticker_worker_tasks_pending`
+- `sticker_worker_tasks_processing`
+- `sticker_worker_tasks_failed`
+- `domain_event_outbox_pending`
+- `domain_event_outbox_failed`
+
+Acceptance:
+
+- failed queues remain near zero (transient spikes allowed)
+- pending queues recover after load burst
+- no monotonic growth in DLQ tables
+
+## Rollback Plan
+
+1. Disable `enable_object_storage_delivery`.
+2. Disable `enable_worker_dedicated_processes` (inline poller resumes).
+3. Disable `enable_domain_event_outbox` if event flow is unstable.
+4. Keep `enable_ranking_snapshot_read` enabled only if snapshot freshness is healthy.
+
+Data safety notes:
+
+- tasks/events are persisted in SQL queues
+- failed terminal tasks/events are preserved in DLQ tables
+- local disk read path remains fallback for sticker asset serving
+
+## Post-Rollout Tuning
+
+Tune these env vars after baseline:
+
+- `STICKER_WORKER_CLASSIFICATION_CADENCE_MS`
+- `STICKER_WORKER_CURATION_CADENCE_MS`
+- `STICKER_WORKER_REBUILD_CADENCE_MS`
+- `STICKER_DEDICATED_WORKER_POLL_INTERVAL_MS`
+- `STICKER_SCORE_SNAPSHOT_REFRESH_INTERVAL_MS`
+- `STICKER_OBJECT_STORAGE_SIGNED_URL_TTL_SECONDS`