clube67_newwhats.local/clube67/newwhats.local/md/instrucoes.md

### Role: Arquiteto de Software SaaS Sênior & Especialista em Sistemas de Agentes (Temporal.io)
### Task: Arquitetar um SaaS de Mensageria Omnichannel e Atendimento Corporativo com Orquestração Durável

**Contexto & Ambiente de Trabalho:**
O sistema legado (backend antigo) localizado em `whatsapp.local` deve ser estritamente ignorado.
O nosso workspace atual está em `/home/deploy/projetos/newwhats.local`. 
- **Backend:** Deve ser construído COMPLETAMENTE DO ZERO.
- **Frontend:** O layout visual (Tailwind/Componentes) já está APROVADO na pasta `frontend`. Você deve LIMPAR a lógica antiga (estados, chamadas de API soltas) e plugar a nova inteligência do zero usando Zustand, Sockets e integração com o novo backend, respeitando a interface existente.
O sistema é um CRM robusto, White-Label e genérico, projetado para alta demanda corporativa.

---

### 1. Padrões de Código, Infraestrutura e Qualidade (NÍVEL PRODUÇÃO)
- **Zero Dados Mockados:** É ESTRITAMENTE PROIBIDO o uso de dados mockados. Todo componente React e serviço Node.js deve consumir dados reais do PostgreSQL/DragonflyDB via Zustand/Sockets ou chamadas de API reais.
- **Zero Gambiarras (No Hacky Solutions):** O código não deve ser fragmentado. Use injeção de dependência, Repository Pattern para acesso ao banco, operações atômicas (como `upsert` no Prisma) e separe claramente as responsabilidades.
- **Uso Estrito da Documentação Anexa (Baileys):** O LLM DEVE basear a implementação da biblioteca do WhatsApp na documentação anexa (`baileys_api_docs.md`). 
- **Infraestrutura Local (Bare-Metal):** Desenvolvimento inicial sem Docker. Conexões com PostgreSQL, DragonflyDB, NATS e Temporal.io parametrizadas via variáveis de ambiente (`.env`).
- **Tratamento de Mídia:** O download de buffers da Baileys deve ser assíncrono e salvo corretamente (sem travar o event loop) antes da entrega ao frontend.

### 2. Regras de Interatividade e Workflow de Execução
- **Lista de Tarefas (Checklist):** Antes de gerar qualquer linha de código ou explicação técnica, você (LLM) DEVE iniciar sua resposta com um Checklist visível contendo todos os entregáveis da fase atual. À medida que for entregando cada bloco, você deve atualizar o checklist marcando o item como concluído (ex: `[x] Item concluído`, `[ ] Item pendente`).
- **Instrução de Parada (PAUSA PARA QR CODE):** O primeiro passo prático é estabelecer a sessão. Quando você terminar de gerar os artefatos da Fase 1 (onde o QR Code é emitido), **VOCÊ DEVE PARAR IMEDIATAMENTE DE GERAR A RESPOSTA.**
- **Mensagem Exigida:** Pare e exiba exatamente esta mensagem: *"⏳ **Aguardando escaneamento:** A estrutura de conexão do WhatsApp foi gerada. Por favor, configure o `.env`, rode este módulo inicial, escaneie o QR Code com seu aparelho e me avise aqui digitando 'Escaneado!' para prosseguirmos com Temporal, NATS e React."*
- **Atenção:** Não gere entregáveis da Fase 2 até que eu confirme o escaneamento.

---

### 3. Stack Tecnológica Definitiva
- **Backend Core:** Node.js (TypeScript) com arquitetura modular.
- **Banco de Dados Relacional:** **PostgreSQL** (Prisma ORM).
- **Cache & Sessão Rápida:** **DragonflyDB**.
- **Transporte de Mensagens:** **NATS JetStream**.
- **Orquestração de Agentes:** **Temporal.io**.
- **Frontend:** React, Vite, **Tailwind CSS**, Zustand, Immer.
- **WhatsApp Engine:** Baileys (v6+ Multi-device).
- **IA & Voz:** OpenAI (GPT-4o/Whisper) & Gemini (1.5 Flash para Micro-prompts).

---

