Contrato de Mensagem - Worker

Versao: 1.2
Objetivo: padronizar o payload de mensagens publicadas no SQS e chamadas HTTP de processamento por canal.

Onde isso entra no sistema: o worker consome mensagens neste formato da fila SQS_QUEUE_URL. O orquestrador (pré-processamento portal) publica na mesma fila após montar notifications[]; integrações com o SDK podem publicar diretamente nessa fila, sem passar pelo orquestrador. Diagrama e fluxos: Fluxo de mensageria completo.

---

1) Payload para fila SQS

Use este payload quando sua aplicacao publica eventos para a fila consumida pelo worker.

Campo	Tipo	Obrigatorio	Descricao
id / dedupKey	string	Recomendado	Chave de idempotencia da mensagem.
correlationId	string	Recomendado	Correlacao de logs/requests entre sistemas (id da requisicao/evento de negocio). Pode ser UUID, string legivel etc.
traceparent	string	Opcional	W3C Trace Context (00-<trace-id>-<parent-id>-01).
company_id	number	Sim	Empresa/tenant emissor da notificacao.
internal_sector	string	Opcional	Identificador do setor interno (ex.: financeiro, compras). Persistido em tb_notifications.internal_sector.
notifications	array	Sim	Lista de destinatarios e canais.
metadata	object	Opcional	Metadados livres para origem, batch e contexto.

Estrutura de notifications[]

Campo	Tipo	Obrigatorio	Descricao
id	number ou string	Opcional	Identificador do item da lista.
template_id	number	Sim	Template cadastrado no banco.
email	string	Condicional	Obrigatorio para canal email.
phone	string	Condicional	Obrigatorio para sms/whatsapp.
variables_value	object	Opcional	Variaveis de preenchimento do template.
info	object	Sim	Configuracao de canais e atributos extras.

Estrutura de info

Campo	Tipo	Descricao
channels	number[]	0=email, 1=whatsapp, 2=sms, 3=push, 4=interno.
token	string	Token FCM para push.
from	string	Remetente para SMS.
data	object	Dados extras para push.

Exemplo completo SQS

json
{
  "dedupKey": "pedido-123-notif-1",
  "correlationId": "req-123",
  "company_id": 10,
  "internal_sector": "financeiro",
  "notifications": [
    {
      "id": "item-1",
      "template_id": 5,
      "email": "destinatario@exemplo.com",
      "phone": "+5511999999999",
      "variables_value": { "nome": "Maria" },
      "info": { "channels": [0, 2], "from": "Mobilemed" }
    }
  ],
  "metadata": {
    "source": "faturamento",
    "batch_id": "batch-001"
  }
}

---

2) Payload para POST /notifications/process-job

Endpoint para processar um job por requisicao HTTP (normalmente por um consumidor externo).

Campo	Tipo	Obrigatorio	Descricao
channel	string	Sim	email, sms, push ou whatsapp.
notificationId	number	Opcional	ID de rastreio do recipient/notificacao.
correlationId	string	Opcional	Correlacao de logs.
traceId	string	Opcional	Rastreio distribuido.
payload	object	Sim	Conteudo do job por canal.
loadTest	object	Opcional	{"simulateError": true|false} (respeita LOAD_TEST_MODE=true).

Exemplo por canal

json
{
  "channel": "email",
  "correlationId": "req-123",
  "payload": {
    "to": "destinatario@exemplo.com",
    "subject": "Assunto",
    "body": "<p>Corpo HTML</p>",
    "attachments": [
      {
        "filename": "arquivo.pdf",
        "content": "BASE64_AQUI",
        "contentType": "application/pdf"
      }
    ]
  }
}

json
{
  "channel": "sms",
  "payload": {
    "to": "+5511999999999",
    "message": "Mensagem SMS",
    "from": "Mobilemed",
    "attribute": "Transactional"
  }
}

json
{
  "channel": "push",
  "payload": {
    "token": "fcm-token",
    "title": "Titulo",
    "body": "Corpo",
    "data": { "screen": "orders" }
  }
}

json
{
  "channel": "whatsapp",
  "payload": {
    "to": "+5511999999999",
    "message": "Mensagem WhatsApp"
  }
}

---

3) Idempotencia, retry e DLQ

• O worker usa dedupKey/id para evitar reenvio duplicado (tb_notification_dedup).
• Em falha de processamento, a mensagem nao e deletada e pode ser reentregue pelo SQS.
• Com politica de redrive no SQS, mensagens excedendo tentativas vao para DLQ.
• O worker respeita SQS_MAX_RECEIVE_COUNT para interromper processamento local e deixar o redrive atuar.

---

4) Rastreabilidade

• correlationId: correlacao entre requisicao de origem, fila e logs do worker.
• traceparent: continuidade de tracing distribuido (APM). Se voce nao tem tracing, pode omitir.
• Obs: a fila do worker nao espera traceId. O identificador usado como trace.id nos logs deve ser enviado em correlationId.
• internal_sector: classificacao interna de custo/setor persistida em tb_notifications.

---

5) Historico de versao

• v1.2: referência ao documento de fluxos do monorepo e diagrama de produtores da fila.
• v1.1: adiciona internal_sector no payload SQS e persistencia em tb_notifications.
• v1.0: contrato inicial (id/dedupKey, correlationId, traceId, traceparent, metadata e canais).