Runbook - Scripts Playwright e CDP do Sagazchat

Índice operacional dos scripts locais usados para auditar, validar e operar partes do Sagazchat. Esta nota deve ficar junto aos runbooks porque os scripts explicam como vários endp

8 min de leitura Atualizado em 15 de mai. de 2026

Índice operacional dos scripts locais usados para auditar, validar e operar partes do Sagazchat. Esta nota deve ficar junto aos runbooks porque os scripts explicam como vários endpoints e comportamentos da UI foram descobertos.

Fonte canônica

Código dos scripts:

<repo>/central_de_ajuda/scripts/sagaz-*.mjs

Dependência principal:

<repo>/central_de_ajuda/node_modules/playwright

Regra: o código executável continua no repo; o vault documenta finalidade, risco, entrada/saída e scripts validados. Se um script virar parte estável de setup/produção, também deve ser citado no runbook específico do módulo em uma seção Scripts validados.

Regra de segurança

Scripts do Sagazchat podem operar conta real. Tratar por nível de risco:

Risco	Exemplos	Regra
Baixo	listagem, screenshot, inspeção, mapeamento	Pode rodar para auditoria se usar conta correta.
Médio	criar etiquetas, departamentos, respostas rápidas, variáveis globais	Fazer `GET` antes, deduplicar por nome, validar depois.
Alto	salvar fluxo, ativar fluxo padrão, horários, campanha, webhook, envio de mensagem	Fazer backup antes e pedir confirmação explícita antes de persistir/ativar.

Nunca colar JWT/token no chat. Usar sessão local, localStorage.token do navegador logado ou variáveis de ambiente temporárias. Não versionar storage-state.json, screenshots sensíveis ou payloads com credenciais.

Inventário por família

Levantamento em 2026-05-15 na pasta scripts/:

Família	Qtde	Uso típico
`sagaz-fluxos-*`	53	abrir, criar, mapear, capturar blocos e validar flowbuilder.
`sagaz-estetica-*`	78	fluxo real/lab de estética; manipulação de nós, menu, etiquetas, salvamento e reconexões no canvas.
`sagaz-venda-*`	24	fluxo de venda/qualificação; iterações, salvamento e verificação.
`sagaz-webhooks-*`	20	mapear, salvar, ativar, validar e inspecionar webhooks.
`sagaz-kanban-*`	21	criação, colunas, cards, regras e validação de Kanban.
`sagaz-agenda-*`	17	criar calendário, configurar horários, bloquear dias e vincular agenda em fluxo.
`sagaz-validate-*`	18	validações específicas do Bate Papo e comportamentos de UI.
`sagaz-audit-*`	22	auditoria visual/funcional do Bate Papo.
`sagaz-horarios-*`	13	mapear/salvar configuração de fora de horário e ação por fluxo/mensagem.
`sagaz-flowdefault-*`	6	mapear, alterar e reverter Fluxo padrão. Alto risco.
`sagaz-assistentes-*`	6	listar, criar, inspecionar e configurar assistentes IA.
`sagaz-dept-` / `sagaz-departamentos-`	7	mapear, criar e limpar departamentos.
`sagaz-tags-*`	3	mapear, criar e inspecionar etiquetas.
`sagaz-respostas-*`	5	mapear, criar e limpar respostas rápidas.
`sagaz-remarketing-*`	7	criar/inspecionar remarketing e etapas.
`sagaz-conexoes-` / `sagaz-conexao-`	5	listar/mapear conexões e kebab de canais.
`sagaz-perfil-*`	6	mapear/editar perfil e permissões avançadas.
`sagaz-config-` / `sagaz-settings-`	8	sidebar de configurações, plano e empresa/settings.
`sagaz-api-*`	3	mapear tela de API/mensagens e screenshots.
`sagaz-login.mjs`, `sagaz-session.mjs`, `sagaz-ping-cdp.mjs`	3	login, sessão persistente e conexão CDP.
Outros pontuais	20+	probes, screenshots, render checks, transmissões, campanhas, campos, audiência, dashboard.

Reutilização de sessão sem relogin [validado 2026-05-15]

Para evitar login repetido em sequências de scripts, usar dois arquivos de saída:

Arquivo	Conteúdo	Uso
`scripts/_out/{cliente}-token.txt`	JWT Bearer puro	Headers de API (`Authorization: Bearer <token>`)
`scripts/_out/{cliente}-session.json`	`storageState` do Playwright	`browser.newContext({ storageState })`

Padrão de reutilização de token:

const TOKEN_F = 'scripts/_out/auto-center-exemplo-token.txt';
let token;
if (existsSync(TOKEN_F)) {
  token = readFileSync(TOKEN_F, 'utf8').trim();
  const test = await ctx.get('/users/me', { headers: { Authorization: `Bearer ${token}` } });
  if (test.status() !== 200) token = null;  // expirou, relogar
}
if (!token) {
  const r = await ctx.post('/auth/login', { data: { email, password } });
  ({ token } = await r.json());
  writeFileSync(TOKEN_F, token, 'utf8');
}

Padrão de reutilização de sessão browser:

const SESSION_F = 'scripts/_out/auto-center-exemplo-session.json';
if (existsSync(SESSION_F)) {
  const bCtx = await browser.newContext({ storageState: SESSION_F, viewport: { width: 1440, height: 900 } });
  // ... ir para a URL. Se não redirecionar para /login, sessão ainda válida.
}
// Após login fresh, salvar:
await bCtx.storageState({ path: SESSION_F });

Script gerador: sagaz-session-save.mjs (salva token + storageState de uma vez).

Scripts-base para sessão

`sagaz-login.mjs`

Faz login em https://app.sagazchat.com/login usando:

SAGAZ_EMAIL
SAGAZ_PASSWORD

Gera screenshot pós-login em scripts/_out/post-login.png. Útil para validar credenciais e estado inicial.

`sagaz-session.mjs`

Abre browser com remote debugging, salva scripts/_out/state.json e expõe endpoint CDP em scripts/_out/cdp.txt. Scripts posteriores podem conectar nessa sessão sem relogar.

Risco: mantém sessão aberta. Fechar ao terminar e não compartilhar state.json.

`sagaz-ping-cdp.mjs`

Valida se a sessão CDP está acessível. Usar antes de scripts em fases.

Scripts de fluxo

Flowbuilder geral

Exemplos:

sagaz-fluxos-list.mjs
sagaz-fluxos-criar.mjs
sagaz-fluxos-abrir.mjs
sagaz-fluxos-state.mjs
sagaz-fluxos-paleta.mjs
sagaz-fluxos-screenshots-blocos.mjs
sagaz-fluxos-screenshots-construtor.mjs
sagaz-fluxos-conteudo-tipos.mjs
sagaz-fluxos-openai*.mjs

Uso: abrir builder, listar fluxos, criar fluxo, mapear blocos, capturar screenshots e entender payloads.

Regra: antes de salvar fluxo real, fazer backup com GET /flowbuilder/flow/{id} e preservar campos desconhecidos.

Fluxos reais/lab existentes

Exemplos:

sagaz-fluxos-petshop-*.mjs
sagaz-estetica-*.mjs
sagaz-venda-*.mjs
sagaz-lab-blocos-sem-ia-*.mjs

Uso: iterações específicas de fluxos já construídos ou usados como laboratório. Não tratar como template genérico sem revisar ids, textos, nós e conexões.

Scripts por módulo

Departamentos

sagaz-departamentos-mapear.mjs
sagaz-dept-criar-lab.mjs
sagaz-dept-continuar.mjs
sagaz-dept-cleanup.mjs

Relacionar com departamentos.

Etiquetas

sagaz-tags-mapear.mjs
sagaz-tags-inspect.mjs
sagaz-tags-criar-lab.mjs

Relacionar com etiquetas.

Respostas rápidas

sagaz-respostas-mapear.mjs
sagaz-respostas-inspect.mjs
sagaz-respostas-criar-lab.mjs
sagaz-respostas-continuar.mjs
sagaz-respostas-cleanup.mjs

Relacionar com respostas-rapidas.

Fluxo padrão

sagaz-flowdefault-mapear.mjs
sagaz-flowdefault-canal.mjs
sagaz-flowdefault-locator.mjs
sagaz-flowdefault-salvar.mjs
sagaz-flowdefault-salvar-amplo.mjs
sagaz-flowdefault-reverter.mjs

Relacionar com fluxo-padrao. Alto risco: PUT /flowdefault muda disparadores automáticos para cliente real.

Horários

