Bot Dashboard — Documentação Técnica

1. Arquitetura do Sistema

O Bot Dashboard é uma plataforma SaaS multi-tenant onde cada usuário (conta dashboard) possui um ou mais bots Telegram. A dashboard PHP permite configurar fluxos de conversa, produtos digitais, gateways de pagamento, estratégias de vendas, clientes, campanhas em massa e analytics. O runtime Go (externo a este repositório) executa as interações Telegram em tempo real lendo/escrevendo o mesmo banco MySQL.

Nossos numeros:

Identificadores

2. Stack Tecnológica

3. Configuração (config/config.php)

Timezone: America/Sao_Paulo

Esquemas de cor UI: purple, blue, green, rose, orange, teal (COLOR_SCHEMES)

4. Sistema de Idiomas — 17 Idiomas

Definidos em SUPPORTED_LANGUAGES (config/config.php). Cada idioma possui arquivo lang/{codigo}.php com ~796 chaves de tradução sincronizadas via tools/sync_lang.php.

Arquivos extras de tradução (patches por módulo)

lang/extras.php, currency_extras.php, presentation_extras.php, bot_select_extras.php, config_tab_extras.php, config_create_bot_extras.php, flow_extras.php, product_extras.php, gateway_extras.php, strategy_extras.php, client_extras.php, mass_extras.php, stats_extras.php, button_extras.php, coupon_extras.php, affiliate_extras.php, coproducer_extras.php, bot_language_extras.php, config_bot_edit_extras.php, payment_extras.php, notification_extras.php, advanced_extras.php, support_extras.php

Função de tradução

function __(string $key, array $replacements = []): string
// Carrega lang/en.php + lang/{getCurrentLanguage()}.php
// Placeholders: __('clients_total_count', ['count' => 42]) → ":count clientes"

5. Moedas Suportadas — 18 Moedas

Constante SUPPORTED_CURRENCIES. Cada moeda inclui: name, symbol, decimal separator, thousands separator, position (before/after).

Hierarquia: products.currency → bots.currency → users.bot_currency / users.dashboard_currency

6. Gateways de Pagamento — 11 Providers

Tabela: payment_gateways. Um registro por provider por usuário. Status: active | inactive.

Redes crypto (getCryptoNetworks())

btc, eth, bsc, usdt

Tipos chave Pix (getPixKeyTypes())

email, phone, cpf, cnpj, random

Regras de negócio gateways

• Fallback: se gateway primário falhar, usar config.fallback_provider (deve estar configurado e ≠ self)
• Pix manual e Cripto usam credencial customizada (não api_key tradicional)
• Chave API mascarada na UI via maskGatewayApiKey()
• Só gateways active com credencial preenchida aparecem no nó payment do fluxo
• API JSON: api/gateways.php — GET lista, POST salva configuração

Métodos de pagamento (filtro menu Pagamentos)

pix, credit_card, debit_card, boleto, crypto, paypal, stripe, mercado_pago, pushinpay, manual, other

7. Schema MySQL — Todas as Tabelas

