Botoscope^®

Não há um ID de tenant em lado nenhum do motor. init() inicia sessão num cliente bot TDLib, abre um pool knex e uma ligação Redis, e lê o domínio da loja, a chave de API do cliente, o limite de produtos e a flag do plano gratuito a partir de variáveis de ambiente. O isolamento entre lojas é uma questão de implementação: cada bot tem a sua própria instância, com o seu próprio diretório de base de dados TDLib e esquema MySQL.

Isto mantém simples as consultas e as chaves Redis (chat:<id>:<key>) ao custo de um processo por loja. As chaves Redis não levam prefixo do bot, pelo que duas instâncias não podem partilhar a mesma base de dados Redis.

O bot inicia sessão através do TDLib (tdl com tdl-tdlib-addon) com um token de bot e mantém uma única ligação duradoura ao Telegram. As atualizações são empurradas para client.on('update'), pelo que o motor não precisa de um URL de webhook acessível a partir do Telegram nem de um ciclo de polling com getUpdates.

A razão principal é o modelo de ecrãs. O TDLib comunica as mensagens enviadas pelo próprio bot como updateNewMessage e updateMessageSendSucceeded no mesmo fluxo das mensagens do cliente. Um único handler regista cada ID de mensagem numa conversa privada, enviada ou recebida, e quando um ecrã muda o motor elimina-as com deleteMessages (revoke: true). A conversa guarda apenas o ecrã atual, e as entradas escritas, como uma pesquisa ou uma morada, desaparecem com ele. O mesmo fluxo permite ao motor esperar até um álbum de fotografias ter realmente chegado antes de enviar o painel do produto.

O TDLib cobre também chamadas que a Bot API por HTTP não tem: getMessage relê o texto de uma mensagem que o bot enviou antes, o que o painel de produtos agrupados usa para redesenhar os seus botões. getChat e getUser são respondidos pelo cliente TDLib com a base de dados de informação de conversas ligada, e os ficheiros multimédia saem de caminhos locais ou por ID de ficheiro remoto através da base de dados de ficheiros. A base de dados de mensagens está desligada porque o bot não guarda histórico, o otimizador de armazenamento poda os ficheiros do TDLib, e o TDLib corre com uma thread de trabalho.

O custo é que a semântica do TDLib se infiltra na aplicação: os IDs das mensagens são provisórios até o servidor os confirmar (ver a tarefa de mapeamento de IDs), e o diretório de sessão prende um bot a um processo.

Possíveis passos seguintes que o TDLib já oferece: ligar a sua base de dados de mensagens para histórico e pesquisa por conversa, e enviar ficheiros maiores do que o limite de 50 MB de envio da Bot API por HTTP. O motor não faz nenhuma das duas hoje; limita os documentos a 50 MB.

Answer transforma as atualizações do TDLib em eventos do bus: do_callback_query para toques em botões, do_command para texto, pre_checkout_query e successful_payment para pagamentos. Carrinho, favoritos, reservas, suporte e os restantes subscrevem e tratam apenas as suas próprias ações, pelo que não importam os handlers uns dos outros.

Para a composição da interface há dois registos de hooks. Hooks guarda callbacks por chat_id (o menu de contexto atual, botões extra de produto) ordenados por prioridade, onde acrescentar um hook com uma prioridade existente o substitui. GlobalHooks faz o mesmo para todas as conversas; a extensão de suporte usa-o para acrescentar um botão a painéis de produto que não são seus. Os hooks por conversa são largados quando a conversa é eliminada.

A lista de extensões ativas (cupões, envio, suporte, reservas, marketing, b2b e outras) é sincronizada para a tabela de opções. Extensions.init() converte cada slug num nome de classe e instancia-a antes de os módulos principais serem construídos, para que os seus hooks existam primeiro. Os módulos principais verificam uma extensão através de getters opcionais e mudam de comportamento; por exemplo, o checkout salta o passo do código promocional quando os cupões estão desligados.

Desativar uma extensão não consegue descarregar código que já registou listeners, pelo que repor a cache das extensões reinicia o processo através do PM2. Os comentários do código notam que isto interrompe os utilizadores a meio de uma sessão.

Commander corre um servidor http simples com /health e /command. Os comandos conhecidos (payment_success, order_is_done, reset_cache, update_product_cache) são tratados diretamente. Tudo o resto é emitido como exec_command; o módulo que o possui escreve is_executed e answer no objeto body partilhado, que o endpoint devolve após uma curta espera fixa.

reset_cache atualiza uma cache de definições ou todas, com as extensões sempre em último porque essa reinicia o processo. O reset_db_cache() de cada módulo volta a puxar o seu blob JSON para a tabela de opções e limpa a sua cópia em memória.

