# Cadastro do dashboard no banco compartilhado

Os botões **Novo Cliente** do dashboard e da lista de clientes usam o mesmo formulário e gravam na tabela `clients` existente do gerador. O dashboard e a lista consultam esse banco a cada sete segundos; não carregam mais os clientes de demonstração ou usam o armazenamento local como fonte principal.

O cadastro grava o cliente, copia o template global 9 para `templates`, registra o histórico operacional e, quando fornecida, grava a lista em `keywords`. Essas etapas acontecem em uma única transação. Um template ausente ou vazio impede a criação de um cadastro parcial. O cadastro principal do master não depende da aba do gerador para ser salvo; os controles de geração da área Gerador continuam usando `master_commands`.

O frontend guarda uma chave antes de enviar cada cadastro. Reenviar o mesmo cadastro após falha de conexão recupera o ID original e não cria outro cliente. O popup de sucesso só aparece após a confirmação da transação, permanece cinco segundos e recarrega a página na mesma área do master.

## Colunas adicionadas em clients

| Campos da interface | Colunas |
| --- | --- |
| Etapa | `master_status` |
| Segmento e responsável | `segment`, `responsible` |
| Entrada e onboarding | `entry_date`, `has_onboarding`, `onboarding_date` |
| Briefing | `briefing_date` |
| Envio e aprovação das palavras-chave | `keyword_sent_date`, `keyword_approval_date` |
| Criticidade e motivo | `criticality`, `criticality_reason` |
| Total informado e origem do total | `keywords_total_manual`, `keywords_total_source` |
| Observações | `general_notes` |
| Datas operacionais do master | `master_created_at`, `master_updated_at` |
| Arquivamento no master | `master_archived_at` |

As colunas foram adicionadas como nullable para preservar os registros anteriores. Datas antigas ausentes não recebem horários inventados. O nome utiliza a coluna `name` já existente; contexto, WhatsApp e templates atuais são preservados nas edições operacionais. Nome, etapa, datas, criticidade, motivo, total e observações do formulário ficam no banco.

O comando separado `npm.cmd run setup:clients` inicializa apenas essas colunas e as tabelas novas `master_client_requests` e `master_client_history`. Ele já foi executado neste ambiente e não roda durante o startup. Nenhuma tabela existente foi recriada ou esvaziada.

## Palavras-chave

No formulário, escolha a origem do total:

- **Manual:** grava o número informado em `keywords_total_manual`.
- **Lista:** conta os textos únicos da lista ativa em `keywords`, sem duplicatas exatas ou espaços excedentes. A lista pode ser cadastrada neste formulário ou no gerador. Alterações feitas no gerador aparecem nas próximas consultas do dashboard.

**Atualizadas** é a quantidade de palavras únicas com pelo menos um texto gerado. A leitura utiliza `generation_files` e os índices confirmados em `completed_json` relacionados ao plano `items_json` dos jobs existentes, incluindo histórico. Uma palavra com várias regiões, arquivos ou versões conta somente uma vez. Quando há lista ativa, a contagem considera as palavras dessa lista. No modo manual sem lista ativa, usa as palavras identificáveis no histórico de geração.

Não é usado `generated_count` como se fosse uma contagem de palavras: esse campo conta páginas. Os contadores de palavras geradas não aceitam edição pelo formulário ou pela API operacional. O restante é `max(0, total - atualizadas)`. Progresso antigo sem arquivos persistidos ou índices/plano identificáveis não permite recuperar quais palavras foram geradas; o sistema não inventa essas palavras.

Os nomes das palavras do plano são carregados uma vez por job e mantidos em cache; templates e conteúdo das páginas não são carregados no polling. A lista completa de palavras de um cliente só é enviada ao frontend ao abrir sua edição.

Substituir uma lista ativa desativa os registros anteriores, sem apagá-los. Edições de listas não mudam o plano nem o progresso de um job existente.

## Histórico e ações

Notas e alterações operacionais são persistidas em `master_client_history`. Os dados anteriores às edições são preservados nos eventos. O histórico de comandos e revisões do gerador permanece separado e intacto.

A ação **Excluir Cliente** preenche `clients.deleted_at` com a data UTC e também mantém `master_archived_at` por compatibilidade. Oculta o cliente nas listas e filas exibidas pelo master, bloqueando edição e novos comandos. Preserva dados e arquivos. O gerador deve implementar o filtro compartilhado e a interrupção segura descritos em [EXCLUSAO-CLIENTES.md](EXCLUSAO-CLIENTES.md).

A ação de geração da lista abre o cliente na área **Gerador**, que consulta o progresso e controla a fila real. Não há gravação manual de contadores de geração nesse fluxo.

Os clientes locais anteriores permanecem no navegador. Eles não são importados automaticamente, pois incluem dados de demonstração e não podem ser associados aos IDs do gerador pelo nome.

## Permissões e validação

A conta de operação do master precisa ler as tabelas compartilhadas, inserir clientes/templates e inserir ou atualizar listas e campos operacionais. Também precisa de SELECT/INSERT/UPDATE nas duas tabelas novas. A criação das colunas usa uma conta com permissão de administração somente na configuração inicial.

Testes automatizados verificam validação, reenvio idempotente, template obrigatório, contagem por palavra e atualização do progresso. O cadastro, a edição parcial, a cópia do template e o reenvio também foram conferidos no MySQL real dentro de uma transação revertida: nenhum cliente ou solicitação de teste permaneceu gravado. Nenhum arquivo do projeto do gerador foi alterado nesta etapa.
