@omnizap-system/omnizap 2.6.0 → 2.6.2

package/app/modules/userModule/userCommand.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import { executeQuery, TABLES } from '../../../database/index.js';
 import { getJidUser, getProfilePicBuffer, normalizeJid } from '../../config/index.js';
 import { isUserAdmin } from '../../config/index.js';
@@ -37,6 +38,44 @@ const SOCIAL_DST_EXPR = `JSON_UNQUOTE(
  */
 const buildUsageText = (commandPrefix = DEFAULT_COMMAND_PREFIX) => getUserUsageText('user', { commandPrefix }) || ['Formato de uso:', `${commandPrefix}user perfil <id|telefone>`, '', 'Dica:', '• Você pode mencionar alguém.', '• Ou responder a mensagem do usuário desejado.'].join('\n');
 
+/**
+ * Extrai metadados do remetente considerando payload novo do pipeline/socket.
+ * @param {object} params
+ * @param {object} [params.messageInfo]
+ * @param {string|null} [params.senderJid]
+ * @param {string|object|null} [params.senderIdentity]
+ * @returns {string|object|null}
+ */
+const resolveSenderSource = ({ messageInfo, senderJid, senderIdentity }) => {
+  const key = messageInfo?.key || {};
+
+  if (senderIdentity && typeof senderIdentity === 'object') {
+    return {
+      participant: senderIdentity.participant || key.participant || null,
+      participantAlt: senderIdentity.participantAlt || key.participantAlt || key.remoteJidAlt || null,
+      jid: senderIdentity.jid || senderJid || null,
+      remoteJid: key.remoteJid || null,
+      remoteJidAlt: key.remoteJidAlt || null,
+    };
+  }
+
+  return {
+    participant: key.participant || null,
+    participantAlt: key.participantAlt || key.remoteJidAlt || null,
+    jid: senderJid || (typeof senderIdentity === 'string' ? senderIdentity : null),
+    remoteJid: key.remoteJid || null,
+    remoteJidAlt: key.remoteJidAlt || null,
+  };
+};
+
+const hasResolvableIdentity = (value) => {
+  if (!value) return false;
+  if (typeof value === 'string') return Boolean(value.trim());
+  if (typeof value !== 'object') return false;
+
+  return Boolean(value?.jid || value?.lid || value?.participant || value?.participantAlt || value?.remoteJid || value?.remoteJidAlt || value?.id);
+};
+
 /**
  * Extrai o `contextInfo` da mensagem, incluindo estruturas aninhadas.
  * @param {object} messageInfo Estrutura da mensagem recebida pelo bot.
@@ -90,24 +129,34 @@ const parseTargetArgument = (rawValue) => {
  * Define qual usuário será usado como alvo (menção, argumento, reply ou remetente).
  * @param {object} messageInfo Mensagem usada para inferir contexto.
  * @param {string|null} senderJid JID do remetente do comando.
+ * @param {string|object|null} senderIdentity Identidade recebida do pipeline (participant/participantAlt/jid).
  * @param {string} targetArg Argumento explícito passado no comando.
  * @returns {{ source: string | object | null, invalidExplicitTarget: boolean }} Fonte escolhida e sinalizador de argumento inválido.
  */
-const resolveCandidateTarget = (messageInfo, senderJid, targetArg) => {
+const resolveCandidateTarget = (messageInfo, senderJid, senderIdentity, targetArg) => {
   const contextInfo = getContextInfo(messageInfo);
   const mentioned = Array.isArray(contextInfo?.mentionedJid) ? contextInfo.mentionedJid.find(Boolean) || null : null;
   const parsedTarget = parseTargetArgument(targetArg);
+  const quotedMessageKey = contextInfo?.quotedMessageKey && typeof contextInfo.quotedMessageKey === 'object' ? contextInfo.quotedMessageKey : null;
   const repliedSource =
-    contextInfo?.participant || contextInfo?.participantAlt
+    contextInfo?.participant || contextInfo?.participantAlt || quotedMessageKey?.participant || quotedMessageKey?.participantAlt
       ? {
-          participant: contextInfo.participant || null,
-          participantAlt: contextInfo.participantAlt || null,
+          participant: contextInfo?.participant || quotedMessageKey?.participant || null,
+          participantAlt: contextInfo?.participantAlt || quotedMessageKey?.participantAlt || null,
+          remoteJid: quotedMessageKey?.remoteJid || null,
+          remoteJidAlt: quotedMessageKey?.remoteJidAlt || null,
         }
       : null;
+  const senderSource = resolveSenderSource({
+    messageInfo,
+    senderJid,
+    senderIdentity,
+  });
   const hasContextTarget = Boolean(mentioned || repliedSource);
+  const normalizedSenderSource = hasResolvableIdentity(senderSource) ? senderSource : senderJid || null;
 
   return {
-    source: mentioned || parsedTarget.jid || repliedSource || senderJid || null,
+    source: mentioned || parsedTarget.jid || repliedSource || normalizedSenderSource || null,
     invalidExplicitTarget: parsedTarget.invalid && !hasContextTarget,
   };
 };
@@ -242,10 +291,10 @@ const formatPercent = (value, total) => {
 /**
  * Calcula a diferença inteira em dias entre dois timestamps.
  * @param {number} fromMs Timestamp inicial em milissegundos.
- * @param {number} [toMs=Date.now()] Timestamp final em milissegundos.
+ * @param {number} [toMs=__timeNowMs()] Timestamp final em milissegundos.
  * @returns {number} Quantidade de dias inteiros.
  */
-const toIntegerDays = (fromMs, toMs = Date.now()) => {
+const toIntegerDays = (fromMs, toMs = __timeNowMs()) => {
   if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || toMs < fromMs) return 0;
   return Math.floor((toMs - fromMs) / DAY_MS);
 };
@@ -873,7 +922,7 @@ const hasRecentInteraction = (lastMessage) => {
   const parsed = lastMessage instanceof Date ? lastMessage.getTime() : new Date(lastMessage).getTime();
   if (!Number.isFinite(parsed)) return false;
   const maxAgeMs = ACTIVE_DAYS_WINDOW * 24 * 60 * 60 * 1000;
-  return Date.now() - parsed <= maxAgeMs;
+  return __timeNowMs() - parsed <= maxAgeMs;
 };
 
 /**
@@ -901,7 +950,7 @@ const isTargetBlocked = async (targetIds) => {
 const formatTempoDeCasa = (firstMessage) => {
   const firstMs = toMillis(firstMessage);
   if (!Number.isFinite(firstMs)) return 'N/D';
-  const days = toIntegerDays(firstMs, Date.now());
+  const days = toIntegerDays(firstMs, __timeNowMs());
   return `${days} dia(s)`;
 };
 
@@ -913,7 +962,7 @@ const formatTempoDeCasa = (firstMessage) => {
 const formatDaysSinceLastMessage = (lastMessage) => {
   const lastMs = toMillis(lastMessage);
   if (!Number.isFinite(lastMs)) return 'N/D';
-  return `${toIntegerDays(lastMs, Date.now())} dia(s)`;
+  return `${toIntegerDays(lastMs, __timeNowMs())} dia(s)`;
 };
 
 /**
@@ -1016,20 +1065,19 @@ const resolveMentionJid = (ids = []) => ids.find((id) => isWhatsAppUserId(id)) |
  * @param {object} params.messageInfo Mensagem original usada como contexto.
  * @param {number|undefined} params.expirationMessage Configuração de expiração de mensagem.
  * @param {string} params.senderJid JID de quem executou o comando.
+ * @param {string|object|null} [params.senderIdentity=null] Identidade enriquecida do remetente (participant/participantAlt/jid).
  * @param {string[]} [params.args=[]] Argumentos recebidos após o comando.
  * @param {boolean} params.isGroupMessage Indica se o contexto é grupo.
  * @param {string} [params.commandPrefix=DEFAULT_COMMAND_PREFIX] Prefixo de comandos.
  * @returns {Promise<void>} Finaliza após responder ao usuário.
  */
-export async function handleUserCommand({ sock, remoteJid, messageInfo, expirationMessage, senderJid, args = [], isGroupMessage, commandPrefix = DEFAULT_COMMAND_PREFIX }) {
-  const subcommand = args?.[0]?.toLowerCase() || '';
-  if (subcommand !== 'perfil' && subcommand !== 'profile') {
-    await sendAndStore(sock, remoteJid, { text: buildUsageText(commandPrefix) }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
-    return;
-  }
-
-  const explicitTargetArg = args.slice(1).join(' ').trim();
-  const { source, invalidExplicitTarget } = resolveCandidateTarget(messageInfo, senderJid, explicitTargetArg);
+export async function handleUserCommand({ sock, remoteJid, messageInfo, expirationMessage, senderJid, senderIdentity = null, args = [], isGroupMessage, commandPrefix = DEFAULT_COMMAND_PREFIX }) {
+  const firstArg = String(args?.[0] || '')
+    .trim()
+    .toLowerCase();
+  const hasExplicitSubcommand = firstArg === 'perfil' || firstArg === 'profile';
+  const explicitTargetArg = hasExplicitSubcommand ? args.slice(1).join(' ').trim() : args.join(' ').trim();
+  const { source, invalidExplicitTarget } = resolveCandidateTarget(messageInfo, senderJid, senderIdentity, explicitTargetArg);
   if (invalidExplicitTarget) {
     await sendAndStore(sock, remoteJid, { text: `❌ ID ou telefone inválido.\n\n${buildUsageText(commandPrefix)}` }, { quoted: messageInfo, ephemeralExpiration: expirationMessage });
     return;
@@ -1044,11 +1092,12 @@ export async function handleUserCommand({ sock, remoteJid, messageInfo, expirati
     const senderIds = await resolveSenderIdsForTarget(canonicalTarget);
     const normalizedTargetIds = Array.from(new Set([canonicalTarget, ...senderIds].map((value) => normalizeJid(value) || value).filter(Boolean)));
     const mentionJid = resolveMentionJid(normalizedTargetIds);
-    const senderCanonical = resolveUserIdCached({
-      jid: senderJid,
-      lid: senderJid,
-      participantAlt: null,
+    const senderSource = resolveSenderSource({
+      messageInfo,
+      senderJid,
+      senderIdentity,
     });
+    const senderCanonical = await resolveCanonicalTarget(senderSource);
     const rankingTargetId = mentionJid || canonicalTarget;
 
     const [stats, ranking, latestPushName, premiumUsers, blocked, groupAdmin] = await Promise.all([fetchUserStats({ canonicalId: rankingTargetId, senderIds: normalizedTargetIds }), fetchUserRanking(rankingTargetId), fetchLatestPushName(normalizedTargetIds), premiumUserStore.getPremiumUsers(), isTargetBlocked(normalizedTargetIds), isGroupMessage ? isUserAdmin(remoteJid, mentionJid || canonicalTarget) : Promise.resolve(false)]);

package/app/modules/waifuPicsModule/AGENT.md

@@ -7,7 +7,7 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - arquivo_base: `app/modules/waifuPicsModule/commandConfig.json`
 - schema_version: `2.0.0`
 - module_enabled: `true`
-- generated_at: `2026-03-11T02:35:17.177Z`
+- generated_at: `2026-03-17T04:04:14.195Z`
 
 ## Escopo do Modulo
 
@@ -90,9 +90,9 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - <prefix>wp neko
 - mensagens_uso (variantes):
 - default:
-- 💡 _Uso:_ <prefix>waifu <categoria>
-  Exemplo: <prefix>waifu neko
-- Dica: Use <prefix>waifuajuda para ver todas as categorias! 🎨
+- 🖼️ _Como usar:_ <prefix>waifu <categoria>
+- Exemplos rápidos: <prefix>waifu neko | <prefix>wp hug
+- Quer ver todas as categorias disponíveis? Use <prefix>waifuajuda.
 - subcomandos:
 - (nenhum)
 - argumentos:
@@ -125,12 +125,22 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - consulta API externa
 - envia imagem no chat
 - respostas_padrao:
-- success: Prontinho! Aqui está sua imagem. ✨
-- usage_error: Ops! Parece que você esqueceu a categoria. Use <prefix>waifuajuda para ver as opções disponíveis. 🧐
-- permission_error: Eita! Você não tem permissão para usar este comando. Entre em contato com um administrador. 🔐
-- sucesso: Comando executado com sucesso.
-- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
-- erro_permissao: Permissão insuficiente para executar este comando.
+- success: ✅ Pedido recebido! Aqui vai sua imagem.
+  Dica: você pode pedir outra categoria no próximo comando (ex.: <prefix>waifu neko).
+- usage_error: ❗ Não entendi o formato do comando.
+  Exemplos:
+  • <prefix>waifu neko
+  • <prefix>waifunsfw waifu
+  Para ver todas as categorias: <prefix>waifuajuda
+- permission_error: 🔒 Este comando não está liberado para você neste contexto.
+  Se for NSFW em grupo, peça para um admin usar <prefix>nsfw on.
+- sucesso: ✅ Imagem enviada com sucesso!
+  Exemplo de próximo pedido: <prefix>waifu hug
+- erro_uso: ❗ Categoria inválida ou ausente.
+  Exemplos: <prefix>waifu neko | <prefix>wp waifu
+  Veja a lista completa em <prefix>waifuajuda.
+- erro_permissao: 🔒 Não consegui liberar este pedido para seu perfil.
+  Se achar que é engano, verifique seu plano e tente novamente.
 - mensagens_sistema:
 - (nao informado)
 - limites_operacionais:
@@ -211,9 +221,9 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - <prefix>wpnsfw waifu
 - mensagens_uso (variantes):
 - default:
-- 🔞 _Uso:_ <prefix>waifunsfw <categoria>
-  Exemplo: <prefix>wpnsfw blowjob
-- Atenção: O grupo deve estar com NSFW ligado!
+- 🔞 _Como usar:_ <prefix>waifunsfw <categoria>
+- Exemplos rápidos: <prefix>waifunsfw waifu | <prefix>wpnsfw neko
+- Pré-requisitos: plano Premium; em grupo, NSFW ativo com <prefix>nsfw on.
 - subcomandos:
 - (nenhum)
 - argumentos:
@@ -247,12 +257,22 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - consulta API externa
 - envia imagem NSFW no chat
 - respostas_padrao:
-- success: Prontinho! Aqui está sua imagem. ✨
-- usage_error: Ops! Parece que você esqueceu a categoria. Use <prefix>waifuajuda para ver as opções disponíveis. 🧐
-- permission_error: Eita! Você não tem permissão para usar este comando. Entre em contato com um administrador. 🔐
-- sucesso: Comando executado com sucesso.
-- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
-- erro_permissao: Permissão insuficiente para executar este comando.
+- success: ✅ Pedido recebido! Aqui vai sua imagem.
+  Dica: você pode pedir outra categoria no próximo comando (ex.: <prefix>waifu neko).
+- usage_error: ❗ Não entendi o formato do comando.
+  Exemplos:
+  • <prefix>waifu neko
+  • <prefix>waifunsfw waifu
+  Para ver todas as categorias: <prefix>waifuajuda
+- permission_error: 🔒 Este comando não está liberado para você neste contexto.
+  Se for NSFW em grupo, peça para um admin usar <prefix>nsfw on.
+- sucesso: 🔞 Imagem NSFW enviada.
+  Exemplo de próximo pedido: <prefix>waifunsfw neko
+- erro_uso: ❗ Categoria NSFW inválida ou ausente.
+  Exemplos: <prefix>waifunsfw waifu | <prefix>wpnsfw neko
+  Veja opções em <prefix>waifuajuda.
+- erro_permissao: 🔒 Este comando NSFW exige acesso Premium.
+  Em grupos, também é preciso NSFW ativo com <prefix>nsfw on.
 - mensagens_sistema:
 - (nao informado)
 - limites_operacionais:
@@ -332,8 +352,9 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - <prefix>waifuajuda
 - mensagens_uso (variantes):
 - default:
-- 📖 _Guia Rápido:_ Digite <prefix>waifuajuda para ver as categorias SFW e NSFW disponíveis.
-- Use <prefix>waifu <categoria> para receber uma imagem!
+- 📖 _Como usar:_ <prefix>waifuajuda
+- Depois do guia, teste: <prefix>waifu neko
+- Para NSFW: <prefix>waifunsfw waifu (Premium; em grupo exige <prefix>nsfw on).
 - subcomandos:
 - (nenhum)
 - argumentos:
@@ -364,12 +385,21 @@ Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos co
 - efeitos_colaterais:
 - envia mensagem de ajuda
 - respostas_padrao:
-- success: Prontinho! Aqui está sua imagem. ✨
-- usage_error: Ops! Parece que você esqueceu a categoria. Use <prefix>waifuajuda para ver as opções disponíveis. 🧐
-- permission_error: Eita! Você não tem permissão para usar este comando. Entre em contato com um administrador. 🔐
-- sucesso: Comando executado com sucesso.
-- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
-- erro_permissao: Permissão insuficiente para executar este comando.
+- success: ✅ Pedido recebido! Aqui vai sua imagem.
+  Dica: você pode pedir outra categoria no próximo comando (ex.: <prefix>waifu neko).
+- usage_error: ❗ Não entendi o formato do comando.
+  Exemplos:
+  • <prefix>waifu neko
+  • <prefix>waifunsfw waifu
+  Para ver todas as categorias: <prefix>waifuajuda
+- permission_error: 🔒 Este comando não está liberado para você neste contexto.
+  Se for NSFW em grupo, peça para um admin usar <prefix>nsfw on.
+- sucesso: 📚 Guia enviado com sucesso.
+  Agora experimente: <prefix>waifu neko
+- erro_uso: ℹ️ Este comando não precisa de argumentos.
+  Use apenas: <prefix>waifuajuda
+- erro_permissao: 🔒 Não consegui mostrar o guia neste contexto.
+  Tente novamente no privado ou em um grupo permitido.
 - mensagens_sistema:
 - (nao informado)
 - limites_operacionais:

package/app/modules/waifuPicsModule/commandConfig.json

@@ -357,6 +357,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "waifu",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Guia rápido para usar o comando waifu e receber uma imagem de anime (SFW) da categoria escolhida.",
+        "quando_usar": ["Quando você quer uma imagem de anime específica (ex.: neko, waifu) sem enviar outras perguntas."],
+        "exemplos_reais": [
+          {
+            "situacao": "Quero uma imagem de neko.",
+            "comando": "<prefix>waifu neko",
+            "resposta_esperada": "✅ Imagem enviada com sucesso! Exemplo de próximo pedido: <prefix>waifu hug.",
+            "variacao": "Usando alias: <prefix>wp neko."
+          },
+          {
+            "situacao": "Não informei a categoria.",
+            "comando": "<prefix>waifu",
+            "resposta_esperada": "❗ Categoria inválida ou ausente. Exemplos: <prefix>waifu neko | <prefix>wp waifu Veja a lista completa em <prefix>waifuajuda.",
+            "variacao": "Tente: <prefix>waifu neko."
+          },
+          {
+            "situacao": "Categoria não suportada.",
+            "comando": "<prefix>waifu dragon",
+            "resposta_esperada": "❗ Categoria inválida ou ausente. Exemplos: <prefix>waifu neko | <prefix>wp waifu Veja a lista completa em <prefix>waifuajuda.",
+            "variacao": "Tente uma categoria comum como neko ou waifu."
+          }
+        ],
+        "resposta_esperada": ["O bot envia uma imagem de anime da categoria solicitada (SFW)."],
+        "erros_comuns_usuario": ["Esquecer de indicar a categoria", "Usar uma categoria não suportada", "Usar o comando sem o prefixo quando necessário", "Erro de conexão temporário"],
+        "passos_se_der_erro": ["1. Verifique se digitou a categoria corretamente. 2. Use o formato com prefixo: <prefix>waifu <categoria> ou <prefix>wp <categoria>. 3. Se receber erro de categoria, peça a lista de categorias com <prefix>waifuajuda e es"],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     },
     {
@@ -575,6 +604,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "waifunsfw",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Envie imagens NSFW de waifus em grupos autorizados. Requer Premium e NSFW ativo. Use <prefix>waifunsfw <categoria> ou <prefix>wpnsfw <waifu>.",
+        "quando_usar": ["Quando o grupo tiver NSFW ativo e você for assinante Premium.", "Para solicitar uma imagem NSFW de uma categoria válida (ex.: neko, waifu, etc.).", "Para confirmar qual variedade de conteúdo NSFW está disponível no momento."],
+        "exemplos_reais": [
+          {
+            "situacao": "Grupo com NSFW ativo e usuário Premium solicita neko.",
+            "comando": "<prefix>waifunsfw neko",
+            "resposta_esperada": "🔞 Imagem NSFW enviada. Exemplo de próximo pedido: <prefix>waifunsfw neko.",
+            "variacao": "neko."
+          },
+          {
+            "situacao": "Grupo sem Premium ou NSFW ativo.",
+            "comando": "<prefix>waifunsfw neko",
+            "resposta_esperada": "🔒 Este comando NSFW exige acesso Premium. Em grupos, também é preciso NSFW ativo com <prefix>nsfw on.",
+            "variacao": "premium_required."
+          },
+          {
+            "situacao": "Categoria NSFW inválida.",
+            "comando": "<prefix>waifunsfw manga",
+            "resposta_esperada": "❗ Categoria NSFW inválida ou ausente. Exemplos: <prefix>waifunsfw waifu | <prefix>wpnsfw neko Veja opções em <prefix>waifuajuda.",
+            "variacao": "categoria_invalida."
+          }
+        ],
+        "resposta_esperada": ["🔞 Imagem NSFW enviada. Exemplo de próximo pedido: <prefix>waifunsfw neko", "❗ Categoria NSFW inválida ou ausente. Exemplos: <prefix>waifunsfw waifu | <prefix>wpnsfw neko Veja opções em <prefix>waifuajuda.", "🔒 Este comando NSFW exige acesso Premium. Em grupos, também é preciso NSFW ativo com <prefix>nsfw on."],
+        "erros_comuns_usuario": ["Não informar a categoria NSFW", "Categoria informada não é suportada", "NSFW não está ativo no grupo", "Usuário não possui assinatura Premium"],
+        "passos_se_der_erro": ["Verifique se o NSFW está ativo no grupo com <prefix>nsfw on e peça ao admin para ativar, se necessário.", "Confirme que você possui uma assinatura Premium válida para usar o comando.", "Certifique-se de digitar uma categoria NSFW suportada, por exemplo neko, waifu, etc.", "Tente novamente com uma categoria diferente ou em outro momento; se o problema persistir, peça ajuda ao administrador do grupo."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     },
     {
@@ -771,6 +829,35 @@
         "schema": "legacy_v1_and_v2",
         "legacy_name": "waifuajuda",
         "legacy_fields_present": ["descricao", "metodos_de_uso", "permissao_necessaria", "local_de_uso", "informacoes_coletadas", "argumentos", "pre_condicoes", "dependencias_externas", "efeitos_colaterais", "observabilidade", "privacidade", "acesso", "limite_uso_por_plano"]
+      },
+      "user_experience": {
+        "resumo_usuario": "Guia rápido das categorias de fotos anime que posso enviar. Mostra todas as opções disponíveis e como usar o comando. Não é necessário Premium; funciona para planos comum e premium.",
+        "quando_usar": ["Quando você quer conhecer todas as categorias de fotos disponíveis sem digitar argumentos", "Quando precisa confirmar que o comando não aceita parâmetros", "Quando desejar usar o alias wppicshelp para abrir o guia rapidamente"],
+        "exemplos_reais": [
+          {
+            "situacao": "Usuário quer abrir o guia rapidamente com o prefix.",
+            "comando": "<prefix>waifuajuda",
+            "resposta_esperada": "Guia de categorias exibido. Exemplo: <prefix>waifu neko.",
+            "variacao": "uso direto com <prefix>."
+          },
+          {
+            "situacao": "Usuário prefere usar o alias.",
+            "comando": "wppicshelp",
+            "resposta_esperada": "Guia de categorias exibido. Observação: você pode usar <prefix>waifu neko para abrir uma categoria específica.",
+            "variacao": "alias."
+          },
+          {
+            "situacao": "Usuário está em contexto privado ou grupo permitido.",
+            "comando": "<prefix>waifuajuda",
+            "resposta_esperada": "Guia pronto. Veja as categorias disponíveis e escolha uma: neko, shinobu, etc.",
+            "variacao": "contexto privado ou grupo permitido."
+          }
+        ],
+        "resposta_esperada": ["Guia de categorias exibido com sucesso. Use <prefix>waifu neko para ver fotos de uma categoria específica."],
+        "erros_comuns_usuario": ["Tentar usar o comando com argumentos, quando ele não exige nenhum.", "Esquecer de incluir o prefixo, por exemplo usar 'waifuajuda' sem o prefixo.", "Tentar usar em contexto onde o guia não pode ser exibido (contextos não suportados)."],
+        "passos_se_der_erro": ["Verifique se o comando está sendo usado em um contexto permitido (privado ou grupo permitido).", "Tente novamente com o prefix correto: <prefix>waifuajuda.", "Se o guia não aparecer, tente novamente mais tarde ou entre em contato com o suporte."],
+        "resumo_usuario_origem": "auto_ia_assistida",
+        "resumo_usuario_revisao_pendente": true
       }
     }
   ],

package/app/modules/waifuPicsModule/waifuPicsCommand.js

@@ -1,3 +1,4 @@
+import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import axios from 'axios';
 
 import logger from '#logger';
@@ -278,7 +279,7 @@ const buildRateScopeKey = ({ scope, senderKey, remoteJid }) => {
   return `user:${String(senderKey || '').trim() || 'unknown'}`;
 };
 
-const pruneRateMapIfNeeded = (now = Date.now()) => {
+const pruneRateMapIfNeeded = (now = __timeNowMs()) => {
   if (userPlanRateMap.size <= USER_RATE_LIMIT_MAP_MAX_SIZE) return;
 
   for (const [key, value] of userPlanRateMap.entries()) {
@@ -302,7 +303,7 @@ const pruneRateMapIfNeeded = (now = Date.now()) => {
 const checkPlanUsageRateLimit = ({ commandKey, userPlan, scope, max, windowMs, senderKey, remoteJid }) => {
   if (!max || !windowMs) return { limited: false, remainingMs: 0 };
 
-  const now = Date.now();
+  const now = __timeNowMs();
   const scopeKey = buildRateScopeKey({ scope, senderKey, remoteJid });
   const cacheKey = `${String(commandKey || 'waifu')}:${normalizePlanName(userPlan)}:${scopeKey}`;
   const current = userPlanRateMap.get(cacheKey);

package/app/observability/metrics.js

@@ -32,6 +32,8 @@ const METRICS_SERVICE = process.env.METRICS_SERVICE_NAME || process.env.ECOSYSTE
 const HTTP_SLO_TARGET_MS = Math.max(50, parseEnvNumber(process.env.HTTP_SLO_TARGET_MS, 750));
 
 const QUERY_THRESHOLDS_MS = parseThresholds(process.env.DB_QUERY_ALERT_THRESHOLDS, [500, 1000]);
+const ADMIN_ALERT_SEVERITIES = Object.freeze(['critical', 'high', 'medium', 'low', 'unknown']);
+const ADMIN_FEATURE_FLAG_STATES = Object.freeze(['enabled', 'disabled', 'total']);
 
 const registry = new client.Registry();
 let metrics = null;
@@ -375,6 +377,53 @@ const ensureMetrics = () => {
       labelNames: ['outcome'],
       registers: [registry],
     }),
+    adminOverviewUpdatedAtSeconds: new client.Gauge({
+      name: 'omnizap_admin_overview_updated_at_seconds',
+      help: 'Timestamp Unix (s) da ultima atualizacao de snapshot do painel admin',
+      registers: [registry],
+    }),
+    adminOverviewRequestsTotal: new client.Counter({
+      name: 'omnizap_admin_overview_requests_total',
+      help: 'Total de snapshots do painel admin publicados em metricas',
+      labelNames: ['source'],
+      registers: [registry],
+    }),
+    adminCounters: new client.Gauge({
+      name: 'omnizap_admin_counters',
+      help: 'Contadores agregados do painel admin',
+      labelNames: ['counter'],
+      registers: [registry],
+    }),
+    adminDashboardQuick: new client.Gauge({
+      name: 'omnizap_admin_dashboard_quick',
+      help: 'Metricas rapidas do dashboard admin',
+      labelNames: ['metric'],
+      registers: [registry],
+    }),
+    adminSystemHealth: new client.Gauge({
+      name: 'omnizap_admin_system_health',
+      help: 'Indicadores de saude expostos no painel admin',
+      labelNames: ['metric'],
+      registers: [registry],
+    }),
+    adminAlertsTotal: new client.Gauge({
+      name: 'omnizap_admin_alerts_total',
+      help: 'Total de alertas ativos por severidade no painel admin',
+      labelNames: ['severity'],
+      registers: [registry],
+    }),
+    adminFeatureFlagsTotal: new client.Gauge({
+      name: 'omnizap_admin_feature_flags_total',
+      help: 'Distribuicao de feature flags no painel admin',
+      labelNames: ['state'],
+      registers: [registry],
+    }),
+    adminSnapshotItemsTotal: new client.Gauge({
+      name: 'omnizap_admin_snapshot_items_total',
+      help: 'Total de itens por secao no snapshot do painel admin',
+      labelNames: ['section'],
+      registers: [registry],
+    }),
   };
 
   return metrics;
@@ -502,6 +551,93 @@ export const recordMessagesUpsert = ({ durationMs, type, messagesCount, ok }) =>
   }
 };
 
+export const setAdminOverviewSnapshot = ({ overview = null, source = 'admin_overview' } = {}) => {
+  const m = ensureMetrics();
+  if (!m) return;
+  if (!overview || typeof overview !== 'object') return;
+
+  const setGaugeIfFinite = (gauge, labels, value, { clampToZero = false } = {}) => {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric)) return;
+    gauge.set(labels, clampToZero ? Math.max(0, numeric) : numeric);
+  };
+
+  const sourceLabel = normalizeLabel(source, 'admin_overview').slice(0, 32);
+  m.adminOverviewRequestsTotal.inc({ source: sourceLabel });
+
+  const updatedAtMs = Date.parse(String(overview?.updated_at || ''));
+  const updatedAtSeconds = Number.isFinite(updatedAtMs) ? updatedAtMs / 1000 : Date.now() / 1000;
+  m.adminOverviewUpdatedAtSeconds.set(updatedAtSeconds);
+
+  const counters = overview?.counters && typeof overview.counters === 'object' ? overview.counters : {};
+  const counterKeys = ['total_packs_any_status', 'total_stickers_any_status', 'active_google_sessions', 'known_google_users', 'active_bans', 'visit_events_24h', 'visit_events_7d', 'unique_visitors_7d'];
+  for (const key of counterKeys) {
+    setGaugeIfFinite(m.adminCounters, { counter: key }, counters?.[key], { clampToZero: true });
+  }
+
+  const dashboardQuick = overview?.dashboard_quick && typeof overview.dashboard_quick === 'object' ? overview.dashboard_quick : {};
+  const quickKeys = ['bots_online', 'messages_today', 'spam_blocked_today', 'errors_5xx'];
+  for (const key of quickKeys) {
+    setGaugeIfFinite(m.adminDashboardQuick, { metric: key }, dashboardQuick?.[key], { clampToZero: true });
+  }
+
+  const systemHealth = overview?.system_health && typeof overview.system_health === 'object' ? overview.system_health : {};
+  const healthKeys = ['cpu_percent', 'ram_percent', 'http_latency_p95_ms', 'queue_pending', 'db_total_queries', 'db_slow_queries'];
+  for (const key of healthKeys) {
+    setGaugeIfFinite(m.adminSystemHealth, { metric: key }, systemHealth?.[key], { clampToZero: true });
+  }
+
+  const moderationQueue = Array.isArray(overview?.moderation_queue) ? overview.moderation_queue : [];
+  const auditLog = Array.isArray(overview?.audit_log) ? overview.audit_log : [];
+  const users = Array.isArray(overview?.users_sessions?.users) ? overview.users_sessions.users : [];
+  const activeSessions = Array.isArray(overview?.users_sessions?.active_sessions) ? overview.users_sessions.active_sessions : [];
+  const blockedAccounts = Array.isArray(overview?.users_sessions?.blocked_accounts) ? overview.users_sessions.blocked_accounts : [];
+  const alerts = Array.isArray(overview?.alerts) ? overview.alerts : [];
+  const featureFlags = Array.isArray(overview?.feature_flags) ? overview.feature_flags : [];
+
+  m.adminSnapshotItemsTotal.set({ section: 'moderation_queue' }, moderationQueue.length);
+  m.adminSnapshotItemsTotal.set({ section: 'audit_log' }, auditLog.length);
+  m.adminSnapshotItemsTotal.set({ section: 'users' }, users.length);
+  m.adminSnapshotItemsTotal.set({ section: 'active_sessions' }, activeSessions.length);
+  m.adminSnapshotItemsTotal.set({ section: 'blocked_accounts' }, blockedAccounts.length);
+  m.adminSnapshotItemsTotal.set({ section: 'alerts' }, alerts.length);
+  m.adminSnapshotItemsTotal.set({ section: 'feature_flags' }, featureFlags.length);
+
+  const severityCounts = Object.fromEntries(ADMIN_ALERT_SEVERITIES.map((severity) => [severity, 0]));
+  for (const alert of alerts) {
+    const severityRaw = String(alert?.severity || '')
+      .trim()
+      .toLowerCase();
+    const severity = ADMIN_ALERT_SEVERITIES.includes(severityRaw) ? severityRaw : 'unknown';
+    severityCounts[severity] = Number(severityCounts[severity] || 0) + 1;
+  }
+  for (const severity of ADMIN_ALERT_SEVERITIES) {
+    m.adminAlertsTotal.set({ severity }, Number(severityCounts[severity] || 0));
+  }
+
+  let enabledFlags = 0;
+  let disabledFlags = 0;
+  for (const flag of featureFlags) {
+    if (flag?.is_enabled) {
+      enabledFlags += 1;
+    } else {
+      disabledFlags += 1;
+    }
+  }
+  const totalFlags = enabledFlags + disabledFlags;
+  for (const state of ADMIN_FEATURE_FLAG_STATES) {
+    if (state === 'enabled') {
+      m.adminFeatureFlagsTotal.set({ state }, enabledFlags);
+      continue;
+    }
+    if (state === 'disabled') {
+      m.adminFeatureFlagsTotal.set({ state }, disabledFlags);
+      continue;
+    }
+    m.adminFeatureFlagsTotal.set({ state }, totalFlags);
+  }
+};
+
 export const recordRpgPlayerCreated = (value = 1) => {
   const m = ensureMetrics();
   if (!m) return;