instrucoes_gerais/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.