# Google Sheets

O servidor sincroniza a cada 60 segundos a aba `Clientes Master`, usando somente A:G: Cliente, Criticidade, Palavras totais, Palavras geradas, Palavras restantes, Máquina usada e Posição na fila. A posição acompanha a mesma consulta da tela Gerador, contando separadamente por máquina. Um cliente em várias filas mostra cada máquina e sua posição; clientes sem fila mostram `Fora da fila`.

O banco é a fonte dos dados. A aba é exclusiva para sincronização: valores manuais em A:G serão substituídos; outras abas e colunas são preservadas. Clientes excluídos saem da planilha na próxima sincronização. Textos são enviados como strings literais, sem executar fórmulas vindas dos nomes de clientes.

Clientes Master tem cabeçalho laranja, primeira linha e coluna congeladas, filtros, linhas alternadas, números formatados e cores de criticidade. A formatação de A:G é gerenciada a cada sincronização para acompanhar clientes novos e mudanças de criticidade.

A aba **Dashboard Máquinas** mostra seções por máquina, com o nome acima da fila. Cada seção apresenta posição, cliente, status, páginas totais, geradas, restantes e páginas por rodada. Máquinas ativas sem jobs mostram `Fila vazia`. Máquinas inativas com jobs também aparecem. A ordem vem da mesma consulta da tela Gerador, incluindo a ordem salva por arraste.

As duas abas recebem dados no mesmo `batchUpdate` a cada sincronização, a partir da mesma leitura de clientes e fila. O dashboard tem layout gerenciado pelo sistema em A:G; valores, formatação e mesclagens nessa área são recriados automaticamente. Outras abas não são alteradas.

A aba **Dashboard Etapas** também participa da mesma sincronização. Cada etapa mostra seu título, total de clientes e uma lista dos nomes em ordem alfabética. Inclui Apontamento e Traqueamento após Publicação, além de Performando, Site e Pausado. Mudanças de fase transferem o cliente de seção na próxima atualização; etapas vazias são identificadas.

A tag Site é independente da fase (`clients.master_site_tag`). Quando ativa, o nome aparece como `Cliente · SITE` nas três abas, com destaque laranja. Remover a tag elimina esse destaque na próxima sincronização. Site não é mais uma seção de etapa; a antiga fase Pausado aparece como Aviso.

## Ativação

1. No Google Cloud, crie/selecione um projeto, habilite **Google Sheets API** e crie uma conta de serviço.
2. Crie uma chave JSON da conta de serviço e salve localmente em `.data/google-service-account.json`. Não envie a chave no chat. `.data` está fora do Git.
3. Compartilhe a planilha com o e-mail `client_email` da conta de serviço, com acesso de **Editor**. A conta não precisa de acesso ao MySQL nem de delegação de domínio.
4. Configure no `.env`:

```dotenv
GOOGLE_SHEETS_ID=1I23z8YNmmRG9BVUEZi6bWcU87tLSZhqmJrGG3M4qlfU
GOOGLE_SHEETS_TAB="Clientes Master"
GOOGLE_SHEETS_CREDENTIALS_FILE=".data/google-service-account.json"
```

5. Reinicie o Master. A primeira sincronização ocorre ao iniciar; as demais, a cada minuto.

O endpoint local `/api/master/google-sheets/status` informa a última tentativa, último sucesso e falha, sem expor credenciais. Uma falha não interrompe o sistema nem grava dados incompletos na planilha. A próxima tentativa acontece no minuto seguinte. Chamadas não se sobrepõem.

O intervalo normal é inferior ao limite solicitado de 30 minutos. A atualização depende do servidor Master ligado, conexão com internet, acesso ao MySQL e disponibilidade/permissões do Google. Não é possível garantir o limite durante uma indisponibilidade desses serviços.

Referências: [contas de serviço](https://developers.google.com/identity/protocols/oauth2/service-account) e [batchUpdate](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate).
