**PROMPT MESTRE DA PLATAFORMA OPERACIONAL ONSMS**.

---

# 🔷 PROMPT MESTRE – PLATAFORMA OPERACIONAL ONSMS

*(para uso no Replit / agente de desenvolvimento)*

## 📌 CONTEXTO GERAL

Você é um **arquiteto de software sênior** responsável por projetar e implementar uma **Plataforma Operacional** que funciona como intermediária entre a **Plataforma OnSMS** e **ferramentas externas de disparo de WhatsApp**.

Esta plataforma **NÃO cuida de cobrança, créditos ou financeiro**.
Toda a parte financeira é responsabilidade exclusiva da **OnSMS principal**.

A Plataforma Operacional tem **uma única missão**:
👉 **processar campanhas**,
👉 **gerar pacotes operacionais**,
👉 **receber relatórios**,
👉 **normalizar status**,
👉 **retornar os resultados via API para a OnSMS**.

---

## 🎯 OBJETIVO PRINCIPAL

Criar uma aplicação backend que:

1. Receba **lotes/campanhas via API**
2. Organize os arquivos da campanha
3. Gere um **ZIP operacional**
4. Envie esse ZIP por **e-mail para um operador humano**
5. Aguarde o **retorno do e-mail com relatório**
6. Leia automaticamente o relatório
7. Normalize os status
8. Atualize os status da campanha
9. Envie os status finais via API para a **OnSMS**

---

## 🧩 VISÃO DE ARQUITETURA

### Plataformas envolvidas:

* **OnSMS (principal)** → envia campanhas e recebe status
* **Plataforma Operacional (esta)** → processa e controla
* **Operador humano** → usa ferramenta de disparo externa
* **Ferramenta externa** → gera relatório (CSV, XLS, TXT)

---

## 🗂️ ESTRUTURA DE UMA CAMPANHA

Cada campanha (lote) pode conter:

* Texto da mensagem (`.txt`)
* Base de números (`.csv`)
* Imagem (`.jpg/.png`) – opcional
* Vídeo (`.mp4`) – opcional

A plataforma deve:

* Validar os arquivos
* Padronizar nomes
* Gerar um **ZIP único por campanha**

---

## 📦 CONTEÚDO DO ZIP GERADO

Estrutura padrão:

```
campanha_12345.zip
 ├── mensagem.txt
 ├── numeros.csv
 ├── imagem.jpg (opcional)
 ├── video.mp4 (opcional)
 └── README.txt
```

O `README.txt` deve conter:

* ID da campanha
* Data/hora
* Instruções simples para o operador
* Formato esperado do relatório de retorno

---

## 📧 FLUXO DE E-MAIL

### Envio:

* Um **e-mail por campanha**
* Assunto padronizado:

  ```
  [ONSMS][CAMPANHA #12345] Arquivos para disparo
  ```
* Anexo: ZIP da campanha

### Retorno:

* O operador responde **o mesmo e-mail**
* Anexa o **relatório de envio**
* A plataforma deve:

  * Monitorar a caixa de entrada
  * Identificar a campanha pelo assunto ou ID interno
  * Baixar automaticamente o anexo
  * Processar o relatório

---

## 📄 RELATÓRIO DE ENVIO

O relatório pode conter **status divergentes**, em idiomas diferentes ou formatos distintos.

Exemplos de status recebidos:

```
READ, DELIVERED, RECEIVED, SENT,
ENVIADO, LIDO, RECEBIDO, ENTREGUE, ENVIADOS
```

Ou:

```
ERROR 130472, ERROR, NÃO ENVIADO, NAO ENVIADO,
ERRO, FALHA, NUMERO SEM WHATSAPP
```

---

## 🔁 NORMALIZAÇÃO DE STATUS (REGRA DE OURO)

### STATUS FINAIS (INTERNOS)

A plataforma deve trabalhar com apenas **dois status finais**:

* **Enviado**
* **Não Enviado**

### MAPEAMENTO OBRIGATÓRIO

#### ➕ Mapear como **Enviado**

Se o status recebido for:

```
READ
DELIVERED
RECEIVED
SENT
ENVIADO
LIDO
RECEBIDO
ENTREGUE
ENVIADOS
```

👉 Status final: **Enviado**
👉 Status original: salvar em **observação**

---

#### ❌ Mapear como **Não Enviado**

Se o status recebido for:

```
ERROR
ERROR 130472
NÃO ENVIADO
NAO ENVIADO
ERRO
FALHA
NUMERO SEM WHATSAPP
```

👉 Status final: **Não Enviado**
👉 Status original: salvar em **observação**

---

## 📝 OBSERVAÇÃO (CAMPO OBRIGATÓRIO)

Sempre que houver normalização:

* O **status original do relatório** deve ser enviado como:

  ```
  observacao: "STATUS ORIGINAL DO RELATÓRIO"
  ```

Mesmo quando o status coincidir.

---

## 🔗 INTEGRAÇÃO COM A API ONSMS

A Plataforma Operacional deve:

* Consumir a API da OnSMS para:

  * Receber campanhas
* Enviar de volta:

  * Status por número
  * Observação
  * ID da campanha
  * Data/hora do processamento

### Requisitos:

* Autenticação conforme API OnSMS
* Envio idempotente
* Retry em caso de falha
* Log de todas as chamadas

---

## 🧠 REGRAS IMPORTANTES

* ❌ Não usar IA para leitura de e-mail ou relatórios
* ❌ Não usar NLP
* ❌ Não inferir dados
* ✅ Tudo deve ser determinístico e auditável
* ✅ Logs claros por campanha
* ✅ Erros não podem “sumir”
* ✅ Uma campanha não pode ser finalizada duas vezes

---

## 🛠️ TECNOLOGIA (sugestão inicial)

Escolha stack simples e madura:

* Backend: Node.js ou Python
* API: REST
* Banco: SQLite (MVP), depois PostgreSQL
* E-mail: IMAP + SMTP
* Armazenamento: filesystem local (MVP)

---

## 🧭 ROADMAP OBRIGATÓRIO

### 🔹 MVP (funcional ponta a ponta)

* Receber campanha via API
* Gerar ZIP
* Enviar e-mail
* Ler e-mail de retorno
* Processar relatório
* Normalizar status
* Enviar status para OnSMS

### 🔹 V1

* Logs
* Idempotência
* Reprocessamento manual
* Validação forte de dados

### 🔹 V2

* Dashboard
* Fila
* Multi-operador
* Alertas

---

## 🚨 LIMITES DE ESCOPO

Qualquer funcionalidade fora do fluxo acima:
👉 **deve ser ignorada ou marcada como futura**

---

## ✅ SUA PRIMEIRA TAREFA (como desenvolvedor)

1. Descrever a arquitetura do MVP
2. Definir os endpoints da Plataforma Operacional
3. Definir o modelo mínimo de banco
4. Definir o fluxo de e-mail
5. Só depois começar a codar

---

## 🧠 MENTALIDADE ESPERADA

Construa como:

* sistema operacional
* previsível
* auditável
* simples
* robusto

Não construa como:

* SaaS genérico
* sistema “inteligente”
* solução mágica