Bxio
1be8a45dde
All checks were successful
Testar e publicar imagem Docker / publish (push) Successful in 44s
92 lines
7.8 KiB
Markdown
92 lines
7.8 KiB
Markdown
# TS6 Botflow 0.3
|
|
|
|
Painel local XanaX para gerir bots TeamSpeak, com login Discord e editor visual de flows. Usa os logótipos originais e o tema flat roxo.
|
|
|
|
## Editor e motor
|
|
|
|
- **68 blocos** para eventos, dados, lógica, clientes, canais, grupos, servidor, permissões e integrações.
|
|
- Vários pontos de início por flow: temporizador, cron, manual, eventos TeamSpeak, comandos de chat e webhook.
|
|
- Portas Seguinte, Sim/Não, Cada/Fim e Erro. Ciclos no grafo são recusados; **Para cada item** percorre listas.
|
|
- Arrastar, zoom, ajustar ao ecrã, organizar, duplicar, desfazer/refazer, pesquisa e validação.
|
|
- Atalhos na área do editor: Ctrl+S, Ctrl+Z, Ctrl+Y, Ctrl+D e Delete. Shift+arrastar ou botão do meio desloca a área.
|
|
- Templates: Estatísticas, Boas-vindas, Mover inativos, Comando de informações, Contador de entradas e Personalizado.
|
|
- Importação/exportação JSON e duplicação. Importações começam desativadas e sem ligação. Exportações omitem campos secretos; webhooks importados recebem novos segredos.
|
|
- Listas de clientes, canais, grupos e permissões carregadas do servidor pelo botão no editor.
|
|
- Simulação com dados de exemplo ou evento JSON personalizado, sem pedidos TeamSpeak/HTTP/Discord nem alterações em variáveis persistentes.
|
|
- Histórico por passo, tentativas, cancelamento, filtros e atualização automática.
|
|
|
|
A falha segue a porta **Erro**, quando ligada, e fica registada como erro tratado. Sem essa ligação, termina a execução. Até três tentativas adicionais repetem a ação. Cada bot tem uma execução de cada vez, fila limitada de eventos e limite de duração entre 10 e 600 segundos.
|
|
|
|
## Ações
|
|
|
|
| Categoria | Operações |
|
|
| --- | --- |
|
|
| Clientes | Consultar, mensagem privada/canal/servidor, poke, mover, kick, ban e remover ban |
|
|
| Canais | Listar, consultar, criar, editar campos/descrição, mover e apagar |
|
|
| Grupos | Listar, criar, renomear, apagar; adicionar/remover cliente, definir grupo de canal, consultar membros e grupos de um cliente |
|
|
| Servidor | Consultar informações e editar campos com parâmetros JSON |
|
|
| Permissões | Adicionar/remover/consultar: cliente, canal, grupo de servidor, grupo de canal e cliente num canal |
|
|
| Lógica | Condições, expressões, ordenação, top, filtros, foreach, variáveis, cálculos, códigos aleatórios, texto, espera e paragem |
|
|
| Integrações | HTTP GET/POST/PUT/PATCH/DELETE, Discord, webhook de entrada e WebQuery avançado |
|
|
|
|
**clid** identifica a sessão online; **cldbid** identifica a pessoa na base de dados para grupos/permissões. Usar `{{event.clid}}` ou `{{event.client_database_id}}`; num foreach, `{{item.clid}}` ou `{{item.client_database_id}}`.
|
|
|
|
WebQuery avançado recebe operação e parâmetros JSON separados. Exemplo: `channeledit`, parâmetros `{"cid":21,"channel_description":"{{text}}"}`. Inclui operações adicionais para tokens, mensagens, reclamações, logs, cópia de grupos e edição de clientes. A resposta é uma lista em `temp.result` (configurável): `{{temp.result.0.campo}}`. Blocos de criação de canal/grupo guardam um objeto com o ID criado.
|
|
|
|
## Variáveis e expressões
|
|
|
|
Blocos de dados preenchem `server`, `clients`, `channels` e `temp`. Executá-los antes de usar os seus valores. Variáveis persistentes suportam texto, números, booleanos e JSON. Temporárias duram uma execução.
|
|
|
|
```text
|
|
{{server.virtualserver_name}}
|
|
{{server.virtualserver_clientsonline - server.virtualserver_queryclientsonline}}
|
|
{{variables.entradas}}
|
|
{{temp.resultado}}
|
|
{{event.command_args}}
|
|
{{event.webhook_body.name}}
|
|
{{item.client_nickname}}
|
|
{{text}}
|
|
{{top}}
|
|
{{time}}
|
|
{{time.time}}:{{time.seconds}}
|
|
{{temp.error.message}}
|
|
```
|
|
|
|
Expressões suportam contas, parênteses, comparações, `&&`, `||` e `!`, com avaliação condicional de `&&`/`||`. Funções: `round`, `floor`, `ceil`, `abs`, `min`, `max`, `lower`, `upper`, `length`, `contains`, `startsWith`, `endsWith`. São interpretadas por um parser próprio, sem executar JavaScript. Valores em falta numa conta ou divisão por zero produzem erro no passo.
|
|
|
|
Filtros: `{{text | upper}}`, `{{temp.result | json}}`, `{{server.virtualserver_uptime | uptime}}`. Horário: Europe/Lisbon; o trigger cron tem fuso configurável.
|
|
|
|
O template Estatísticas atualiza o canal **21** a cada 30 segundos. O top ordena pessoas atualmente online pela data de entrada. Ranking histórico está no [checklist](FLOW_CHECKLIST.md).
|
|
|
|
## Eventos, chat e webhooks
|
|
|
|
Em **Ligações**, configurar WebQuery HTTP/HTTPS, ID virtual e API key. Para eventos/comandos, ativar **Escuta SSH Query** e indicar host, porta (habitualmente **10022**), utilizador e password do SSH Query TeamSpeak.
|
|
|
|
A primeira ligação guarda a impressão digital SHA-256; uma alteração da chave exige confirmar e atualizar esse campo. Há reconexão automática e estado visível em Ligações. Escutas começam quando um bot ativo as utiliza, partilhadas por servidor/canal.
|
|
|
|
Um comando pode restringir um grupo de servidor. Canal vazio escuta mensagens privadas/servidor. Um ID de canal cria uma sessão Query nesse canal para escutar o seu chat. Notificações de entrada, saída, movimento, mensagens e edição de canais/servidor ficam em `event`.
|
|
|
|
Webhook: `POST /api/hooks/ID_DO_BOT`, cabeçalho **X-Webhook-Secret** (ou Bearer) com o segredo do bloco. O bot deve estar ativo. Corpo JSON em `event.webhook_body`. Limites: 30 chamadas por minuto por bot, 100 eventos em fila, corpo até 500 KB. O bloco permite filtros de campos do corpo.
|
|
|
|
Cron aceita cinco/seis campos numéricos, `*`, listas, intervalos e passos. **`* * * * * *`** executa a cada segundo; **`* * * * *`** a cada minuto. Temporizadores aceitam um segundo. Ações demoradas prolongam o intervalo efetivo; permissões e proteção contra flood do TeamSpeak devem permitir os pedidos.
|
|
|
|
## Docker / Portainer
|
|
|
|
Web editor: [deploy/bot-stack.yaml](deploy/bot-stack.yaml). Runner: [deploy/README.md](deploy/README.md). Cada push em `main` testa, constrói e publica. Depois do workflow verde, fazer **Update stack / Re-pull and redeploy**. O volume `/app/data` preserva bots, flows, ligações e sessões. Build local: `compose.yaml`.
|
|
|
|
Variáveis: `APP_URL` (ex. `http://192.168.88.99:3080`), `DISCORD_CLIENT_ID`, `DISCORD_CLIENT_SECRET`, `OWNER_DISCORD_ID` (IDs separados por vírgulas), `ALLOWED_DISCORD_IDS` (leitores). A stack tem os donos `376768118535749633,723613831196311603`; um dono mantém o perfil mesmo que esteja nas duas listas.
|
|
|
|
Discord: adicionar redirect exato `APP_URL/auth/discord/callback`. O **Dono** configura/guarda/executa; o **Leitor** consulta, com controlo no backend. As credenciais TeamSpeak determinam as ações aceites pelo servidor.
|
|
|
|
`http://teamspeak6:10080` funciona numa rede Docker partilhada que resolve o nome; também podes usar a porta publicada no IP da máquina. Testar a ligação e simular antes de ativar.
|
|
|
|
## Persistência e validação
|
|
|
|
SQLite mantém o formato dos flows anteriores. API keys, passwords SSH e campos secretos são cifrados com AES-GCM. Preservar **todo o volume**, incluindo `credentials.key`, nas cópias de segurança. Histórico: 500 execuções. Encerramento cancela trabalhos antes de fechar a base de dados; interrupções abruptas são assinaladas no arranque.
|
|
|
|
Node 22.15+: `npm ci --ignore-scripts`, `npm start`, `npm test`. Testes abrangem autenticação, permissões, simulação de todos os blocos, payloads, foreach, cálculos, retries, erros, cancelamento, webhooks, armazenamento e compatibilidade. Servidores HTTP/SSH de teste verificam autenticação e notificações; ações administrativas não são executadas no TeamSpeak real. O editor é verificado em navegador desktop/móvel.
|
|
|
|
Voz/música, subflows/versionamento, gestão de perfis no painel e ranking histórico estão no [checklist](FLOW_CHECKLIST.md). Cada bot tem um flow com vários triggers. Voz precisa de identidade, protocolo e motor de áudio próprios.
|
|
|
|
Public Sans inclui licença OFL em `public/fonts`. Os logótipos conservam os ficheiros originais.
|