ecosystem.config.cjs corre uma única instância em fork (o modo cluster está comentado; um token de bot significa uma sessão TDLib), limita o espaço antigo do V8, reinicia perante crescimento de memória e exige 30 s de funcionamento antes de um arranque contar como estável. Os handlers de SIGTERM, SIGINT e SIGQUIT destroem o pool knex antes de sair, e um temporizador regista o uso do pool quando há atividade.

As caches em memória, como carrinhos e moedas selecionadas, são limpas por temporizadores, e o mapa de IDs de mensagens é esvaziado a cada mudança de ecrã.

sendMessage no TDLib devolve um ID local provisório; o ID real chega depois em updateMessageSendSucceeded, juntamente com old_message_id. O motor guarda o ID devolvido por send() no contexto da conversa (top_message_id, taxonomies_btn_mgs_id e semelhantes) e resolve-o através de MessageMapping quando precisa de editar ou eliminar essa mensagem.

O mapeamento viveu primeiro no Redis e passou para um mapa por conversa em memória, limpo a cada mudança de ecrã para se manter pequeno. Sem ele, editar um teclado inline após um clique apontaria a um ID que já não existe.

Cada novo ID de mensagem numa conversa privada é empurrado para chat:<id>:messages. make_messages_castling() move essa lista para chat:<id>:old_messages e repõe o mapeamento de IDs, o módulo desenha o novo ecrã, e clear_display() elimina depois as mensagens antigas. O novo conteúdo aparece antes de o antigo desaparecer, pelo que a conversa nunca fica em branco entre ecrãs.

Experimentou-se uma limpeza completa da conversa, mantida no código apenas como aviso: em alguns telemóveis expulsava o utilizador do bot.

O menu persistente inferior mostra um botão de carrinho com a contagem de artigos em tempo real. O Telegram não permite editar o texto de uma mensagem que leva um teclado de resposta, pelo que Cart.redraw_menu() envia uma nova mensagem de topo e elimina a anterior pelo seu ID mapeado, enquanto o resumo inferior, uma mensagem inline, é editado no próprio local após um curto atraso.

O menu atual é guardado como um hook context_menu por conversa. change_menu_buttons_text() reescreve apenas o botão que começa pelo emoji do carrinho no menu serializado, de modo que qualquer ecrã possa atualizar a contagem do carrinho sem conhecer a sua própria disposição.

format_string_before_send() trata strong, em, u, s, code, pre e a href. Encontra a tag de abertura mais próxima, remove-a juntamente com a de fecho, e regista as posições de início e fim na string limpa; estas tornam-se offsets de textEntity em formattedText. As entidades HTML nomeadas e numéricas do WooCommerce são descodificadas primeiro. Uma tag malformada ou por fechar faz a função devolver o texto original sem entidades em vez de enviar formatação quebrada.

Dois truques de disposição ficam a seu lado: uma sequência de carateres em branco Braille preenche as mensagens para que os cartões de produto tenham a mesma largura, e um caráter de sobreposição combinante desenha um preço antigo riscado dentro dos rótulos dos botões, onde as entidades não são permitidas.

Os botões do teclado de resposta chegam como texto simples no idioma do utilizador, pelo que o encaminhamento compara o texto recebido com os rótulos construídos por get_menu_command_text() para essa conversa. Quando um passo espera texto livre (pesquisa, SKU, morada, código promocional, mensagem de suporte), o contexto guarda is_waiting_user_input e o comando a retomar. Answer guarda o texto como user_message_text e repete esse comando, a menos que o texto seja um comando com barra ou um rótulo de navegação.

Os handlers de entrada do checkout repetem a verificação contra os rótulos dos seus próprios passos, pelo que premir Voltar quando se espera uma morada navega para trás em vez de guardar a palavra como morada.

Um cartão de produto é um álbum multimédia seguido de um painel de texto com botões. print_products_blocks() envia o álbum, espera até 10 s pelo evento new_message_coming dessa conversa, e faz depois uma pausa antes de enviar o painel, para que o painel nunca fique acima das suas fotografias. Curtas pausas fixas antes de cada envio e eliminação espaçam os pedidos.

Toques rápidos em seguinte e anterior iniciariam de outro modo uma segunda troca de ecrã antes de a primeira ter eliminado as suas mensagens. Uma flag nowdo por conversa ignora a navegação enquanto um ecrã está a ser substituído e é libertada um segundo depois de as mensagens antigas serem eliminadas.

