a # Chatc2 - Contexto do Projeto

_Arquivo gerado em 05/06/2026 para retomada em qualquer computador._

---

## 📋 Missão Atual

Plataforma multi-empresa de atendimento com WhatsApp (Evolution API) + Firebase Firebird, incluindo:
- Chat com atendimento humano e triagem automatizada
- Geração de boletos em PDF via API externa
- Transcrição de áudio com Whisper.cpp (local)
- Fluxo de atendimento personalizado por empresa (submenus, etiquetas)
- Breve: integração com Asterisk para ligações telefônicas

---

## 🗂️ Estrutura de Arquivos (49 arquivos)

```
src/
├── app.js                          # Express app setup
├── server.js                       # Entry point (porta 3000)
├── database.js                     # Conexão Firebird (query, execute, readBlob)
├── config/
│   ├── databases.js                # Conexões estáticas + custom (JSON)
│   ├── databases_custom.json       # Conexões adicionadas via API
│   ├── database.js                 # Config padrão do banco
│   └── auth.js                     # JWT secret/expires
├── middlewares/
│   └── auth.js                     # JWT + USU_TOKEN dual auth
├── controllers/
│   ├── authController.js           # Login, /me, dashboard
│   ├── chatController.js           # Conversas, mensagens, mídia, Evolution send
│   ├── clientController.js         # CRUD clientes, carnês, dependentes, convalescentes, listcarne
│   ├── configController.js         # Config empresa, equipes, etiquetas, instâncias
│   ├── evolutionController.js      # Webhook Evolution, QR Code, instâncias
│   ├── genericController.js        # Health, tables, query, aliases
│   ├── menuController.js           # CRUD CHATC2_MENUS_EMPRESA (submenus do fluxo)
│   ├── triageController.js         # Fluxo de triagem (sendMenu, processResponse, boleto)
│   ├── databaseController.js       # CRUD de conexões de banco (custom JSON)
│   ├── routesController.js         # Descoberta automática de rotas
│   ├── empresaController.js        # Logo da empresa
│   └── transcriber.js              # Whisper.cpp para transcrição de áudio
├── routes/
│   ├── index.js                    # Agregador de rotas
│   ├── authRoutes.js, chatRoutes.js, configRoutes.js
│   ├── genericRoutes.js, menuRoutes.js, databaseRoutes.js
└── public/
    ├── login.html, dashboard.html, chat.html, client-list.html
    ├── client-detail.html, settings.html, routes.html
    ├── admin-conversations.html, csat.html
    ├── css/dark-mode.css, css/main.css
    └── js/dark-mode.js
scripts/
├── migracoes.js                 # 19 migrações de banco (controle via CHATC2_CONTROLE_MIGRACOES)
├── criar_tabelas_chat.js        # Script original de criação de tabelas
├── gerar-token-jwt.js, gerar-token-usuario.js
├── habilitar-acesso-web.js, definir-senha-web.js
└── listar-tokens.js
deploy/
├── cloud-init.yml               # Deploy automático Ubuntu 22.04
├── setup.sh                     # Instalação manual
└── README_INSTALACAO.md         # Guia completo
```

---

## 🔥 Principais Funcionalidades Implementadas

### 1. Autenticação
- JWT + USU_TOKEN (dual auth)
- Login com USU_LOGIN + USU_SENHA (ou USU_SENHA_WEB)
- Roles: Agente (A) e Gerente/Admin (G) via USU_TIPO_CHAT
- `/app/:alias/me` retorna dados do usuário

### 2. Webhook Evolution API (v2.3.7)
- URL: `POST /api/webhook/evolution` (sem alias na URL)
- Detecta alias automaticamente pelo nome da instância
- Cria conversas novas ou reusa existentes (últimos 8 dígitos)
- Busca cliente por telefone (CLI_CELULAR, CLI_FONE1, CLI_FONE2, DEPENDENTES_CLI)
- Sempre corrige CON_CLIENTE_ID pelo telefone (novas + existentes)
- Mídia: tenta download via URL, depois /chat/getMedia/, depois base64 embutido

### 3. Chat (Tempo Real)
- Sidebar: Minhas / Sem Atendimento / Equipe / Todas (com contagens)
- Painel central com mensagens
- Painel direito: atendente, equipe, etiquetas
- Envio de texto, imagem, áudio (MediaRecorder → base64), documento
- Prévia do áudio antes de enviar
- Transcrição de áudio via Whisper.cpp (exibida abaixo do player)

