| # 🤖 AKIRA BOT V21 — ARQUITETURA OOP | |
| ## Visão Geral | |
| **Akira Bot V21** foi completamente refatorado com uma **arquitetura Orientada a Objetos (OOP)** moderna, modular e escalável. O código foi dividido em **6+ classes especializadas**, cada uma com responsabilidade única, totalizando mais de **3000 linhas de código bem organizado**. | |
| ## Estrutura de Diretórios | |
| ``` | |
| /index/ | |
| ├── index.js # Arquivo principal (orquestrador) | |
| ├── index.js.old # Backup da versão anterior | |
| ├── package.json # Dependências | |
| └── modules/ # Pasta com todas as classes | |
| ├── ConfigManager.js # Gerenciamento de configurações | |
| ├── APIClient.js # Cliente HTTP com retry (api.py) | |
| ├── AudioProcessor.js # STT, TTS, efeitos de áudio | |
| ├── MediaProcessor.js # Imagens, vídeos, stickers, YouTube | |
| ├── MessageProcessor.js # Análise de mensagens e contexto | |
| ├── ModerationSystem.js # Moderação: mute, ban, anti-link | |
| └── BotCore.js # Núcleo: Baileys wrapper, event loop | |
| ``` | |
| ## Classes Principais | |
| ### 1. **ConfigManager** (Singleton) | |
| **Arquivo:** `modules/ConfigManager.js` | |
| Gerencia todas as configurações globais do bot. | |
| **Responsabilidades:** | |
| - Leitura de variáveis de ambiente | |
| - Constantes de configuração | |
| - Validação de configurações críticas | |
| - Permissões de dono | |
| **Exemplo de uso:** | |
| ```javascript | |
| const config = ConfigManager.getInstance(); | |
| console.log(config.BOT_NUMERO_REAL); | |
| console.log(config.isDono('244937035662', 'Isaac Quarenta')); | |
| ``` | |
| **Configurações disponíveis:** | |
| ```javascript | |
| PORT, API_URL, API_TIMEOUT, API_RETRY_ATTEMPTS | |
| BOT_NUMERO_REAL, BOT_NAME, BOT_VERSION, PREFIXO | |
| TEMP_FOLDER, AUTH_FOLDER, DATABASE_FOLDER, LOGS_FOLDER | |
| DEEPGRAM_API_KEY, DEEPGRAM_MODEL, STT_LANGUAGE | |
| TTS_LANGUAGE, TTS_SLOW | |
| RATE_LIMIT_WINDOW, RATE_LIMIT_MAX_CALLS | |
| MUTE_DEFAULT_MINUTES, AUTO_BAN_AFTER_MUTES | |
| YT_MAX_SIZE_MB, YT_QUALITY | |
| FEATURE_STT_ENABLED, FEATURE_TTS_ENABLED, etc. | |
| ``` | |
| --- | |
| ### 2. **APIClient** | |
| **Arquivo:** `modules/APIClient.js` | |
| Cliente HTTP para comunicação com api.py com retry automático. | |
| **Responsabilidades:** | |
| - Formatar payloads conforme esperado por api.py | |
| - Requisições HTTP com retry exponencial | |
| - Integração com vision/OCR | |
| - Health checks | |
| **Payload Padrão:** | |
| ```javascript | |
| { | |
| usuario: 'Isaac', | |
| numero: '244937035662', | |
| mensagem: 'Oi, tudo bem?', | |
| tipo_conversa: 'pv', // ou 'grupo' | |
| tipo_mensagem: 'texto', // ou 'audio', 'image', 'video' | |
| mensagem_citada: '', | |
| reply_metadata: { | |
| is_reply: false, | |
| reply_to_bot: false, | |
| quoted_author_name: '', | |
| context_hint: '' | |
| }, | |
| historico: [], | |
| forcar_busca: false, | |
| imagem: { | |
| dados: 'base64...', | |
| mime_type: 'image/jpeg', | |
| descricao: 'Análise de visão' | |
| } | |
| } | |
| ``` | |
| **Exemplo de uso:** | |
| ```javascript | |
| const apiClient = new APIClient(logger); | |
| const payload = apiClient.buildPayload({ | |
| usuario: 'Isaac', | |
| numero: '244937035662', | |
| mensagem: 'Olá' | |
| }); | |
| const resultado = await apiClient.processMessage(payload); | |
| ``` | |
| --- | |
| ### 3. **AudioProcessor** | |
| **Arquivo:** `modules/AudioProcessor.js` | |
| Processa áudio: STT (Deepgram), TTS (Google), efeitos. | |
| **Responsabilidades:** | |
| - Speech-to-Text via Deepgram API | |
| - Text-to-Speech via Google TTS | |
| - Aplicação de efeitos (nightcore, slow, bass, etc.) | |
| - Cache de TTS para performance | |
| - Detecção de tipo de áudio | |
| **Métodos principais:** | |
| ```javascript | |
| speechToText(audioBuffer, language = 'pt') // STT | |
| textToSpeech(text, language = 'pt') // TTS | |
| applyAudioEffect(buffer, effect) // Efeitos: nightcore, slow, bass, treble, echo | |
| detectAudioType(buffer) // Detecta tipo (ogg, mp3, wav, etc) | |
| ``` | |
| **Exemplo:** | |
| ```javascript | |
| const audioProc = new AudioProcessor(logger); | |
| // STT | |
| const transcricao = await audioProc.speechToText(audioBuffer); | |
| console.log(transcricao.texto); // "Olá, como você está?" | |
| // TTS | |
| const tts = await audioProc.textToSpeech('Oi! Tudo bem?'); | |
| await sock.sendMessage(jid, { audio: tts.buffer, ptt: true }); | |
| // Efeito | |
| const nightcore = await audioProc.applyAudioEffect(buffer, 'nightcore'); | |
| ``` | |
| --- | |
| ### 4. **MediaProcessor** | |
| **Arquivo:** `modules/MediaProcessor.js` | |
| Processa mídia: imagens, vídeos, stickers, YouTube. | |
| **Responsabilidades:** | |
| - Download de mídia via Baileys | |
| - Criação de stickers (estáticos e animados) | |
| - Conversão sticker ↔ imagem | |
| - Download de áudio do YouTube | |
| - Busca de músicas | |
| **Métodos principais:** | |
| ```javascript | |
| downloadMedia(message, mimeType) // Download de mídia | |
| bufferToBase64(buffer) // Conversão | |
| createStickerFromImage(imageBuffer) // Sticker de imagem | |
| createAnimatedStickerFromVideo(videoBuffer) // Sticker animado | |
| convertStickerToImage(stickerBuffer) // Converte sticker para PNG | |
| downloadYouTubeAudio(url) // Download de áudio YT | |
| searchYouTube(query, limit) // Busca no YouTube | |
| ``` | |
| **Exemplo:** | |
| ```javascript | |
| const mediaProc = new MediaProcessor(logger); | |
| // Download e criar sticker | |
| const imageBuffer = await mediaProc.downloadMedia(message.imageMessage, 'image'); | |
| const sticker = await mediaProc.createStickerFromImage(imageBuffer); | |
| await sock.sendMessage(jid, { sticker: sticker.buffer }); | |
| // YouTube | |
| const resultado = await mediaProc.downloadYouTubeAudio('https://youtube.com/watch?v=...'); | |
| if (resultado.sucesso) { | |
| await sock.sendMessage(jid, { audio: resultado.buffer }); | |
| } | |
| ``` | |
| --- | |
| ### 5. **MessageProcessor** | |
| **Arquivo:** `modules/MessageProcessor.js` | |
| Análise inteligente de mensagens e contexto. | |
| **Responsabilidades:** | |
| - Extração de texto, número, tipo de conversação | |
| - Detecção de reply e contexto | |
| - Análise de comandos | |
| - Rate limiting | |
| - Sanitização de texto | |
| **Métodos principais:** | |
| ```javascript | |
| extractUserNumber(message) // Número do usuário | |
| extractText(message) // Extrai texto | |
| getConversationType(message) // 'pv' ou 'grupo' | |
| extractReplyInfo(message) // Info de reply | |
| isCommand(text) // É comando? | |
| parseCommand(text) // Parse de comando | |
| isBotMentioned(message) // Bot mencionado? | |
| checkRateLimit(userId) // Verifica rate limit | |
| ``` | |
| **Exemplo:** | |
| ```javascript | |
| const msgProc = new MessageProcessor(logger); | |
| const numero = msgProc.extractUserNumber(message); | |
| const texto = msgProc.extractText(message); | |
| const tipo = msgProc.getConversationType(message); // 'pv' ou 'grupo' | |
| const replyInfo = msgProc.extractReplyInfo(message); | |
| if (replyInfo) { | |
| console.log(replyInfo.textoMensagemCitada); | |
| console.log(replyInfo.ehRespostaAoBot); | |
| } | |
| // Rate limiting | |
| if (!msgProc.checkRateLimit(numero)) { | |
| console.log('Rate limit excedido!'); | |
| } | |
| ``` | |
| --- | |
| ### 6. **ModerationSystem** | |
| **Arquivo:** `modules/ModerationSystem.js` | |
| Sistema avançado de moderação. | |
| **Responsabilidades:** | |
| - Mute com escalação (duplica tempo a cada mute) | |
| - Ban permanente ou temporário | |
| - Anti-link automático | |
| - Anti-spam | |
| - Contadores diários | |
| **Métodos principais:** | |
| ```javascript | |
| muteUser(groupId, userId, minutes) // Muta com escalação | |
| unmuteUser(groupId, userId) // Remove mute | |
| isUserMuted(groupId, userId) // Verifica mute | |
| banUser(userId, reason, expiresIn) // Bane usuário | |
| unbanUser(userId) // Remove ban | |
| isBanned(userId) // Verifica ban | |
| toggleAntiLink(groupId, enable) // Ativa/desativa anti-link | |
| isAntiLinkActive(groupId) // Verifica status | |
| containsLink(text) // Detecta link | |
| checkSpam(userId) // Verifica spam | |
| ``` | |
| **Exemplo:** | |
| ```javascript | |
| const moderation = new ModerationSystem(logger); | |
| // Mute | |
| const muteResult = moderation.muteUser(groupId, userId, 5); | |
| console.log(`Mutado por ${muteResult.minutes} minutos`); | |
| // Anti-link | |
| moderation.toggleAntiLink(groupId, true); | |
| if (moderation.containsLink(texto)) { | |
| // Remove usuário | |
| } | |
| // Ban | |
| moderation.banUser(userId, 'Spam', 24*60*60*1000); // 24h | |
| ``` | |
| --- | |
| ### 7. **BotCore** | |
| **Arquivo:** `modules/BotCore.js` | |
| Núcleo do bot: orquestração, event loop, Baileys wrapper. | |
| **Responsabilidades:** | |
| - Inicialização e conexão com WhatsApp | |
| - Main loop de processamento de mensagens | |
| - Orquestração de todas as classes | |
| - Gestão de estado e QR Code | |
| - Event handling | |
| **Métodos principais:** | |
| ```javascript | |
| initialize() // Inicializa bot | |
| connect() // Conecta ao WhatsApp | |
| getStatus() // Status atual | |
| getStats() // Estatísticas | |
| getQRCode() // QR Code atual | |
| ``` | |
| **Fluxo de processamento:** | |
| ``` | |
| Mensagem recebida | |
| ↓ | |
| Deduplicação (últimos 30s) | |
| ↓ | |
| Verificação de ban/spam | |
| ↓ | |
| Verificação de mute (grupos) | |
| ↓ | |
| Processamento (áudio/texto) | |
| ↓ | |
| Extração de contexto e reply | |
| ↓ | |
| Verificação de rate limit | |
| ↓ | |
| Chamada à API (api.py) | |
| ↓ | |
| STT/TTS se necessário | |
| ↓ | |
| Envio da resposta | |
| ``` | |
| --- | |
| ## Fluxo de Mensagem Detalhado | |
| ### 1. **Mensagem de Texto Recebida** | |
| ``` | |
| handleMessagesUpsert() [BotCore] | |
| ↓ | |
| processMessage() [BotCore] | |
| ├─ extractUserNumber() [MessageProcessor] | |
| ├─ extractText() [MessageProcessor] | |
| ├─ extractReplyInfo() [MessageProcessor] | |
| ├─ checkRateLimit() [MessageProcessor] | |
| ├─ buildPayload() [APIClient] | |
| ├─ processMessage() [APIClient] → POST /akira (api.py) | |
| └─ sendMessage() [BotCore] | |
| ``` | |
| ### 2. **Mensagem de Áudio Recebida** | |
| ``` | |
| handleMessagesUpsert() [BotCore] | |
| ↓ | |
| handleAudioMessage() [BotCore] | |
| ├─ downloadMedia() [MediaProcessor] | |
| ├─ speechToText() [AudioProcessor] → Deepgram API | |
| ├─ [Processa como texto...] | |
| └─ textToSpeech() [AudioProcessor] → Google TTS | |
| └─ sendMessage() com áudio [BotCore] | |
| ``` | |
| ### 3. **Comandos (prefixo #)** | |
| ``` | |
| Exemplo: #sticker | |
| ↓ | |
| isCommand() verifica prefixo | |
| ↓ | |
| parseCommand() extrai comando e args | |
| ↓ | |
| CommandHandler executa lógica | |
| └─ (Futuramente: classe CommandHandler) | |
| ``` | |
| --- | |
| ## Conformidade com api.py | |
| O `APIClient` formata mensagens exatamente como api.py espera: | |
| ### Exemplo: Reply em grupo | |
| ```javascript | |
| // Usuário responde a bot em grupo | |
| const payload = { | |
| usuario: 'Isaac', | |
| numero: '244937035662', | |
| mensagem: 'O que é isso?', // Mensagem ATUAL | |
| tipo_conversa: 'grupo', | |
| tipo_mensagem: 'texto', | |
| mensagem_citada: 'Como posso ajudar?', // Mensagem citada COMPLETA | |
| reply_metadata: { | |
| is_reply: true, | |
| reply_to_bot: true, // Flag BOT_ID | |
| quoted_author_name: 'Akira', | |
| quoted_author_numero: '244937035662', | |
| quoted_type: 'texto', | |
| context_hint: '(Usuário respondendo à mensagem do bot)' | |
| }, | |
| grupo_id: '...', | |
| contexto_grupo: 'Meu Grupo' | |
| } | |
| // api.py recebe: | |
| // - Mensagem atual para responder | |
| // - Mensagem citada para contexto | |
| // - Flag de reply ao bot para lógica especial | |
| ``` | |
| --- | |
| ## Variáveis de Ambiente | |
| ```bash | |
| # Servidor | |
| PORT=3000 | |
| # WhatsApp/API | |
| API_URL=http://localhost:8000/api/akira | |
| BOT_NUMERO=244937035662 | |
| BOT_NAME=Akira | |
| # STT (Deepgram) | |
| DEEPGRAM_API_KEY=seu_token_aqui | |
| DEEPGRAM_MODEL=nova-2 | |
| STT_LANGUAGE=pt | |
| # TTS | |
| TTS_LANGUAGE=pt | |
| TTS_SLOW=false | |
| # YouTube | |
| YT_MAX_SIZE_MB=25 | |
| YT_QUALITY=highestaudio | |
| # Moderação | |
| MUTE_DEFAULT_MINUTES=5 | |
| AUTO_BAN_AFTER_MUTES=3 | |
| # Features | |
| FEATURE_STT=true | |
| FEATURE_TTS=true | |
| FEATURE_YT=true | |
| FEATURE_STICKERS=true | |
| FEATURE_MODERATION=true | |
| FEATURE_VISION=true | |
| ``` | |
| --- | |
| ## Endpoints HTTP | |
| ### GET `/` | |
| Página de status do bot | |
| ### GET `/qr` | |
| QR Code para conectar | |
| ### GET `/health` | |
| Health check | |
| ### GET `/stats` | |
| Estatísticas detalhadas | |
| ### POST `/reset-cache` | |
| Limpa todos os caches | |
| ### POST `/moderation/toggle-antilink` | |
| ```json | |
| { | |
| "groupId": "120363...", | |
| "enable": true | |
| } | |
| ``` | |
| --- | |
| ## Padrões de Design Utilizados | |
| 1. **Singleton** (ConfigManager) | |
| - Uma única instância globalmente acessível | |
| 2. **Factory** (APIClient, AudioProcessor) | |
| - Cria instâncias com injeção de logger | |
| 3. **Observer** (BotCore com events) | |
| - Event-driven para Baileys | |
| 4. **Strategy** (AudioProcessor com efeitos) | |
| - Diferentes estratégias para processamento de áudio | |
| 5. **Cache** (TTLCache em APIClient) | |
| - Cache com expiração automática | |
| --- | |
| ## Performance e Otimizações | |
| ### Cache | |
| - **STT Cache**: Evita re-transcrever mesmo áudio | |
| - **TTS Cache**: Reutiliza áudios gerados | |
| - **Media Cache**: Evita re-download | |
| ### Deduplicação | |
| - Mensagens duplicadas ignoradas (30s) | |
| - Impede processamento duplo em case de retry | |
| ### Rate Limiting | |
| - Máximo 6 requisições por 8 segundos | |
| - Proteção contra spam de comandos | |
| ### Conexão com api.py | |
| - Retry automático (até 3 tentativas) | |
| - Backoff exponencial (1s, 2s, 4s) | |
| - Timeout de 120s | |
| ### Limpeza de Memória | |
| - Maps de mute/ban auto-limpam expirados | |
| - Cache de mensagens com limite máximo | |
| - Spam cache com limite de 1000 entradas | |
| --- | |
| ## Exemplos de Uso | |
| ### Iniciar o bot | |
| ```bash | |
| cd /home/elliot_pro/Programação/akira/index | |
| node index.js | |
| ``` | |
| ### Acessar status | |
| ```bash | |
| curl http://localhost:3000/health | jq | |
| ``` | |
| ### Resetar caches | |
| ```bash | |
| curl -X POST http://localhost:3000/reset-cache | |
| ``` | |
| ### Ativar anti-link em grupo | |
| ```bash | |
| curl -X POST http://localhost:3000/moderation/toggle-antilink \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"groupId": "120363...", "enable": true}' | |
| ``` | |
| --- | |
| ## Escalabilidade Futura | |
| ### Classe CommandHandler (planejada) | |
| ```javascript | |
| class CommandHandler { | |
| registerCommand(name, handler, options = {}) | |
| executeCommand(comando, args, message) | |
| // Centralize todos os comandos (#sticker, #play, etc) | |
| } | |
| ``` | |
| ### Classe DatabaseManager (planejada) | |
| ```javascript | |
| class DatabaseManager { | |
| saveUserData(userId, data) | |
| getUserData(userId) | |
| // Persistência de dados de usuários | |
| } | |
| ``` | |
| ### Classe LevelingSystem (planejada) | |
| ```javascript | |
| class LevelingSystem { | |
| addXP(userId, amount) | |
| checkLevelUp(userId) | |
| // Sistema de leveling e patentes | |
| } | |
| ``` | |
| --- | |
| ## Dependências Principais | |
| ```json | |
| { | |
| "@whiskeysockets/baileys": "^6.0.0", | |
| "express": "^4.18.0", | |
| "axios": "^1.6.0", | |
| "pino": "^8.0.0", | |
| "qrcode": "^1.5.0", | |
| "ffmpeg-fluent": "^2.1.2", | |
| "google-tts-api": "^2.0.2", | |
| "@distube/ytdl-core": "^4.11.5", | |
| "yt-search": "^2.10.0" | |
| } | |
| ``` | |
| --- | |
| ## Próximos Passos | |
| 1. ✅ Arquitetura OOP completa | |
| 2. ✅ Integração com api.py | |
| 3. ✅ STT/TTS funcional | |
| 4. ⏳ CommandHandler centralizado | |
| 5. ⏳ DatabaseManager para persistência | |
| 6. ⏳ LevelingSystem (XP, patentes) | |
| 7. ⏳ Dashboard web | |
| --- | |
| **Versão:** 21.02.2025 | |
| **Arquitetura:** OOP com 6+ classes especializadas | |
| **Status:** Pronto para produção | |
| **Linha de código:** ~3000+ linhas bem organizadas | |