get_rest_data() e send_remote_data() fazem post para um único URL de proxy do Botoscope. A loja é indicada num cabeçalho client-domain, o endpoint noutro, e o pedido é autenticado com a chave de API do cliente e um código derivado com HMAC-SHA256. Os descarregamentos de ficheiros usam o mesmo proxy através do seu endpoint fetch-file.

O motor nunca precisa das chaves REST da própria loja, e o lado WordPress só tem de responder ao proxy. As falhas devolvem null e quem chama trata null como ausência de dados, pelo que uma indisponibilidade da loja degrada-se para listas vazias em vez de fazer falhar um ecrã.

Products.reset_db_cache() lê a contagem de produtos, trunca products e products_vs_terms, executa ALTER TABLE ... DISABLE KEYS nas duas tabelas MyISAM e puxa products/{offset}/{limit} em páginas de 100. Cada página é inserida em lotes de 100 linhas; um erro numa página é registado e a importação passa à página seguinte. O MyISAM não tem transações, pelo que as linhas já escritas de uma página falhada permanecem. As chaves são reativadas num bloco finally, de modo que uma importação falhada deixa na mesma tabelas indexadas. Enquanto a importação corre, o bot mostra a parte do catálogo carregada até ao momento.

A importação não corre no arranque. Um comentário explica que, com um catálogo grande, poderia bloquear o servidor após cada reinício, pelo que corre apenas num comando reset_cache explícito vindo da loja.

insert_product_batch() desestrutura os campos que o motor consulta (price, sale_price, flags de stock, type, parent_id, publish_date, menu_order, mínimo, máximo e passo do carrinho) em colunas e serializa o resto do payload em data. Listas de multimédia, downloads, dias de acesso ou o URL de um produto externo podem ser acrescentados do lado da loja sem alterar o esquema. Os IDs de categoria vão tanto para uma lista separada por vírgulas na linha como para products_vs_terms, para consultas indexadas de categorias.

install.sql corre em cada arranque com CREATE TABLE IF NOT EXISTS, pelo que uma nova instância cria o seu próprio esquema.

Quando um produto muda no WooCommerce, o lado da loja envia update_product_cache para /command. update_product_cache() vai buscar products_filter/{id}, que devolve o produto com as suas variações, elimina depois a linha do produto, as linhas com esse parent_id e as suas ligações a categorias, e insere as novas linhas. Um único pedido traz o produto e as suas variações, pelo que as linhas são reescritas uma vez por alteração.

O limite do plano conta apenas os produtos-pai. A importação completa corta os produtos principais por página e mantém sempre as suas variações; o caminho incremental ignora um novo produto quando a contagem de produtos distintos em products_vs_terms atinge o limite.

Para produtos com stock gerido, um temporizador a cada três minutos define is_in_stock a partir de stock_quantity nos dois sentidos, de modo que o botão de compra segue a quantidade real mesmo quando uma flag enviada estava desatualizada. Os clientes podem subscrever um produto esgotado ou uma única variação; stock_notify guarda product_id e chat_id. De duas em duas horas o motor encontra os produtos subscritos que voltaram a ter stock, envia de novo o cartão a cada subscritor e remove a subscrição.

Cada consulta ao catálogo compara também publish_date com a hora atual, de modo que os produtos agendados ficam ocultos até à sua data.

O comando /filter e os botões Filtrar abrem filter_page_url como Web App com o chat_id anexado. A filtragem corre do lado do WordPress. O resultado regressa ao motor como um comando filtered_products_ids em /command, e Products imprime esses IDs como um catálogo paginado normal nessa conversa.

Isto mantém a contagem de facetas e a lógica de atributos num só sítio, na loja, enquanto a conversa continua a mostrar os resultados no seu próprio formato de cartão.

Cart.get() serve a partir de um mapa estático por conversa e recorre ao Redis (chat:<id>:cart); update() escreve em ambos. O rótulo do botão do carrinho, os totais e cada painel de produto leem o carrinho, pelo que a cache poupa uma ida e volta ao Redis de cada vez. Os artigos podem ter uma validade, usada pelas retenções de reservas, e são largados na leitura quando expiram. Desenhar o carrinho remove primeiro os IDs que já não existem no catálogo local, de modo que um produto eliminado no WooCommerce não pode chegar ao checkout.

Os botões de quantidade respeitam quantity_step, min_cart_count e o stock gerido, e uma variação sem valores próprios herda-os do produto-pai.

get_buy_buttons_panel() lê a combinação de atributos de cada variação e ordena os atributos pela ordem de atributos da loja. A primeira linha lista todos os termos em uso; cada linha seguinte lista apenas os termos que, juntamente com as escolhas acima, correspondem a pelo menos uma variação existente. Um atributo com três ou mais opções pode ser mostrado como uma linha compacta anterior / atual / seguinte em vez de uma grelha.

