209 lines
10 KiB
Markdown
209 lines
10 KiB
Markdown
# Propósito do Produto — Fazer AI / Chatwoot Fork
|
|
|
|
> Documento vivo. Atualizado em: 2026-02-22
|
|
|
|
---
|
|
|
|
## 1. Propósito Central
|
|
|
|
Este repositório é um fork evolutivo do Chatwoot open-source para se tornar a plataforma de atendimento inteligente do ecossistema Fazer AI.
|
|
|
|
Nosso objetivo é entregar atendimento enterprise com IA nativa, WhatsApp e automações, sem depender de time técnico para ajustes operacionais do dia a dia.
|
|
|
|
---
|
|
|
|
## 2. Princípio Inegociável: Abertura Máxima ao Usuário Final
|
|
|
|
O produto deve sempre priorizar a maior abertura possível para o usuário final.
|
|
|
|
Em termos práticos:
|
|
|
|
- Sempre que for viável, a configuração deve existir no front-end/UI.
|
|
- Regras de negócio não devem ficar chumbadas no código quando puderem ser parametrizadas.
|
|
- Prompt, comportamento do agente, handoff, limites operacionais, integrações e fluxos devem ser gerenciáveis no painel.
|
|
- O backend deve atuar como camada de capacidade e segurança, não como gargalo de configuração.
|
|
|
|
Exceções permitidas:
|
|
|
|
- Segurança, compliance, integridade de dados e restrições de infraestrutura.
|
|
- Casos de performance crítica comprovada.
|
|
|
|
Regra de engenharia:
|
|
|
|
- Se houver dúvida entre hardcode e configuração em UI, escolher configuração em UI.
|
|
- Se um hardcode temporário for necessário, ele deve nascer com plano de migração para UI.
|
|
|
|
---
|
|
|
|
## 3. Visão de Produto
|
|
|
|
> "Toda empresa deve poder ter um atendimento de nível enterprise, com IA, WhatsApp e automações, sem precisar de um time de engenharia dedicado."
|
|
|
|
Público principal: empresas de médio porte (redes de pousadas, clínicas, academias, hotelaria e operações de serviço com alto volume em WhatsApp).
|
|
|
|
Problemas que resolvemos:
|
|
|
|
- Atendimento omnichannel com operação unificada (WhatsApp, email e web).
|
|
- IA capaz de responder, qualificar e executar tarefas reais (reserva, cobrança, consulta).
|
|
- Escalonamento fluido para humano quando necessário.
|
|
- Rastreabilidade total das ações de bot e humano.
|
|
|
|
---
|
|
|
|
## 4. Resultados Esperados do Produto
|
|
|
|
- Reduzir tempo médio de resposta e custo operacional por conversa.
|
|
- Aumentar taxa de resolução com IA sem perder controle humano.
|
|
- Dar autonomia operacional ao cliente final via painel de configuração.
|
|
- Evitar dependência de deploy para alterações de rotina.
|
|
|
|
---
|
|
|
|
## 5. Funcionalidades Implementadas (reference/chatwoot-develop)
|
|
|
|
As funcionalidades abaixo foram desenvolvidas no projeto de referência (`reference/chatwoot-develop`) e precisam ser portadas, adaptadas e melhoradas neste repositório:
|
|
|
|
### 5.1 🤖 Agentes de IA (Captain AI — v2)
|
|
|
|
| Feature | Descrição | Status |
|
|
|---------|-----------|--------|
|
|
| **Captain AI (Jasmine)** | Agente LLM principal que responde conversas automaticamente via WhatsApp | ✅ Implementado no reference |
|
|
| **Sistema de Tools** | Agente executando ferramentas: busca de FAQ, verificação de disponibilidade, consulta de preços, status de suítes | ✅ Implementado no reference |
|
|
| **Handoff para Humano** | IA detecta quando não sabe responder e transfere para agente humano, notificando via webhook | ✅ Implementado no reference |
|
|
| **Prompt Studio** | Interface para editar o prompt do agente em blocos modulares (system, persona, tools) diretamente no painel | ✅ Implementado no reference |
|
|
| **Análise de Imagem** | Agente recebe e processa imagens enviadas pelo cliente via WhatsApp | ✅ Implementado no reference |
|
|
| **Transcrição de Áudio** | Mensagens de áudio são transcritas e processadas pelo agente | ✅ Implementado no reference |
|
|
| **Sub-agentes** | Captain pode invocar agentes especializados (ex: agente de preços, agente de reservas) | ✅ Implementado no reference |
|
|
| **FAQ Lookup Tool** | Tool que busca respostas em base de conhecimento via embeddings | ✅ Implementado no reference |
|
|
| **Response Delay** | Simula tempo de digitação para tornar o bot mais humano | ✅ Implementado no reference |
|
|
|
|
### 5.2 📱 WhatsApp / Wuzapi Integration
|
|
|
|
| Feature | Descrição | Status |
|
|
|---------|-----------|--------|
|
|
| **Canal Wuzapi** | Integração com Wuzapi (WhatsApp não-oficial para dev/teste) | ✅ Parcialmente portado |
|
|
| **Webhook Wuzapi** | Recebimento de mensagens via webhook do Wuzapi | 🔧 Em ajuste |
|
|
| **Envio de Mensagens** | Envio de texto, imagem, arquivo e reações via Wuzapi | ✅ Implementado no reference |
|
|
| **Sync de mensagens enviadas pelo celular** | Mensagens enviadas pelo app do celular aparecem como "Enviadas" no Chatwoot | ✅ Implementado no reference |
|
|
| **QR Code flow** | Tela de escanear QR code ao criar o canal | ✅ Implementado |
|
|
| **Provisioning automático de usuário** | Ao criar o canal, cria automaticamente um usuário no Wuzapi | ✅ Implementado |
|
|
|
|
### 5.3 💳 Pagamentos PIX
|
|
|
|
| Feature | Descrição | Status |
|
|
|---------|-----------|--------|
|
|
| **PIX Stateful** | Fluxo completo de pagamento PIX dentro do chat (geração, polling, confirmação) | ✅ Implementado no reference |
|
|
| **PIX One-tap** | Pagamento PIX com um clique após dados já cadastrados | ✅ Implementado no reference |
|
|
| **PIX Público** | Geração de link de cobrança público sem autenticação | ✅ Implementado no reference |
|
|
|
|
### 5.4 📅 Reservas
|
|
|
|
| Feature | Descrição | Status |
|
|
|---------|-----------|--------|
|
|
| **Reserva via Chat** | Agente de IA cria reservas diretamente na conversa perguntando dados ao cliente | ✅ Implementado no reference |
|
|
| **Checagem de disponibilidade** | Tool que verifica disponibilidade de suítes em datas específicas | ✅ Implementado no reference |
|
|
| **Reserva PIX integrada** | Após confirmar reserva, gera cobrança PIX na mesma conversa | ✅ Implementado no reference |
|
|
| **Filtro por duração** | Filtro de reservas por período de estadia | ✅ Implementado no reference |
|
|
|
|
### 5.5 📊 Campanhas WhatsApp
|
|
|
|
| Feature | Descrição | Status |
|
|
|---------|-----------|--------|
|
|
| **Campanhas em massa** | Disparo de mensagens em lote via WhatsApp | ✅ Implementado no reference |
|
|
| **Rastreamento de cliques** | Captura UTM, referer, IP e geolocalização de links em campanhas | ✅ Implementado no reference |
|
|
| **Métricas de campanha** | Dashboard de cliques, conversões por campanha | ✅ Implementado no reference |
|
|
|
|
### 5.6 🏢 Multi-Unidade (Marcas / Brands)
|
|
|
|
| Feature | Descrição | Status |
|
|
|---------|-----------|--------|
|
|
| **Configuração por Unidade** | Cada inbox/unidade tem seu próprio webhook, prompt, agente e configurações | ✅ Implementado no reference |
|
|
| **Filtro de conversas por Unidade** | Agente/atendente vê apenas as conversas da sua unidade | ✅ Implementado no reference |
|
|
|
|
### 5.7 💬 UX / Interface
|
|
|
|
| Feature | Descrição | Status |
|
|
|---------|-----------|--------|
|
|
| **Atalhos de resposta** | Shortcuts customizados de resposta rápida | ✅ Implementado no reference |
|
|
| **Tradução de UI** | Traduções pt-BR para todas as interfaces novas | ✅ Implementado no reference |
|
|
| **Filtros avançados de conversas** | Filtrar por status, unidade, agente, data | ✅ Implementado no reference |
|
|
|
|
---
|
|
|
|
## 6. Funcionalidades Prioritárias Para Portar
|
|
|
|
> Lista priorizada do que ainda precisa ser implementado neste fork:
|
|
|
|
1. **`IncomingMessageWuzapiService` completo** — Recebimento de mensagens (texto, imagem, áudio, arquivo) corretamente roteado
|
|
2. **Handoff webhook** — Notificação externa quando IA transfere para humano
|
|
3. **Prompt Studio** — Interface de edição de prompts em blocos
|
|
4. **PIX Stateful** — Fluxo de pagamento dentro do chat
|
|
5. **Sub-agentes Captain** — Invoke de agentes especializados
|
|
6. **Campanhas WhatsApp com rastreamento** — Disparo + métricas
|
|
7. **Reservas** — Agente de reservas com disponibilidade e PIX
|
|
|
|
---
|
|
|
|
## 7. Arquitetura de IA
|
|
|
|
```
|
|
Cliente (WhatsApp)
|
|
│
|
|
▼
|
|
Wuzapi Server ──► Webhook ──► Chatwoot
|
|
│
|
|
┌─────────┴──────────┐
|
|
│ Captain AI Agent │
|
|
│ (LLM + Tools) │
|
|
└─────────┬──────────┘
|
|
│
|
|
┌────────────────────┼────────────────────┐
|
|
▼ ▼ ▼
|
|
FAQ Lookup Reservas Tool PIX Tool
|
|
(Embeddings) (Disponibilidade) (Pagamento)
|
|
│ │ │
|
|
└────────────────────┴────────────────────┘
|
|
│
|
|
Handoff se necessário
|
|
│
|
|
▼
|
|
Agente Humano
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Stack Tecnológica
|
|
|
|
| Camada | Tecnologia |
|
|
|--------|-----------|
|
|
| Backend | Ruby on Rails 7.1 |
|
|
| Frontend | Vue 3 + Vite |
|
|
| IA | OpenAI GPT-4.1 / Compatível OpenRouter |
|
|
| WhatsApp | Wuzapi (dev) / Evolution API (prod) |
|
|
| Banco de dados | PostgreSQL |
|
|
| Cache/Jobs | Redis + Sidekiq |
|
|
| Embeddings | pgvector (PostgreSQL) |
|
|
|
|
---
|
|
|
|
## 9. Diretrizes de Produto e Implementação
|
|
|
|
- Toda feature nova deve nascer com o mínimo de parâmetros essenciais expostos no painel.
|
|
- Configurações devem ser legíveis e editáveis por operação, não apenas por engenharia.
|
|
- Defaults podem existir, mas nunca bloquear customização quando ela fizer sentido de negócio.
|
|
- Evitar acoplamento entre comportamento do agente e constantes fixas em arquivo.
|
|
- Antes de fechar uma implementação, responder: "o usuário final consegue ajustar isso pela UI?"
|
|
|
|
---
|
|
|
|
## 10. Referências
|
|
|
|
- Projeto de referência com todas as features implementadas: `reference/chatwoot-develop/`
|
|
- Notas de progresso técnico: `reference/chatwoot-develop/progresso/`
|
|
- Plano de evolução Captain v2: `reference/chatwoot-develop/progresso/plano_evolucao_capitao_v2.md`
|
|
- Arquitetura dos bots: `reference/chatwoot-develop/progresso/arquitetura-bots.md`
|
|
|
|
---
|
|
|
|
*Documento mantido pelo time de arquitetura e produto do Fazer AI.*
|