Manual do Painel de Indicadores

01O que o sistema faz

Toda segunda-feira às 7h, sozinho, sem ninguém apertar nada:

1. Abre a pasta Qualidade - Fontes do Motor no Google Drive
2. Lê todas as planilhas que estiverem lá dentro
3. Conta, soma e compara com a semana anterior
4. Pede a uma inteligência artificial para interpretar os números
5. Escreve um comentário nas linhas que parecem ter problema, dentro da própria planilha
6. Manda um e-mail com o resumo

Você não precisa preparar nada, nem padronizar planilha. O sistema descobre sozinho o que é cada coluna, mesmo que cada setor preencha de um jeito diferente.

02Os dois e-mails que você recebe

Toda segunda, ~7h — o relatório de indicadores

O assunto começa com uma destas três faixas — dá para triar sem abrir:

Dentro do e-mail, nesta ordem

• Resumo executivo — 3 a 5 frases. Se você só tiver 30 segundos, leia isto.
• Por planilha — quantos registros cada planilha teve e a variação em relação à semana passada: ▲ subiu, ▼ caiu, ■ estável. Cada nome é um link; clique e a planilha abre.
• Indicadores — os números da semana, em cartões.
• Achados — os problemas encontrados, com uma barra colorida indicando a gravidade.
• Ações recomendadas — o que fazer, em quanto tempo e por qual área. Nunca aparece nome de pessoa: notificação de qualidade não serve para apontar culpado.
• Linhas que exigem revisão manual — até 15 linhas específicas, com o número da linha, para você ir direto nelas.
• Qualidade do preenchimento — nota de 0 a 10 sobre o quão bem preenchidas estão as planilhas.

03O que aparece nas planilhas

Na primeira vez que o sistema analisa uma planilha, ele cria duas colunas novas no fim dela:

A célula do comentário fica colorida conforme a gravidade — as mesmas cores das faixas do e-mail:

04As três tarefas do dia a dia

4.1 · Incluir uma planilha nova na análise

Esta é a operação mais comum, e não precisa mexer em código. Abra a pasta de fontes e coloque a planilha lá:

Pasta “Qualidade - Fontes do Motor” ↗

Pronto: ela entra na próxima segunda-feira.

Você não precisa avisar ninguém, dizer quais são as colunas, nem padronizar nada.

4.2 · Tirar uma planilha da análise

• Simples: tire a planilha (ou o atalho) da pasta.
• Sem tirar da pasta: renomeie o arquivo pondo EXCLUIR no começo do nome.

O sistema pula qualquer arquivo cujo nome contenha EXCLUIR, Modelo, Teste, Rascunho, Arquivo morto, Cópia de, Financeiro ou Planilha sem título.

4.3 · Mudar quem recebe o e-mail

Esta precisa de uma mexida no código — uma linha só.

1. Abra o programa no Apps Script ↗
2. Na lista da esquerda, clique em 00_Config.gs
3. Aperte Ctrl+F e procure por destinatarios
4. Edite os e-mails, cada um entre apóstrofos e separados por vírgula
5. Ctrl+S para salvar

destinatarios: { to: ['ana@empresa.com.br', 'bruno@empresa.com.br'],
                 cc: ['diretoria@empresa.com.br'] },

05Rodar agora, sem esperar

Abra o programa no Apps Script, clique no arquivo na lista da esquerda e clique em ▶ Executar. Cada arquivo tem uma função só, então não precisa mexer em nenhum seletor.

Use sempre nesta ordem:

Os outros três arquivos

O resultado aparece embaixo, no painel Registro de execução.

06Quando algo dá errado

Primeiro lugar para olhar: a aba LOG da planilha de controle. Cada linha tem data, nível e mensagem. Procure por ERROR e WARN.

Abrir a planilha de controle ↗

Mensagens que são normais e não pedem ação

Problemas de verdade

07As chaves de API

O sistema usa inteligências artificiais gratuitas: chaves da Groq e do Google Gemini. Elas ficam guardadas nas configurações do projeto, nunca no código.

Onde ver ou trocar

1. Abra o programa → ⚙️ Configurações do projeto (engrenagem na barra da esquerda)
2. Role até Propriedades do script
3. Você verá duas linhas: GROQ_KEYS e GEMINI_KEYS
4. Para trocar: Editar propriedades do script → mude o valor → Salvar

Formato: as chaves na mesma linha, separadas por vírgula, sem espaço.

chave1,chave2,chave3

Quantas você quiser. Mais chaves significa mais capacidade — o sistema distribui a carga entre elas sozinho, escolhendo a cada momento a que tem mais folga.

Para ver quanto foi consumido hoje, rode a função relatorioChaves. Não gasta nada.

08Melhorar os comentários

Se os comentários vierem genéricos — “verificar dados”, “revisar registro” — o problema quase sempre é falta de contexto: o sistema não conhece o seu setor.

1. Abra 00_Config.gs
2. Procure por atencao: com Ctrl+F
3. Acrescente frases suas, no mesmo formato: texto entre apóstrofos, vírgula no fim

atencao: [
  'Descrição com menos de 15 palavras é insuficiente e deve ser apontada.',
  'Caso de alta severidade sem tratativa registrada é ALERTA CRÍTICO, sempre.',
  'Evento em UTI sem horário preenchido é problema, porque o turno importa.',
],

09O que o sistema não faz

Honestidade sobre os limites, para não haver surpresa:

• Não conserta planilha. Ele aponta o problema; corrigir é humano.
• Não lê arquivo Excel (.xlsx) solto no Drive. Só planilha do Google. Se tiver um .xlsx, abra e use Arquivo → Salvar como Planilhas Google.
• Não lê Formulário. Lê a planilha de respostas do formulário, que é o que interessa.
• Não lê mais de 30 planilhas por execução. Se a pasta passar disso, o log avisa e o excedente fica de fora.
• Analisa no máximo 5.000 linhas por aba (as mais recentes) e comenta no máximo 120 linhas por planilha por execução.
• Só olha os últimos 7 dias. Registro antigo não entra no recorte do período.
• Não garante acerto. É inteligência artificial: erra. O e-mail avisa isso no pé.
• Não substitui análise humana. Ele economiza o trabalho de olhar linha por linha; a decisão continua sendo sua.

10Glossário

11Onde fica cada coisa

12Rotina de manutenção

Pouca coisa, e nada urgente.

13Chamar ajuda técnica

Entregue estas quatro informações — elas resolvem a maior parte do diagnóstico:

1. O que você esperava e o que aconteceu
2. Print da aba LOG, nas linhas da data do problema
3. Print do Registro de execução no Apps Script, se rodou à mão
4. Se foi e-mail: print do e-mail, com o assunto visível

A documentação técnica fica na pasta do projeto: RESUMO_TECNICO.md traz a arquitetura e as decisões, e docs/IMPLANTACAO.md o passo a passo de instalação. Há também uma bateria de testes automatizados — node tests/rodar.js.