Banco: bot_dashboard. Schema base: database/schema.sql. Migrations runtime em includes/*.php via ensure*Schema().

7.1 users

Contas dashboard. Campos: id, name, email (unique), password (bcrypt), role (user|admin), avatar, theme (light|dark), color_scheme, language, bot_currency, dashboard_currency, status (active|inactive|banned), email_verified_at, last_login_at, timestamps.

7.2 dashboard_settings

Config global admin: site_name, logos, cores, support_email, etc. Chave-valor com setting_type (text|image|color|json|boolean).

7.3 bots ⭐

Entidade central do runtime. Campos: user_id, name, description, platform (telegram default), bot_token, status (active|inactive|paused), language (17 códigos), currency, welcome_message, presentation_media_type (text|image|video), presentation_media (path), avatar, total_clients, total_revenue, timestamps.

7.4 products

Campos base + migrations: access_type (lifetime|subscription), subscription_days, content_type (image|video|audio|document), content_path/size/mime, delivery_mode (file|link|vip_group), delivery_link, vip_group_id (formato -100...), vip_link_type (unique|custom), vip_custom_link, bot_id (NULL=todos bots), status (active|inactive|draft), sales_count.

7.5 clients

platform_user_id (Telegram ID), platform, status (active|inactive|blocked|expired), total_spent, access_expires_at (assinaturas), last_interaction_at, bot_id, user_id.

7.6 client_messages

Fila mensagens manuais dashboard→cliente. status: pending|sent|failed.

7.7 payments

amount, currency, status (pending|completed|expired), payment_method, gateway, transaction_id, metadata (JSON), paid_at. FK: client_id, product_id, bot_id, user_id.

7.8 payment_gateways

provider, api_key, api_secret, webhook_url, status, config JSON.

7.9 strategies

UNIQUE (user_id, type). type: upsell|remarketing|downsell. bot_id, product_id, message, delay_minutes, status, trigger_event, config JSON.

7.10 conversation_flows

bot_id (CASCADE), name, flow_data JSON, status (draft|active|inactive).

7.11 bot_flow_media

bot_id, name, media_type (image|video|document|audio), file_path, file_size, mime_type. Max 10/bot.

7.12 mass_messages

title, message, bot_id, media_type (text|photo|video), media_path, target_filter JSON, scheduled_at, repeat_daily, repeat_time, status (draft|scheduled|sending|sent|failed), total_recipients, total_sent.

7.13 bot_buttons

label, action_type (telegram|url), action_value, position_slot (first|last), position, status, bot_id.

7.14 coupons

code (UNIQUE user+code), discount_type (percentage|fixed), discount_value (max 91%), max_uses, used_count, valid_from/until, status (active|inactive|expired).

7.15 affiliates + affiliate_settings

affiliates: referral_code (UNIQUE global), commission_rate, total_earnings, total_referrals, status. affiliate_settings: enabled, default_commission_rate, payout_gateway (stripe|pushinpay).

7.16 co_producers

bot_id (NULL=todos), product_id, name, email, commission_rate, payout_gateway, gateway_data, status.

7.17 notifications

title, message, type (info|success|warning|error|payment|client), is_read, link. Paginação 25/página.

7.18 support_tickets

subject, message, status (open|in_progress|resolved|closed), priority (low|medium|high|urgent), admin_reply, replied_at.

7.19 bot_analytics_events

event_type (start|abandon|recovery|purchase), flow_step, flow_step_label, product_id, social_source, client_id, bot_id, user_id.

7.20 daily_stats

Cache diário: stat_date, bots_count, clients_count, revenue, sales_count, new_clients, social_reach. UNIQUE (user_id, stat_date).

7.21 user_sessions

session_token, ip_address, user_agent, expires_at — autenticação dashboard.

8. Rotas da Dashboard

Padrão URL: {APP_URL}/dashboard/index.php?page={page}&tab={tab}

Parâmetros query comuns: bot_id, period, edit, saved, error, reason, msg, p, per_page, name, status, product_id, payment_method, date_from, date_to

9. Ações POST (dashboard/index.php)

10. APIs REST/JSON

11. Menu: Home 🏠

page=home — Página inicial pós-login. Sem abas.

Funcionalidades

• Banner boas-vindas com nome do usuário
• Cards estatísticos via getDashboardStats(): bots, produtos, receita (users se admin)
• Atalhos rápidos: criar bot, personalizar, fluxo, produtos
• Lista bots recentes do usuário

Tabelas: bots, products, payments (agregação receita), users (admin)

12. Menu: Personalizar 🎨

page=personalizar tab=apresentacao

Propósito: Configurar primeira impressão do bot — mensagem de boas-vindas e mídia de apresentação exibida no /start do Telegram.

Campos configuráveis

• Seletor de bot (bot_id)
• Mensagem de boas-vindas (bots.welcome_message)
• Tipo mídia: text | image | video (presentation_media_type)
• Upload mídia → uploads/presentation/{user_id}/{bot_id}/

Regras

• Imagem max 5MB (jpeg, png, gif, webp)
• Vídeo max 50MB, duração max 30 segundos
• Tipo text remove mídia existente

Go runtime

No /start: enviar welcome_message + foto/vídeo se configurado. Upsert client. Registrar analytics start.

Funções: getBotPresentationPayload, saveBotPresentation, uploadPresentationMedia, getPresentationMediaUrl, validatePresentationVideoDuration

13. Menu: Fluxo de Conversa 💬

page=fluxo

13.1 Aba: Editor Visual tab=editor_visual

Editor drag-and-drop de nós do fluxo. Toolbar: message, button, media, question, product, payment. Seletor bot_id obrigatório.

Salva JSON em conversation_flows.flow_data. Status forçado active ao salvar.

13.2 Aba: Mídias tab=midias

Galeria de mídias do bot (max 10). Tipos: image, video, document, audio. Listagem com preview, tamanho, ação excluir.

13.3 Aba: Adicionar Mídia tab=adicionar_midia

Form upload: nome, tipo, arquivo. Paths: uploads/flow/{user_id}/{bot_id}/

Tipos de nó flow_data

Funções: getBotConversationFlow, saveBotConversationFlow, normalizeFlowData, getBotFlowPayload, uploadBotFlowMedia, deleteBotFlowMedia, getUserProductsForFlow, getUserGatewaysForFlow

14. Menu: Produtos 📦

page=produtos

14.1 Aba: Todos tab=todos

Lista produtos com: nome, preço, tipo acesso, entrega, vendas, status. Ações: editar, pausar/ativar, excluir.

14.2 Aba: Criar tab=criar

Formulário completo + edit via &edit={id}

Produto usado em fluxo não pode ser pausado/excluído (isProductUsedInAnyFlow).

Go pós-pagamento: entregar file/link/VIP; subscription → access_expires_at; incrementar sales_count, total_spent, total_revenue.

15. Menu: Gateways 💳

page=gateways tab=pagamento

Grid de 11 gateways com modal configuração. Campos: api_key/wallet/pix_key, status active/inactive, fallback provider, crypto network, pix key type.

JS: assets/js/gateways.js. API: api/gateways.php.

Ver seção 6. Gateways para lista completa providers.

16. Menu: Estratégias 🎯

page=estrategias — Cada aba = um tipo (max 1 registro por tipo/user).

Go: Worker com delay_minutes após evento. Enviar message + oferta product_id.

17. Menu: Clientes 👥

page=clientes tab=lista

Filtros: nome/email/telefone, status, bot_id. Paginação 10/25/50/100.

Status: active, inactive, blocked, expired.

Ações: editar (modal), banir → blocked, enviar mensagem → client_messages pending.

Go: upsert clients; processar pending messages; respeitar blocked; expirar assinaturas.

18. Menu: Mensagem em Massa 📢

page=massa

18.1 Aba: Mensagens tab=mensagens

Histórico campanhas com status, agendamento, contadores enviados.

18.2 Aba: Enviar tab=enviar

Form: título, mensagem, bot_id, mídia opcional (text|photo|video), scheduled_at, repeat_daily + repeat_time.

Regra: só cria nova se última campanha status=sent.

Go cron: broadcast clientes do bot_id quando scheduled_at ≤ now.

19. Menu: Estatísticas 📊

page=estatisticas

Filtros globais: bot_id (todos ou específico), period (today|yesterday|7_days|30_days).

Social sources: telegram, instagram, facebook, whatsapp, direct, other.

Event types: start, abandon, recovery, purchase.

Visualização: gráficos donut (pie chart) via renderStatisticsPieChart().

20. Menu: Botões 🔘

page=botoes

20.1 Lista tab=lista

Tabela botões filtrados por bot_id. Colunas: label, ação, posição, status.

20.2 Criar tab=criar

label, action_type (telegram|url), action_value, position_slot (first|last), bot_id.

Telegram: username sem @ min 3 chars. URL: deve ser URL válida.

Go: Anexar botões ativos ao teclado — first=linha superior, last=linha inferior.

21. Menu: Cupom 🎟️

page=cupom

21.1 Lista tab=lista

Código, desconto %, usos, validade, status. Ações: editar, pausar, excluir.

21.2 Criar tab=criar

code (uppercase A-Z0-9_-), discount_value (max 91%), max_uses (NULL=ilimitado).

Go checkout: validar código, status active, usos, aplicar desconto, increment used_count.

22. Menu: Afiliados 🤝

page=afiliados

22.1 Sistema tab=sistema

Stats: total afiliados, comissões pagas, referrals. Lista paginada com filtros nome, sort (name|referrals|earnings), per_page.

Modal editar commission_rate por afiliado.

22.2 Configurações tab=configuracoes

enabled (liga/desliga), default_commission_rate (max 100%), payout_gateway (stripe|pushinpay).

Go: Deep link /start ref_{code}. Calcular comissão em vendas se enabled.

23. Menu: Co-Produtor 👨‍💼

page=coprodutor

23.1 Lista tab=lista

Co-produtores com escopo bot, comissão, gateway payout, status.

23.2 Adicionar tab=add_coproducer

name, email, bot_scope (all|specific bot), commission_rate (0-100%), payout_gateway, gateway_data (ID conta).

Go: Split receita por venda conforme co_producers active.

24. Menu: Configuração ⚙️

page=configuracao

24.1 Meus Bots tab=meus_bots

Lista bots: nome, plataforma, moeda, clientes, status. Ações: editar (modal), ativar/desativar.

Modal edição: name, description, currency, language, bot_token (vazio=mantém).

24.2 Criar Novo Bot tab=criar_bot

name*, description, currency, language, status, bot_token, platform=telegram fixo.

24.3 Geral tab=geral

Moeda padrão dashboard (users.dashboard_currency).

25. Menu: Idioma do Bot 🌐

page=idioma_bot tab=idioma

Grid 17 idiomas com seletor bot. Salva bots.language.

Go: Recarregar pacote i18n quando language mudar.

26. Menu: Pagamentos 💰

page=pagamentos tab=geral

Mini-stats: total recebido, pendentes, expirados.

Filtros: bot_id, status, product_id, payment_method, date_from, date_to, per_page (10/25/50/100).

CRUD: criar/editar (modal), excluir. Status: pending, completed, expired.

Go: Fonte primária de pagamentos é runtime; dashboard é consulta/gestão manual.

27. Menu: Notificações 🔔

page=notificacoes tab=lista

Notificações in-app para dono dashboard (NÃO Telegram). Paginação 25/página.

Tipos: info, success, warning, error, payment, client. Ao abrir página marca todas como lidas.

Go (opcional): INSERT notification em eventos importantes (venda, falha pagamento).

28. Menu: Avançado 🚀

page=avancado tab=geral

• Conexão DB: health check host, database, version MySQL
• Seletor bot: escolhe bot para export/delete
• Exportar dados: download JSON com bot, clients, payments, products, strategies, flows, mass_messages, bot_buttons, co_producers, analytics. Token mascarado.
• Zona perigo: deleteBotData — exclusão transacional total do bot (confirmação JS com nome do bot)

29. Menu: Tutoriais 📚

page=tutoriais tab=lista

Grid cards informativos: Primeiros Passos, Fluxo, Pagamentos, Produtos, Massa, Estratégias. Conteúdo estático (botão assistir placeholder).

Linkado no menu Suporte como canal Tutoriais.

30. Menu: Suporte 💬

page=suporte

30.1 Meus Tickets tab=meus_tickets

Lista tickets: assunto, prioridade, status, data. Ver detalhes (modal com admin_reply). Excluir se open/closed.

Status: open, in_progress, resolved, closed. Prioridade: low, medium, high, urgent.

30.2 Novo Ticket tab=novo_ticket

Form: subject, priority, message → createUserSupportTicket.

Canais de suporte (ambas abas)

31. Funções PHP — Core e Auth

includes/functions.php

• __() — Tradução i18n com placeholders
• getCurrentLanguage() — Cookie idioma, default pt
• setLanguageCookie()
• getCurrentTheme() / setThemeCookie() — light|dark
• getCurrentColorScheme() / setColorCookie()
• isRTL() — true se ar
• formatCurrency() — Formata valor com moeda
• getUserBotCurrency() / getUserDashboardCurrency()
• formatDate() — dd/mm/yyyy HH:mm
• sanitize() — htmlspecialchars
• redirect() / jsonResponse()
• getMenuItems() / getTabLabel()

includes/auth.php

• isLoggedIn() / requireLogin() / isAdmin() / requireAdmin()
• getCurrentUser() / loginUser() / logout()
• registerUser() / authenticateUser()
• updateUserPreferences() / updateUserDashboardCurrency()
• getDashboardStats() — bots, clients, revenue, products, users
• getUserNotificationsPaginated() — 25/página
• createNotification() / markAllNotificationsAsRead()

32. Funções PHP — Bot (includes/bot.php)

• getUserBots() / getUserBot() / getUserPrimaryBot()
• createUserBot() — name, token, language, currency, status
• updateUserBot() — edição modal meus bots
• setBotStatus() — active/inactive
• saveBotLanguage() — bots.language
• saveBotPresentation() — welcome + media
• uploadPresentationMedia() / getPresentationMediaUrl()
• maskBotToken() — mascaramento token na UI

33. Funções PHP — Fluxo (includes/flow.php)

• getDefaultFlowData() / normalizeFlowData()
• getBotConversationFlow() / saveBotConversationFlow()
• getBotFlowPayload() — payload completo editor JS
• uploadBotFlowMedia() / deleteBotFlowMedia()
• getBotFlowMediaList() / countBotFlowMedia()
• getUserProductsForFlow() / getUserGatewaysForFlow()
• normalizeBranchingNodeData() — question/condition branches

34. Funções PHP — Produto (includes/product.php)

• saveUserProduct() / deleteUserProduct() / setProductStatus()
• validateProductInput() — access, delivery, VIP rules
• uploadProductContent() — uploads/products/
• isProductUsedInAnyFlow() / getProductFlowUsage()
• getProductAccessLabel() / getProductDeliveryLabel()

35. Funções PHP — Gateway (includes/gateway.php)

• getAvailableGatewayProviders() — lista 11 providers
• saveUserGatewayConfig() — salva credenciais + config JSON
• getUserGatewayConfigs() / getUserActiveGatewaysForFlow()
• formatGatewayConfig() / maskGatewayApiKey()
• getGatewaysPagePayload() — payload API/JS

36. Funções PHP — Demais Módulos

includes/strategy.php

getUserStrategyByType, saveUserStrategy, getUserProductsForStrategy

includes/client.php

getUserClientsPaginated, updateUserClient, banUserClient, sendClientMessage

includes/mass_message.php

createUserMassMessage, canCreateMassMessage, uploadMassMessageMedia

includes/statistics.php

getSalesByProductStats, getSocialSourceStats, getConversionStats, getAbandonmentStats, getRecoveryStats

includes/bot_button.php

saveUserBotButton, getUserBotButtons, setBotButtonStatus, deleteUserBotButton

includes/coupon.php

saveUserCoupon, normalizeCouponCode, setCouponStatus, deleteUserCoupon

includes/affiliate.php

saveUserAffiliateSettings, getUserAffiliatesPaginated, updateAffiliateCommissionRate

includes/coproducer.php

saveUserCoProducer, setCoProducerStatus, deleteUserCoProducer

includes/payment.php

createUserPayment, updateUserPayment, deleteUserPayment, getUserPaymentsPaginated, getUserPaymentStats

includes/support.php

createUserSupportTicket, deleteUserSupportTicket, getSupportChannels

includes/advanced.php

checkDatabaseConnection, exportBotData, deleteBotData, streamBotExport

37. Runtime Bot Telegram (Go) — Especificação

37.1 Bootstrap

• Conectar MySQL bot_dashboard utf8mb4
• Carregar bots WHERE status=active AND bot_token IS NOT NULL
• Webhook ou long polling Telegram Bot API
• Pacote i18n para 17 idiomas keyed por bots.language

37.2 Ciclo /start

1. Parse deep link payload (affiliate ref, social source)
2. UPSERT clients (platform_user_id = Telegram chat ID)
3. INSERT bot_analytics_events event_type=start
4. Enviar welcome_message + presentation media
5. Carregar conversation_flows.flow_data e iniciar máquina de estados
6. Anexar bot_buttons ativos (first/last)

37.3 Checkout e entrega

1. Nó payment → selecionar gateway → criar cobrança
2. INSERT payments status=pending
3. Webhook gateway → status=completed
4. Validar cupom se aplicável (max 91% desconto)
5. Calcular splits afiliado + co-produtor → metadata JSON
6. Entregar produto conforme delivery_mode
7. Assinatura → clients.access_expires_at
8. Trigger estratégia upsell após delay_minutes

37.4 Workers background

• Estratégias remarketing/downsell/upsell (delay_minutes)
• Mass messages (scheduled_at, repeat_daily)
• Client messages pending → sent
• Expiração assinaturas → clients.status=expired
• Pagamentos pending → expired (timeout configurável)

37.5 Estrutura Go sugerida

cmd/bot/main.go
internal/config/       # env, DSN
internal/db/           # repositories MySQL
internal/telegram/     # Bot API client
internal/flow/         # interpreter flow_data
internal/payment/      # 11 gateway adapters
internal/delivery/     # file, link, vip, subscription
internal/analytics/    # bot_analytics_events
internal/i18n/         # 17 languages
internal/worker/       # strategies, mass, messages

38. Estrutura JSON flow_data (Referência Completa)

{
  "nodes": [
    {
      "id": "start_a1b2c3d4",
      "type": "start",
      "sort_order": 0,
      "data": {}
    },
    {
      "id": "message_welcome",
      "type": "message",
      "sort_order": 1,
      "data": {
        "text": "Bem-vindo! Como posso ajudar?",
        "media_id": 5,
        "media_name": "banner.jpg",
        "media_type": "image",
        "media_url": "http://localhost/bot-dashboard/uploads/flow/1/2/banner.jpg"
      }
    },
    {
      "id": "question_buy",
      "type": "question",
      "sort_order": 2,
      "data": {
        "text": "Deseja ver nossos produtos?",
        "buttons": { "yes": "Sim", "no": "Não" },
        "branches": {
          "yes": [
            { "id": "product_1", "type": "product", "sort_order": 0,
              "data": { "product_id": 12, "product_name": "Curso VIP" } }
          ],
          "no": [
            { "id": "msg_bye", "type": "message", "sort_order": 0,
              "data": { "text": "Ok! Volte quando quiser." } }
          ]
        }
      }
    },
    {
      "id": "payment_checkout",
      "type": "payment",
      "sort_order": 3,
      "data": { "gateway_id": 3, "gateway_name": "Stripe" }
    }
  ]
}

39. Uploads — Paths Completos

URL pública: {APP_URL}/uploads/{file_path}

40. Admin Panel (admin/)

Painel separado para role=admin. Páginas: dashboard, users, bots, products, payments, settings.

URL: {APP_URL}/admin/index.php?page={page}

Gerencia todos usuários e dados globais. Não afeta runtime bot diretamente.