Pular para o conteúdo principal

Feature - Fila Assíncrona de Link de Grupo

Introdução ao documento​

Este documento descreve a feature de enfileiramento e processamento assíncrono para envio de template de link de grupo. Evidência: src/services/groupLinkDispatchQueue.ts:24 Evidência: src/workers/groupLinkDispatchWorker.ts:171

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:16

Referencial teórico​

  • Model GroupLinkDispatchQueue.
  • Serviço de enqueue + worker com retry. Evidência: src/models/groupLinkDispatchQueue.ts:60 Evidência: src/services/groupLinkDispatchQueue.ts:24 Evidência: src/workers/groupLinkDispatchWorker.ts:99

Visão geral​

Após matrícula em fluxo personal ou business, o sistema enfileira o envio do link de grupo e processa em background com tentativas controladas. Evidência: src/flows/personal.ts:207 Evidência: src/flows/business.ts:639 Evidência: src/workers/groupLinkDispatchWorker.ts:121

Atores​

  • Fluxos de matrícula (personal e business) que publicam jobs.
  • Worker de fila que consome jobs.
  • API WhatsApp que recebe o envio final. Evidência: src/flows/personal.ts:207 Evidência: src/workers/groupLinkDispatchWorker.ts:158 Evidência: src/features/api/whatsapp/sendGroupLinkTemplate.ts:13

Pré-condições​

  • Tabela/model GroupLinkDispatchQueue disponível.
  • Worker iniciado (startGroupLinkDispatchWorker) no bootstrap.
  • Credenciais WhatsApp configuradas. Evidência: src/models/groupLinkDispatchQueue.ts:122 Evidência: src/server.ts:82 Evidência: src/features/api/whatsapp/sendGroupLinkTemplate.ts:5 Evidência: src/features/api/whatsapp/sendGroupLinkTemplate.ts:7

Fluxo principal​

  1. Fluxo chama enqueueGroupLinkTemplate com dados de matrícula.
  2. Job é persistido com status=pending e availableAt.
  3. Worker captura próximo job vencido e marca como processing.
  4. Worker envia template via WhatsApp API.
  5. Em sucesso, marca status=sent. Evidência: src/services/groupLinkDispatchQueue.ts:36 Evidência: src/services/groupLinkDispatchQueue.ts:43 Evidência: src/workers/groupLinkDispatchWorker.ts:77 Evidência: src/workers/groupLinkDispatchWorker.ts:101 Evidência: src/workers/groupLinkDispatchWorker.ts:114

Fluxos alternativos​

  • Job sem ID válido é descartado.
  • Falha transitória: volta para pending com novo availableAt.
  • Exaustão de tentativas: marca failed.
  • Jobs presos em processing são recuperados no start do worker. Evidência: src/workers/groupLinkDispatchWorker.ts:73 Evidência: src/workers/groupLinkDispatchWorker.ts:138 Evidência: src/workers/groupLinkDispatchWorker.ts:125 Evidência: src/workers/groupLinkDispatchWorker.ts:33

Regras de negócio​

  • delayMs mínimo é 0; maxAttempts mínimo é 1.
  • Retry delay cresce com multiplicador limitado (MAX_RETRY_MULTIPLIER=8).
  • Processamento em lote respeita GROUP_LINK_WORKER_BATCH_SIZE. Evidência: src/services/groupLinkDispatchQueue.ts:33 Evidência: src/services/groupLinkDispatchQueue.ts:34 Evidência: src/workers/groupLinkDispatchWorker.ts:16 Evidência: src/workers/groupLinkDispatchWorker.ts:30 Evidência: src/workers/groupLinkDispatchWorker.ts:157

Estados possíveis (quando houver)​

  • pending
  • processing
  • sent
  • failed Evidência: src/models/groupLinkDispatchQueue.ts:4

Endpoints envolvidos​

  • POST / (fluxos de matrícula que enfileiram).
  • POST /sendreminder (envio síncrono alternativo de template de grupo). Evidência: src/flows/personal.ts:207 Evidência: src/routes/sendGroupLink.ts:8

Dados impactados​

  • Tabela/model GroupLinkDispatchQueue.
  • Referência de dados locais: ../data/model.md. Evidência: src/models/groupLinkDispatchQueue.ts:60 Evidência: src/services/groupLinkDispatchQueue.ts:36

Pendências​

  • Confirmar necessidade de limpeza/retenção de jobs sent e failed. Evidência: src/models/groupLinkDispatchQueue.ts:114 Evidência: src/workers/groupLinkDispatchWorker.ts:124