Gestão de Estado & Hidratação (Zustand & TanStack Query)
Gestão de Estado & Hidratação (Zustand & TanStack Query)
Section titled “Gestão de Estado & Hidratação (Zustand & TanStack Query)”Estado actual — sincronização compartilhada. Um WebSocket autenticado (/api/live) reutiliza o ChatChannelDO com hibernação para avisos sem registros, IDs de pessoas ou valores. Gravações aceitas incrementam revisões por domínio; o boot lê o marco antes do snapshot e cada conexão recebe o marco atual para recuperar lacunas. Mudanças próximas são agrupadas (750 ms, no máximo uma atualização a cada 5 s), e cada sessão espera ainda um sorteio de até 3 s (spread): todas recebem o mesmo aviso no mesmo instante e, juntas, releriam a janela operacional no mesmo segundo — em 8/11/2026 isso estourou o limite de 10 s do D1 e derrubou um save; somente consultas afetadas e ativas refazem a leitura, as inativas ficam invalidadas. Operações mantém sua leitura de segurança a cada 5 minutos somente sem relay comprovadamente responsivo; a perda da conexão preserva esse fallback, e uma sessão antiga não altera a saúde da nova. Uma conexão saudável responde ao keepalive a cada 10 s no runtime, sem consultar D1; perda do socket usa a API leve de revisões e tenta reconectar, sem recarregar listas quando os marcos não mudaram. Segundo plano, logout e troca de conta encerram socket, timers e leituras pendentes. O objetivo de até 15 s pressupõe rede/API disponíveis; não é promessa durante indisponibilidade.
Estado actual — custo e concorrência da hidratação. Leituras conservam referências de linhas e configurações idênticas, evitando reconstruir quadros, índices e cálculos por uma recarga sem mudanças. Uma leitura iniciada antes de uma edição, criação ou remoção local não desfaz essa alteração; avisos remotos aguardam gravações locais e consultas de listas recebem cancelamento. Billing reutiliza as invoices do boot e da sincronização ao entrar; relatórios só buscam os períodos de estatísticas enquanto essa aba está ativa. O chat conserva seu transporte próprio; digitação, telemetria e GPS não disparam recarga operacional global. Alterações diretas no banco, fora dos handlers, exigem recarga explícita.
Estado actual — cadastro de clientes. E-mail omitido numa gravação preserva o existente; vazio ou nulo limpa para NULL, permitindo salvar preços e outros campos de vários clientes sem e-mail sem conflito de unicidade. O perfil confirma o salvamento com toast somente após aceite do servidor e, quando aplicável, conclusão da conversão do lead.
O Prime Crown utiliza uma arquitetura híbrida de gerenciamento de estado desenhada para eliminação de re-renders desnecessários e sincronização transparente com o banco de dados.
O salvamento do Perfil possui lock síncrono antes das gravações de cliente/funcionário e epoch vinculado ao usuário autenticado. As duas persistências ainda podem executar em paralelo, mas somente o lifecycle que as iniciou atualiza o idioma da sessão, mostra sucesso ou encerra loading; troca de conta não recebe feedback nem estado de uma gravação anterior.
As leituras de recuperação do estado e as mutações compartilhadas de requests, configurações, onboarding e séries recorrentes separam diagnóstico de resposta. O servidor registra exceções sanitizadas por domínio e devolve uma mensagem estável nas oito saídas de falha total. Quando um snapshot ou grupo de configurações falha parcialmente, errors[] conserva somente label e id para orientar o retry; a mensagem do D1, do Resend ou de outro provedor nunca atravessa para PWA, desktop, Android ou iOS. Validação, autenticação, autorização e IDs funcionais continuam específicos.
⚡ 1. Arquitetura de Sincronização de Estado
Section titled “⚡ 1. Arquitetura de Sincronização de Estado”sequenceDiagram
autonumber
actor User as Usuário
participant UI as Componente React
participant Query as TanStack Query Cache
participant Store as Zustand Store (Derived View)
participant Sync as syncAtomic / EntitiesApiClient
participant D1 as Cloudflare D1 DB
Note over UI, D1: Boot Inicial (/api/boot)
UI->>Query: bootData loaded via /api/boot
Query->>Store: useStoreQuerySync (Projeta cache no Zustand)
Store-->>UI: Re-renderiza apenas seletores específicos
Note over UI, D1: Mutação com Atualização Otimista
User->>UI: Executa ação (ex: Alterar Status de Agendamento)
UI->>Store: Aplicação Imediata de Update Otimista
UI->>Sync: Disparo Assíncrono para /api/atomic/*
Sync->>Query: Espelha alteração no Cache do TanStack Query
Sync->>D1: Persistência Atômica no D1
alt Sucesso no Banco
D1-->>Sync: OK 200
else Falha no Banco
D1-->>Sync: Erro 500
Sync->>UI: Exibe Toast "Sync Failed" e Reverte Estado
end
📦 2. Estrutura dos Zustand Stores (src/stores/*)
Section titled “📦 2. Estrutura dos Zustand Stores (src/stores/*)”Para evitar re-renders globais que afetavam a performance antiga do React Context, o estado da aplicação é fatiado nas seguintes stores Zustand:
| Store | Arquivo | Responsabilidade |
|---|---|---|
requestsStore.ts |
src/stores/requestsStore.ts |
Coleção de solicitações de serviço, agendamentos e faturas. |
entityStore.ts |
src/stores/entityStore.ts |
Entidades base do sistema (Clientes, Funcionários, Serviços, Entidades Fiscais, Leads, cotações de leads e Addons). |
payrollStore.ts |
src/stores/payrollStore.ts |
Lançamentos de folha de pagamento, fecho de períodos e saldos de Reserva de Caixa (Cash Reserve). |
systemStore.ts |
src/stores/systemStore.ts |
Configurações globais do sistema, regras de cancelamento e logs de auditoria. |
appStatusStore.ts |
src/stores/appStatusStore.ts |
Status de conexão da aplicação, banner PWA e notificações não lidas. |
leadQuotes é hidratado por /api/boot: ADMIN/MANAGER recebem a fila operacional e uma conta referenciada como LEAD recebe apenas suas próprias cotações. useLeadQuotes e useOpenLeadQuoteCount expõem seletores estreitos. Criar/atualizar uma intenção pelo ClientQuoteWizard (cliente ou lead) faz upsertLeadQuote; confirmar ou recusar substitui o registro autoritativo, sem representar a cotação como service_request provisório.
requestsStore calcula alterações individuais e em lote a partir de um snapshot síncrono, publica a nova coleção uma única vez e somente depois chama syncAtomic. Persistência nunca ocorre dentro do updater Zustand: middleware ou instrumentação não podem repetir o request, e um batch envia exatamente uma gravação para cada tarefa realmente alterada.
Para várias alterações rápidas da mesma tarefa, syncAtomic preserva a ordem de gravação e mantém a projeção otimista no cache TanStack até a última resposta da fila. A invalidação/releitura ocorre uma única vez no ponto de convergência (inclusive se houver recusa), evitando que a confirmação da primeira alteração recoloque no Zustand um snapshot anterior enquanto a próxima ainda aguarda persistência. A fila também captura a geração da sessão: uma edição pendente da conta que saiu não começa sob o cookie da próxima conta, não bloqueia um ID coincidente da nova sessão e não invalida o cache recém-hidratado. A regra é compartilhada pelos shells web, PWA, Android e iOS porque pertence à camada TypeScript comum.
O gate de pureza percorre tanto setters React (setX) quanto o set minúsculo do Zustand. A recarga de carteira também calcula seu cliente atualizado dentro do updater, mas inicia a persistência somente depois da publicação; uma reinvocação de cálculo nunca duplica crédito ou request.
🔒 3. Estado local por conta
Section titled “🔒 3. Estado local por conta”Dados operacionais nunca usam Web Storage: estado offline e histórico de alertas ficam em IndexedDB, enquanto o servidor/D1 continua sendo a fonte de verdade. Preferências exclusivamente visuais podem usar localStorage, mas chaves associadas a uma conta passam por opaqueStorageMarker com namespace próprio. Preferências de som, posição e categorias de notificação usam notif_prefs_v2_<marker>; a leitura migra notif_prefs_v1_<userId> e remove a chave antiga sem perder a configuração. Esse marcador evita IDs legíveis no armazenamento inspecionável da PWA/WebView, mas não é criptografia e nunca deve guardar tokens ou segredos.
No logout, impersonação ou troca de identidade, o cache autenticado do TanStack é destruído de forma síncrona. O próprio QueryClient.clear() cancela e remove as queries; portanto a limpeza não aguarda uma promessa de cancelamento anterior. Isso impede que uma limpeza atrasada de uma conta antiga apague o boot recém-semeado pela conta seguinte.
CloudClient aplica a mesma fronteira aos requests e ao refresh de sessão. Cada chamada captura uma geração e é abortada quando a identidade muda; o refresh compartilhado só limpa a si próprio se ainda for o refresh em voo daquela geração. Assim um refresh lento da conta anterior não pode nem repetir uma leitura com o cookie novo nem apagar o single-flight que já protege a nova sessão contra refreshes duplicados. Repetição automática pertence apenas a GET: POST/PUT/PATCH/DELETE e multipart não são refeitos após rede/5xx ambíguos, evitando duplicar efeitos externos; qualquer recuperação de escrita exige a chave de idempotência do domínio.
Esse transporte também é obrigatório nas leituras e mutações autenticadas de superfícies auxiliares — Perfil, catálogo de carpetes, fila de exclusão, telemetria administrativa e QuickBooks. Elas recebem assim o mesmo cancelamento e a mesma geração das áreas centrais, sem permitir que uma resposta ou ação iniciada pela conta anterior alcance a conta seguinte.
No Android, essa fronteira também alcança entradas criadas pelo sistema: banners, ações de conversa e atalhos dinâmicos do launcher carregam a prova do destinatário. Assim um atalho persistido por uma conversa antiga não pode navegar a conta seguinte para aquele canal durante a limpeza assíncrona do shell.
No service worker, essa audiência também autoriza a recuperação automática de uma assinatura Web Push rotacionada pelo navegador. O evento de rotação ainda avisa as abas abertas, mas após logout — quando a audiência é removida antes da revogação do cookie — ele não cria nem salva um endpoint substituto. Isso evita que uma corrida de rede readicione no servidor a assinatura da conta que acabou de sair.
A seleção do Inbox pertence à mesma fronteira: uma troca de conta limpa imediatamente canal selecionado, detalhe mobile e filtro, além do marcador de conversa ativa usado pelo Android para suprimir somente a notificação da thread aberta. Assim impersonação, logout seguido de login e troca de conta não conservam uma conversa anterior nem podem tratá-la como lida sob a nova identidade.