6.3 KiB
Coordenador GLPI
Automação n8n que analisa os chamados abertos no GLPI todo dia útil, classifica cada um com IA (contexto real do chamado, não só metadados) e envia no Slack os 10 chamados que realmente precisam de ação humana hoje.
O repositório tem duas gerações do workflow:
- V2 (
n8n/,logic/) — versão atual, em produção. Todo este README descreve o V2. - V1 (
Coordenador GLPI - Chamados Abertos Slack.n8n.json, na raiz) — versão legada, mantida apenas como rollback. Nunca foi importada nem ativada na instância n8n de produção; existe só como referência histórica e plano B.
Estado atual (verificado em 2026-08-25)
Workflow: [DEV] Coordenador GLPI - Chamados Abertos v2 (Shadow) (id y6JFEnp7Z2IJEUe2)
active: true
SEND_ENABLED: true
ENVIRONMENT: production
FORCE_SEND: false (execução manual nunca envia de verdade sem essa flag)
Schedule: seg-sex 08:00, timezone America/Sao_Paulo (cron "0 8 * * 1-5")
Testes: 171/171 (node --test)
O nome do workflow no n8n ainda carrega o prefixo histórico [DEV] /
(Shadow) — isso é só rótulo visual, não reflete mais o estado real (ativo,
SEND_ENABLED=true, ENVIRONMENT=production). Renomear é seguro a qualquer
momento, mas não foi feito para não gerar um diff de auditoria sem função.
Se essa seção estiver desatualizada, o estado de verdade é sempre o que o n8n
responde (n8n_get_workflow / n8n_manage_datatable), nunca este arquivo.
Arquitetura
GLPI (MySQL, somente leitura)
-> candidatos (pool configurável, sem corte artificial)
-> normalização de texto (decodifica HTML/entities do GLPI)
-> cache de classificação (Data Table, chave = hash do contexto + versão do classificador)
-> IA (OpenAI) classifica só quem mudou de contexto ou nunca foi analisado
-> score determinístico + seleção Top 10 com diversidade por grupo
-> guard de envio (SEND_ENABLED, FORCE_SEND, idempotência por hash da mensagem)
-> Slack (mensagem real, sem rodapé de atribuição do n8n)
-> shadow-diff contra a query legada do V1 (auditoria, não bloqueia envio)
Cada etapa grava em uma Data Table do n8n (coordenador_glpi_memoria,
coordenador_glpi_envios_digest, coordenador_glpi_shadow_runs) — não há
escrita nenhuma no banco do GLPI. Toda query GLPI é somente leitura; isso é
testado (tools/build-workflow.test.js varre sql/*.sql e o SQL gerado
procurando INSERT/UPDATE/DELETE/ALTER/DROP/CREATE/TRUNCATE).
Por que a IA classifica o chamado, não só pontua
Cada chamado recebe uma classificação semântica (ACTIONABLE_NOW,
UNASSIGNED_ACTIONABLE, WAITING_REQUESTER, WAITING_VENDOR,
WAITING_APPROVAL, SCHEDULED, DEPENDENCY_BLOCKED, NEEDS_COORDINATION,
PROJECT_LONG_TERM, DUPLICATE_OR_OBSOLETE, INSUFFICIENT_CONTEXT) mais um
next_action concreto (nunca frases genéricas tipo "revisar chamado" — isso é
validado e rejeitado, ver logic/classification.js). O prompt
(n8n/nodes/prepare-ai-prompt.node.js) trata cronologia dos apontamentos como
obrigatória e distingue "precisa contatar alguém" (acionável agora) de "já
contatou e está esperando resposta" (WAITING_*).
Determinismo do Top 10
logic/diversity.js desempata candidatos com score igual por ticket.id
(ascendente) — sem isso, ordens de chegada diferentes entre execuções
produziam Top10 diferentes para o mesmo dia, o que já causou um envio real
duplicado em teste (ver docs/superpowers/notes/2026-08-25-relatorio-correcao-final.md,
seção 5). Regressão coberta em logic/diversity.test.js.
Arquivos
logic/*.js Lógica pura, testável com node:test (sem I/O, sem n8n)
n8n/nodes/*.node.js Drivers finos que rodam dentro de Code nodes do n8n
(cabeçalho "// @requires a.js b.js" declara quais
módulos de logic/ precisam ser inlinados)
n8n/workflow.template.json Fonte de verdade da estrutura do workflow
(marcadores __BUILD__:arquivo.js são substituídos
pelo conteúdo de logic/ na hora do build)
n8n/deployed/coordenador-glpi-v2.n8n.json Artefato gerado, importável no n8n
tools/build-workflow.js Inlina logic/ + n8n/nodes/ dentro do template
tools/build-workflow.test.js Regressões de build (dependência transitiva,
alwaysOutputData, columns.mappingMode, etc.)
sql/ Queries GLPI usadas como referência/validação manual
docs/superpowers/ Specs, planos e relatórios de execução (histórico,
não é para reescrever — cada nota é um registro de
um momento específico do projeto)
Build
node tools/build-workflow.js
node --test
O build só precisa rodar de novo quando logic/*.js, n8n/nodes/*.node.js ou
n8n/workflow.template.json mudarem. O artefato gerado
(n8n/deployed/coordenador-glpi-v2.n8n.json) não é a fonte de verdade do
ambiente de produção — o workflow ativo no n8n foi promovido diretamente via
API (n8n_update_partial_workflow) e hoje diverge do template em 3 valores de
configuração de propósito:
| campo | template (default de deploy limpo) | live (produção) |
|---|---|---|
ENVIRONMENT |
dev |
production |
SEND_ENABLED |
false |
true |
FORCE_SEND |
false |
false |
Isso é intencional: o template continua "seguro por padrão" para qualquer
reimportação futura (nunca envia sozinho), e a promoção para produção é um ato
explícito e auditável via n8n_update_partial_workflow, não algo que um
rebuild acidental possa reverter. Se um dia o workflow live for recriado do
zero a partir do template, repita a promoção manualmente (ver comando na nota
2026-08-25-relatorio-finalizacao-producao.md).
Rollback
O V1 (Coordenador GLPI - Chamados Abertos Slack.n8n.json) nunca foi
importado no n8n de produção — não há nada para "reverter para V1", ele
continua disponível como plano B caso seja necessário abandonar o V2. Para
desativar o V2 sem tocar em nada mais: SEND_ENABLED=false no node
Config - Coordenador GLPI v2 e/ou desativar o workflow.
Credenciais e segredos
Nenhum segredo vive neste repositório. Tudo (Slack bot token, OpenAI API key,
credencial MySQL do GLPI) é gerenciado pelo credential store do próprio n8n e
referenciado nos nodes só por {id, name}.