### 4. RBAC, Estrutura Organizacional & Regras de Negócio
- **Hierarquia e Tenants:** Tabela principal DEVE ser `users` (plural). Hierarquia: `admin` (Dono do SaaS) e `user` (Tenant/Cliente).
- **Gestão Corporativa (Dentro do Tenant):** Gerenciamento dinâmico de **Setores** e **Cargos**.
- **Operação de Atendimento:** Agrupamento de funcionários em **Equipes de Atendimento**. Todo novo atendimento deve gerar um **Número de Protocolo** rastreável.
- **Sincronização de Contatos:** Regra de ouro para o upsert: priorizar o nome salvo na agenda (`name`), usar o nome verificado (`verifiedName`) ou o pushname (`notify`) como fallback. Chave única no Prisma para impedir duplicações (`@@unique([tenantId, instanceId, jid])`).

---

### 5. O Cérebro IA Multi-Agente & Orquestração (Temporal.io)

A IA não deve consumir o histórico completo de chat para economizar tokens. Usaremos **State Machine (Stateful Memory)** via Temporal.io:

**A. Cadeia de Decisão por Micro-Prompts (Low Token Consumption)**
- **Agente Receptor:** Identifica a intenção via Webhook/Baileys.
- **Agente de Dados:** Consulta o PostgreSQL/CRM via Activities do Temporal para verificar disponibilidade e contexto (`reply_to_id`).
- **Agente Analista:** Usa LLMs leves (Gemini Flash) forçados a retornar apenas 1 token (ex: 1 para "Escalar", 2 para "Resolver").
- **Stateful Memory (Cérebro):** O Temporal mantém um resumo ativo de 2 frases e o status da negociação. Mensagens que marcam (`reply`) enviam apenas o par [Mensagem Marcada + Pergunta Atual].

**B. Lógicas Críticas de Negócio (Workflows)**
- **Conflito de 1 Hora (Pessoa A vs B):** Se A pede o horário de B (pendente), o Temporal marca como `WAITING_B` e executa um `await workflow.sleep('1 hour')`. Sem resposta de B, a agenda é liberada automaticamente para A via NATS.
- **Gestão de Reputação:** Contatos possuem um `score_reputacao` (0-100) e uma `flag_restricao`.
- **Agente de Conformidade:** Faltas sucessivas reduzem o score. Se ficar RESTRITO, o workflow bloqueia agendamentos automáticos.

---

### 6. UX/UI da Inbox: INTEGRAÇÃO COM LAYOUT APROVADO
Como o layout (Clone do WA Web em Tailwind) já está aprovado, sua tarefa no frontend é **plugar a inteligência**:
- **Sidebar (Esquerda):** Conectar a lista scrollável ao Zustand para renderizar dinamicamente: Foto, Nome, Horário, Snippet (com ícones de Check ✓✓), Badge de `unread_count` e Número do Protocolo.
- **Área Principal (Direita):**
  - **Empty State:** Manter o layout, mas tornar o **Banner SaaS** dinâmico (ex: ler dias restantes do backend).
  - **Chat Ativo:** Plugar o map de mensagens do Zustand para renderizar balões (`fromMe`). Ligar o Footer Fixo (input) aos eventos de emissão do Socket.IO.
- **Proxy:** Consumir a rota `/api/inbox/avatar/:jid` para as fotos de perfil.

---

### 7. Entregáveis Solicitados (Fase 1 - Imediato)
*(Lembre-se da Regra 2: Crie o Checklist primeiro e marque os itens ao entregar)*
1. **Infra e Arquitetura:**
   - Estrutura de Diretórios lógica para `/home/deploy/projetos/newwhats.local/backend`.
   - Exemplo de arquivo `.env`.
2. **Schema do Prisma Atualizado:** Estrutura relacional normalizada: `users`, `sectors`, `teams`, `protocols` (ID, Status, Resumo, Deadline), `contacts` (com `score_reputacao` e `flag_restricao`), `instances`, `chats`, `messages` (com `reply_to_id`), `plans`, `api_keys`.
3. **Módulo Baileys + DragonflyDB:** O código profissional inicial do backend necessário para emitir o QR Code real e validar a conexão no terminal. **(Consulte o arquivo `baileys_api_docs.md` em anexo)**.
4. *(Pare a geração e exiba a mensagem de pausa da Regra 2).*

### 8. Entregáveis Solicitados (Fase 2 - Pós QR Code)
1. Códigos do Temporal.io: Workflow implementando a regra do "Conflito de 1 Hora" e a "Gestão de Reputação".
2. Implementação do Upsert de Contatos e WhatsApp Warmer no backend.
3. ChatStore (Zustand) com Immer e os Snippets de como conectar essa store aos componentes React existentes do layout aprovado.