Mudar um atributo superior limpa os inferiores e ajusta-se à primeira combinação correspondente. Um produto abre na sua variação mais barata. A escolha é guardada por conversa e produto no contexto, e o painel é editado no próprio local a cada toque.

Os passos base são código promocional, morada de envio, método de envio, método de pagamento, comentário e confirmar. Os passos das extensões desativadas são removidos no arranque. get_checkout_steps() inspeciona então o carrinho, percorrendo os produtos agrupados e as variações dos seus filhos variáveis para encontrar qualquer artigo físico; um carrinho sem nenhum salta os dois passos de envio. Um total zero passa para a gate de oferta e salta a escolha de pagamento, uma loja com uma só gateway pré-seleciona-a, e pagar em Stars força a gate Stars.

Os passos obrigatórios bloqueiam next() até um valor ser guardado, e qualquer passo pode ser reaberto em modo de edição a partir do ecrã de confirmação e regressar diretamente a este.

generate_payment_button() chama create_order apenas quando o contexto ainda não tem order_id, e guarda depois o ID. Se o cliente voltar atrás e mudar o método de pagamento, a morada, o código promocional ou o comentário, cada handler chama orders.edit(order_id, ...) para que a encomenda WooCommerce seja corrigida em vez de duplicada.

A encomenda leva o chat_id do Telegram e o nome do bot, de modo que o histórico de encomendas é obtido por conversa e uma ligação pay-for-me pode localizar a encomenda mais tarde.

Os intervalos vêm da loja por produto e dia com capacity e capacity_used, e os intervalos que a loja marca como reservados são filtrados. Quando um cliente escolhe um intervalo, o motor regista uma retenção com validade e adiciona a reserva ao carrinho com o mesmo tempo de retenção. is_freezed() conta as retenções ativas para esse intervalo, data e chave e bloqueia o intervalo quando as retenções atingem a capacidade menos os lugares usados. Remover o artigo do carrinho liberta a sua retenção através do evento done_remove_from_cart.

As datas do calendário e a filtragem de intervalos passados usam o fuso horário da loja nas definições, não o relógio do servidor. As retenções vivem na memória do processo do bot, pelo que se aplicam apenas aos clientes deste bot e são repostas num reinício; as reservas feitas no site ao mesmo tempo não são retidas.

As campanhas de marketing usam fórmulas como 'c >= 6 & c < 12; 25%; 3n, me, cap=3'. parse_formula() divide-as em condições de contagem de artigos, um desconto percentual ou fixo, e modificadores (cada n-ésima unidade, mais barato ou mais caro primeiro, um limite). get_applied_amount() expande o carrinho numa entrada por unidade de produtos da campanha, aplica as fórmulas por ordem e marca as unidades usadas para que uma fórmula posterior não as volte a descontar.

As janelas das campanhas são verificadas no fuso horário da loja, as campanhas em modo de teste aplicam-se apenas à conversa do administrador, e o desconto da campanha é ignorado quando já se aplica um cupão. Os cupões com âmbito de produto estendem-se aos filhos dos produtos agrupados e variáveis.

Os totais do carrinho, os descontos e o envio são calculados na moeda base. format_price() converte para a moeda selecionada da conversa com a taxa sincronizada e aplica a posição do símbolo e as casas decimais, arredondando para cima quando os cêntimos estão ocultos. generate_payment_button() recalcula o total na moeda selecionada antes de chamar uma gateway. As encomendas obtidas do WooCommerce noutra moeda são divididas pela sua taxa de encomenda guardada, de modo que o histórico e os totais coincidem com a aritmética do próprio bot.

Quando a loja não permite pagar noutras moedas, a seleção é reposta na moeda base no passo de pagamento e o cliente é informado do motivo.

As Stars são configuradas como uma moeda chamada XTR na lista de moedas da loja, pelo que a sua taxa chega pela mesma sincronização. O montante é o total base vezes a taxa XTR, arredondado para cima. A fatura é enviada como inputMessageInvoice com um token de fornecedor vazio e um payload JSON em base64 com order_id, chat_id, amount e gateway. A consulta de pré-checkout é respondida e, em messagePaymentSuccessfulBot, o payload é descodificado e a loja é notificada de que a encomenda está paga.

Sem uma moeda XTR, a opção Stars comunica um erro em vez de uma fatura.