sagaz-horarios-mapear.mjs
sagaz-horarios-canal*.mjs
sagaz-horarios-salvar*.mjs
sagaz-horarios-acao-fluxo.mjs
sagaz-horarios-cleanup-completo.mjs

Relacionar com horarios. Alto risco quando altera ação fora de horário.

Webhooks

sagaz-webhooks-check.mjs
sagaz-webhooks-ciclo.mjs
sagaz-webhooks-detalhe*.mjs
sagaz-webhooks-save*.mjs
sagaz-webhooks-finalizar*.mjs

Relacionar com webhooks. Alto risco quando ativa webhook ou dispara fluxo.

Kanban

sagaz-kanban-create.mjs
sagaz-kanban-criar-colunas.mjs
sagaz-kanban-card*.mjs
sagaz-kanban-validar*.mjs
sagaz-kanban-cleanup.mjs

Relacionar com kanban. Alguns scripts são UI-first porque o contrato de API ainda não está consolidado.

Agenda

sagaz-agenda-create.mjs
sagaz-agenda-configure-*.mjs
sagaz-agenda-bloquear-dias.mjs
sagaz-agenda-vincular-flow-539.mjs

Relacionar com fluxos e futura nota específica de agenda, se o módulo for separado.

Assistentes IA

sagaz-assistentes-listar.mjs
sagaz-assistentes-ia-create-lab.mjs
sagaz-assistentes-ia-configure-lab.mjs
sagaz-assistentes-ia-inspect.mjs
sagaz-vincular-assistente.mjs

Relacionar com assistentes-ia. Alto risco quando vincula assistente a canal real.

Bate Papo e validações

sagaz-audit-*.mjs
sagaz-validate-*.mjs
sagaz-composer-*.mjs
sagaz-probe-chat.mjs

Relacionar com bate-papo. Evitar envio real de mensagem fora de número de teste.

Padrão recomendado para novos scripts

Prefixar com sagaz-{modulo}-{acao}.mjs.
Ler credenciais/sessão por variável de ambiente ou state local, nunca hardcoded.
Gravar outputs em scripts/_out/.
Logar ações com prefixo estável ([modulo] ação).
Se for modificar conta real, ter modo de auditoria/listagem antes do modo write.
Se salvar/ativar disparador, gerar backup antes.
Atualizar esta nota e o runbook do módulo após validar.

Setup de clientes via API

Auto Center Exemplo (conta: contato@exemplo.com)

Scripts específicos para este cliente:

Script	Propósito	Risco
`sagaz-auto-center-exemplo-api-setup.mjs`	Criou departamentos, etiquetas, respostas rápidas	Médio
`sagaz-auto-center-exemplo-flow-complete.mjs`	Fluxo completo com 25 nós, stopFlow para coleta de dados	Alto
`sagaz-session-save.mjs`	Salva token + storageState para reutilização	Baixo

Fluxo “Exemplo - Menu Principal” (id 561) — estrutura atual [2026-05-15]:

6 opções no menu principal
Coleta dados antes de rotear: modelo/ano (Film e Funilaria), película existente (Film), particular/seguro+CIA (Funilaria), placa/sinistro (Agendamento)
Sub-menu “Outras informações” com endereços, horários, pagamento/PIX e falar com atendente
PIX: contato@exemplo.com (Loja) e CNPJ 00.000.000/0001-00 (Oficina)

Departamentos:

ID	Nome	Responsável
162	Comercial Loja	Atendente 4
161	Comercial Oficina	Convidado
163	Agendamento/Status Oficina	Atendente 5
164	Pós-venda/SAC	Atendente 3
165	Financeiro/Fornecedores	Atendente 6

Etiquetas:

ID	Nome
779	lead_loja
777	lead_oficina
778	cliente_seguradora
783	agendamento_status
780	cliente_pos_venda
782	assunto_financeiro
776	cliente_ativo

Pendente

Separar scripts de laboratório antigos dos scripts realmente reutilizáveis.
Marcar explicitamente quais scripts já são seguros para setup de cliente.
Criar uma tabela curta por runbook com script, modo, risco, input, output.

Relacionado

2026-05-11 - Sagazchat - Runbooks da plataforma
2026-05-14 - Sagazchat - API interna de uso da plataforma
fluxos
fluxo-padrao
webhooks