### 4. Triagem / Fluxo Automático
- Menu principal = Equipes (ordenadas por EQU_ORDEM) + Boleto (fixo)
- **Ao escolher equipe: CON_EQUIPE_ID atribuído IMEDIATAMENTE**
- Submenus via CHATC2_MENUS_EMPRESA (M=submenu, T=texto, R=rota)
- Navegação multi-nível com "0 - Voltar"
- Etiquetas associadas a cada submenu (adicionadas automaticamente)
- Boleto: lista títulos → seleciona → gera PDF via API externa → envia via Evolution → pergunta "continuar?"

### 5. Boleto
- Geração: `POST https://cobpagweb.com.br/boleto/cliente/index.php?base64`
- Payload: `{ empresa: {EMP_NOME, EMP_CNPJ, EMP_FOTO}, Cliente: {...}, Carnes: [...] }`
- Envio Evolution: `/message/sendMedia/` com `mediatype: 'document'`
- Fallback: texto com dados do boleto quando PDF não gerado
- Nome do arquivo: `<MATRICULA> - <VENCIMENTO>.pdf`

### 6. Whisper.cpp (Transcrição de Áudio)
- Instalado em `whisper/` (main.exe/main + modelo tiny)
- Transcreve áudios recebidos via webhook
- Salva transcrição em `MAT_TRANSCRICAO` (BLOB SUB_TYPE TEXT)
- Exibe no chat: player + transcrição abaixo
- **Limitação: Evolution API v2.3.7 não fornece áudio válido para download**
  - Funcionará quando atualizar a Evolution API (> v2.5.0)

### 7. Settings (Configurações)
- Abas: Equipe, Fluxo, Empresa, Etiquetas, Conexão
- Fluxo: CRUD de submenus por equipe (árvore), com tipos e etiquetas
- Empresa: saudação, triagem, CSAT, foto, nome do usuário
- Etiquetas: nome + cor
- Conexão: instâncias WhatsApp (criar, editar, QR Code)

### 8. Banco de Dados (Migrações)
- Script: `scripts/migracoes.js` — 19 migrações
- Tabelas: CHATC2_INSTANCIAS, CHATC2_EQUIPES, CHATC2_USU_EQUIPES, CHATC2_ETIQUETAS
- CHATC2_CONVERSAS, CHATC2_CONVERSAS_MENSAGENS, CHATC2_MENSAGENS_ATENDIMENTOS
- CHATC2_CONVERSAS_ETIQUETAS, CHATC2_CSAT_AVALIACOES, CHATC2_CONFIGURACOES_EMPRESA
- CHATC2_MENUS_EMPRESA (com MNE_ACAO_ROTA, MNE_ETIQUETA_IDS)
- Controle via `CHATC2_CONTROLE_MIGRACOES` (cada migração roda uma vez)

---

## 🎯 Próximos Passos (quando retomar)

1. **Aguardar**: Usuário vai contratar SIP Trunk e instalar Asterisk
2. **Implementar**: Módulo Voice (AMI) para fazer ligações + transcrição
3. **Atualizar**: Evolution API (> v2.5.0) para download de mídia funcionar
4. **Corrigir pendências da conversa**:
   - Etiquetas em submenus (não estava persistindo - adicionar logs `[Menu]` no console)
   - Transcrição só funciona para áudio do agente (aguardando Evolution atualizar)

---

## 🔗 URLs Importantes

| Recurso | URL |
|---------|-----|
| Login | `/app/:alias/login` |
| Chat | `/app/:alias/company/:empresaId/conversation/:conversaId` |
| Clientes | `/app/:alias/clients` |
| Settings | `/app/:alias/settings` |
| Rotas | `/app/:alias/routes` |
| CSAT | `/app/:alias/csat` |
| Webhook | `POST /api/webhook/evolution` |
| Rotas API | `GET /api/routes` |
| Bancos | `GET /api/:alias/databases` |
| Carnê | `GET /api/:alias/clients/:id/listcarne` |
| Convalescentes | `GET /api/:alias/clients/:id/convalescentes` |

## 🔑 Testes

| Usuário | Senha | Base | Tipo |
|---------|-------|------|------|
| SUPORTE | 123456 | lajedo | Admin (G) |
| SUPORTE | 123456 | novo_local | Admin (G) |

## ☁️ Deploy

Arquivos em `deploy/`:
- `cloud-init.yml` — cloud-init (DigitalOcean, Vultr, etc.)
- `setup.sh` — instalação manual
- `README_INSTALACAO.md` — guia completo

## 📦 Backup

`ponto_1/` contém snapshot completo do código fonte.