Para o CryptoBot, o motor cria uma fatura denominada em moeda fiduciária com validade de 900 s e faz polling de getInvoices a cada 8 s. Um Map de temporizadores indexado por chat_id mantém um polling ativo por cliente, e abrir o carrinho cancela-o. Quando pago, a encomenda passa a processing e o carrinho é limpo; quando expirada ou cancelada, o cliente recebe uma mensagem.

O CoinGate segue o caminho inverso: o seu URL de callback aponta para o proxy do Botoscope, que reencaminha o webhook para /command como payment_success, e a encomenda é concluída quando o webhook comunica pago.

Cada gateway tem o seu próprio construtor: Stripe através de uma Checkout Session, LiqPay através de um blob de dados em base64 assinado com SHA-1 sobre chave privada, dados e chave privada. A ligação é enviada como botão Web App ou URL, opcionalmente precedida por botões das políticas de reembolso, privacidade e envio. O construtor do PayPal (credenciais de cliente OAuth, depois um pagamento com URLs de retorno e cancelamento) envia o pagamento para o endpoint sandbox do PayPal neste código, pelo que serve apenas para testes.

Os métodos offline (dados de cartão bancário, SWIFT, oferta, pay-for-me) mostram instruções traduzidas e um botão de confirmação em vez de uma ligação.

Escolher pay-for-me termina o checkout com uma ligação t.me que inicia o bot com payforme_<order_id>. Quando outro utilizador a abre, o motor carrega a encomenda da loja, aplica a moeda da encomenda, remove os métodos offline e pay-for-me e mostra as gateways restantes para o total da encomenda. Após o pagamento, a conversa do comprador recebe uma mensagem que nomeia quem pagou.

send_media_gallery() faz o hash de cada URL de multimédia, guarda o ficheiro em media_files_cache/<first two hex chars>/<hash> na primeira utilização e depois entrega ao TDLib o caminho local. Os ficheiros de zero bytes são eliminados e ignorados, um álbum é limitado a 8 itens, e uma variação sem imagens próprias recorre à multimédia do produto-pai.

As ligações a publicações t.me ignoram a cache e vão para o TDLib como ficheiros remotos.

downloadFileToLocal() aceita apenas URLs http(s) no domínio do próprio cliente ou em hosts do Telegram, rejeita extensões de executáveis e scripts em ligações diretas, envia um pedido HEAD para rejeitar ficheiros acima do limite (10 MB para imagens e áudio, 50 MB para vídeo e documentos), e depois transmite o ficheiro através do endpoint fetch-file do proxy com o mesmo limite. Os descarregamentos vazios, demasiado grandes e falhados são eliminados do disco.

Answer vigia as publicações em canais. Quando um vídeo aparece num canal a que o bot pertence, o bot responde com o ID de ficheiro remoto do vídeo. Uma ligação de publicação t.me ou esse ID podem então ser usados como multimédia do produto, e o motor envia-o como ficheiro remoto, de modo que o Telegram o serve do seu próprio armazenamento sem envio por cliente.

Quando o carrinho continha produtos descarregáveis e a encomenda é paga online ou é gratuita, do_after_pay() envia cada download desses produtos como documento. Os ficheiros ficam em cache sob um nome derivado do ID do download por shiftUUID(), de modo que o nome guardado não é o ID da loja, e os documentos acima de 50 MB são recusados. Os produtos com acesso limitado mostram os dias restantes, calculados a partir da data de pagamento da encomenda.

As faturas em PDF do endpoint de faturas da loja seguem o mesmo caminho.

Sete ficheiros de idioma (en, es, pt, ru, pl, kz, ua) com as mesmas 215 chaves são carregados no arranque. __() junta o ficheiro de idioma da conversa com as substituições que o proprietário introduziu na administração (sincronizadas como interface_translations e indexadas como s<number>); se uma chave continuar em falta, tenta de novo com o inglês mais as substituições. O idioma escolhido é guardado por conversa; no primeiro contacto vem do language_code do cliente Telegram quando esse idioma está ativo, caso contrário do valor por defeito da loja.

Como os botões de menu são correspondidos pelo seu texto localizado, os rótulos de uma conversa são resolvidos em paralelo com Promise.all em cada verificação de encaminhamento.

Produtos, categorias, marcas, campos meta, métodos de envio e de pagamento levam um objeto translations. translate_to() devolve 0 quando a conversa usa o idioma por defeito, pelo que o caso comum salta todas as consultas; caso contrário, get_field_translation() escolhe o campo traduzido e recorre ao original. A pesquisa por título corre LIKE sobre a coluna do título e o JSON de traduções guardado, com um mínimo de 3 carateres, de modo que uma pesquisa em qualquer idioma ativo encontra o produto.

As datas na meta dos produtos e os períodos de acesso são formatados com o idioma da conversa como locale.