Módulo 7 - Governança, Estabilidade & Auditoria (system)
Módulo 7: Governança, Estabilidade & Auditoria (system)
Section titled “Módulo 7: Governança, Estabilidade & Auditoria (system)”Estado actual — remoção de usuários. Em People → Team, administradores podem remover funcionários e gerentes após confirmar. Gerentes podem remover funcionários. Contas administrativas e cadastros com vínculos operacionais são protegidos. Desativar continua disponível para preservar o histórico.
Estado actual — telas do gerente, quarta volta (27/10). Cancellation: regra que nunca foi salva aparece desligada e marcada como sugestão — o servidor cobra só a política salva, e antes os cartões diziam “ON 100%” sem cobrar nada. Reports → Staff: a receita de cada pessoa é só trabalho concluído, líquido de VAT e reembolsos (a regra do Stats), com avatar, plural e sem caixa alta; Reviews com nomes simples (nota média, visitas nota 5, avaliações no Google, a quem pedir uma). Banking → Accounts: sinal só em dinheiro que se moveu, “1 account”, e o cartão “All accounts” só com duas contas ou mais; Drawings sem blocos de £0 e tabela vazia; Reconciliation mostra Retry só depois de uma falha. Settings → Services: cartão traduzido e sem caixa alta; Online quote sem o código interno (“ONE_OFF”) sob cada linha.
Estado actual — telas do gerente, terceira volta (27/10). Billing: fatura paga não oferece mais link de pagamento nem WhatsApp; o “-” do Xero sai dos cartões (a tabela mantém); “Total” e “1 visit” no lugar de “Grand Total”/“Items”. Reports: Stats calcula lucro e margem pela mesma regra do Margin e do History (receita mantida menos custo), então a “Avg margin” é uma só; quem não foi avaliado aparece com “—” em vez de 5.0; Margin traduzido com plural; títulos sem caixa alta; zero horas é “0h”. Banking → Payroll: o saldo de quem deve à empresa diz “Received by bank / in cash”, sem sinal duplicado, e saiu a frase falsa de que todo saldo passa adiante sozinho. Dashboard: atraso em horas (“6h 28min”), estados com zero escondidos e plural de avaliações.
Estado actual — telas do gerente, segunda volta (27/10). People: o histórico do contato não mostra mais “null/5” numa visita sem nota, e cada “Visit booked” diz o dia da visita; a próxima visita abre com um toque na linha (Staff instruction e Reschedule ficam como botões claros); a equipe vê as visitas de hoje ainda abertas (antes sumiam depois do horário); Devices é uma linha por aparelho, os dois mais recentes primeiro; gerente e admin não mostram “No visits this week”. Quotes: as abas trazem cada fila com a contagem (sem os blocos de KPI repetidos); a confirmação diz o que o cliente paga — “Client pays £144.00 · Net £120.00 + VAT (20%) £24.00” — e não mais o líquido como total com “VAT included”; Decline é um botão de contorno. Notifications: um toque no cartão lê e abre o item. History: o lucro de cada linha usa a regra do total (calculateNetPL), e uma visita ainda por fazer mostra “—”.
Estado actual — telas do admin (27/10). Google Contacts fica em Settings → Messaging: conta, estado, última sincronização e erros, com conexão e manutenção; People não tem botão Google sync. Alterações em clientes, equipe e leads continuam disparando sincronização automática; o retorno da autorização Google abre a nova aba. A fila de Account deletions voltou a carregar: o GET respondia sem success e a tela mostrava erro e lista vazia, escondendo pedidos reais. Fiscal mostra o VAT de cada empresa como selo; mudar o registro só pelo Edit. Margins é um cartão (margem mínima por visita e comissão de carpete). A IA tem a sua aba (Messaging → AI); o tempo das conversas das visitas fica em WhatsApp. Taxas de entrega sem nenhuma mensagem enviada mostram “—”, nunca 100%. Clean-up, Banner e Allocation rules em palavras simples e caixa normal. “See the app as” saiu do menu lateral para o Perfil do admin, como a busca de pessoas do Dashboard (equipe ao abrir, clientes ao digitar; um toque entra). Corrigido: simular alguém que ainda não definiu senha (quase todos, por link de acesso) caía no login, porque o boot lia a troca de senha pendente como primeiro acesso abandonado; numa simulação o /auth/me não pede mais troca de senha. A tela do Chatwoot diz o motivo (sem resposta, sem agente com o e-mail, entrada recusada) a partir de um código do servidor.
Estado actual — relatórios e histórico. Falha de consulta aparece com nova tentativa, sem virar resultado financeiro zero; carregamento/falha bloqueiam a exportação. CSV escapa aspas, vírgulas e quebras de linha e neutraliza fórmulas em texto. Stats e contas ativas compartilham os mesmos seis meses. Capacidade soma turnos/afastamentos reais do mês e horas individuais alocadas; ausência de capacidade ou avaliação aparece sem percentual/nota inventados. Staff identifica como confiabilidade a proporção das visitas concluídas sem atraso registrado acima de quinze minutos. Risk usa o mesmo conjunto faturável e valor líquido de VAT do Billing/Dashboard, incluindo visitas antigas até hoje; clientes sem visitas usam a regra comum de seis semanas sobre o histórico completo e somente cadastros ativos.
Estado actual — fronteiras. Os serviços dos nove domínios e os fluxos de aplicação são auditados transitivamente, incluindo imports dinâmicos, contra UI, stores e transporte concreto; imports cruzados usam contratos públicos e o grafo não contém ciclos. Diagnóstico de integridade permanece puro, separado da execução das reparações; a composição de alertas consome o contrato de saúde da comunicação, sem carregar o cliente HTTP.
Estado actual — janela. /api/boot hidrata a janela operacional (visitas vivas e 14 dias de Londres de DONE/CANCELLED/PAID), não o arquivo. Uma visita fechada que ainda deve dinheiro (DONE, ou CANCELLED com taxa, sem PAID/REFUNDED) fica na janela em qualquer idade (operationalVisitWhere, isOperationalVisit): antes, um serviço não faturado em 14 dias sumia do Pool do Billing e do Unbilled/Unpaid do Dashboard. A última visita não cancelada de cada série em curso (ritmo semanal/quinzenal/mensal, não TERMINATED em recurring_series) também fica, em qualquer idade (series_visit_heads): sem ela, uma série retida por dívida ou que a execução diária não conseguiu estender saía da janela depois de 14 dias e sumia de Issues e dos planos do cliente. É uma linha por série, sempre dentro do escopo do papel. A leitura usa ramos indexados e essa cabeça (gatilho em service_requests), em vez de varrer o arquivo.
Estado actual — deduções de coleta. A folha distingue recebimento factual, parcelas adicionais, devoluções por funcionário e saldo esperado da rota planejada. Trocar o último método não apaga dinheiro já recebido. Uma fatura agrupada atribui à visita somente sua parcela comprovada, preservando o saldo do documento. Recebimento manual, verificação, crédito e coleta gravam visitas, documentos e deltas de folha na mesma transação. Coleta confirmada após folha não rededuz o saldo já esperado; devoluções adicionais usam registro próprio e uma reversão ambígua é recusada. A interface espelha as folhas aceitas pelo servidor.
Estado actual — documentos completos. A leitura de documentos financeiros usa páginas de 200 com cursor de data e identificador; a interface percorre todas as páginas, inclusive créditos antigos. Cada página mantém o escopo do cliente autenticado e cursores inválidos são recusados.
Estado actual — leitura fiscal histórica. Faturamento e recebimentos usam a base fiscal confirmada da visita/documento, preservada nos snapshots da fatura. Alterar VAT ou absorção no perfil atual não reescreve valores históricos; legados sem prova mantêm o cálculo compatível existente. Boot e consultas de faturas recebem a mesma base.
Estado actual — correções financeiras e documentos. O Admin revê preço, custos e base fiscal histórica com motivo e prévia antes de gravar; pagamento original e folha fechada permanecem fatos históricos. Sem recebimentos, uma fatura DRAFT é recalculada e uma emitida é anulada/reemitida com número próprio; uma fatura paga conserva número e linhas, com suplemento ou nota de crédito vinculados. Redução extingue dívida antes de deixar crédito disponível ou registrar transferência já devolvida; não executa um estorno no gateway nem reduz a receita duas vezes. Crédito pertence ao cliente e empresa de origem, pode quitar outra fatura ou depósito dessa mesma origem, exige nova prévia e tem movimentos imutáveis. Documentos e PDFs usam os snapshots originais; o cliente vê somente os seus documentos. O saldo documental considera os créditos da própria visita em faturas agrupadas, mantém tarefas antigas com suplemento devido na janela operacional e não conta aplicação de crédito como dinheiro recebido. Efeitos contábeis conservam identidade, conteúdo e organização de destino em fila persistente; somente confirmação externa pode marcar entrega como confirmada. O cron executa um efeito por chamada, com exclusão mútua por documento, dependências, prova remota e espera progressiva após falhas; o Admin pode solicitar nova tentativa. Recebimentos reais são exportados por transação positiva, nunca pelo saldo quitado por crédito; respostas perdidas são recuperadas sem duplicar. Estorno em transferência exige conta bancária GBP da organização original; no QuickBooks, a saída em contas a receber é vinculada à nota de crédito. A prévia distingue custo total, lucro da visita e participação de cada funcionário; uma equipe vazia aparece explicitamente como ninguém escalado.
Estado actual — auditoria e avisos. A auditoria de integridade corre no Worker contra o D1, uma vez por dia e no Verificar agora (/api/atomic/integrity-audit só lê o resultado guardado) — não sobre o Zustand. Histórico de quem fez o quê: cada insert, update e delete de service_requests, invoices e payroll_entries vira uma linha em audit_events (gatilhos SQLite, migração 0182), com cada campo antes → depois e o autor lido de last_actor_json — utilizador e papel, ou CRON/WEBHOOK/BOT/PUBLIC; um update sem carimbo novo fica como origem desconhecida. Mensagens enviadas a um cliente entram como evento da visita (recordMessageAudit). audit_event_requests liga faturas e folhas às visitas que tocam. A leitura (historyView.ts) esconde cópias internas — original_data_json e, do holerite, request_snapshots_json, adjustments_json e included_request_ids_json (antes, cada recálculo da folha despejava as visitas congeladas em JSON na History da tarefa, 13/10) — e descarta um update que fica sem nada a mostrar, sem motivo nem entrega; o recálculo de um holerite aparece como “Holerite X recalculado”, com os valores nomeados (base, participação, gorjetas, adiantamentos, dinheiro recebido, bruto, líquido). A aba Admin do detalhe da tarefa mostra a History da visita (/api/visits/:id/history, admin/gerente, página a página, filtros por tipo); checklist e evidências da mesma pessoa e da mesma visita em 30 minutos aparecem agrupados, preservando fotos, edições e remoções de itens; incidentes incluem edições e reabertura. O estado atual de entrega do WhatsApp acompanha a mensagem (incluindo recusa posterior da Meta e o motivo), sem reescrever o evento de envio. History e Activity atualizam a cada 30 segundos enquanto abertos em primeiro plano. Os gatilhos dividem JSON em até 16 pares por função para respeitar o limite de 32 argumentos do D1. O browser já não grava logs de actividade (ActivityLogger saiu) e um save sem data nem equipa originais já não deixa entrada vazia em request_edits; os logs antigos não migram. Nas notificações, Activity Feed lê /api/audit/recent (os 100 eventos mais recentes), agrupa por dia de Londres; somente eventos com pedido existente oferecem abrir detalhes. system_logs fica só para erros. Cada aba mantém sua busca. System Errors apresenta falhas do app, servidor e integrações como histórico dos últimos 200 registros, com hora da consulta, resumo e detalhes técnicos expansíveis.
Estado actual — gestão da tarefa. A aba Admin de ADMIN/MANAGER mostra agendamento, equipe, execução, checklist, incidentes, evidências, avaliação, pagamento e todas as faturas/folhas vinculadas, inclusive depósitos e documentos fora da janela do boot. A linha de etapas usa os eventos imutáveis de criação, alocação, entrada, conclusão, faturamento, pagamento e folha; depósitos têm etapa separada, documentos têm identificação e eventos ausentes não ganham datas inventadas. Os horários mostrados são de registro da ação. Os controles financeiros usam essa leitura do servidor; falha de leitura impede editar valores. O modo de correção exige motivo, prévia antes/depois e versão, registra autor e motivo na History e permite corrigir instruções, avaliação, notas, itens do checklist, resolução/reabertura de incidentes e marcações existentes em tarefas encerradas ou canceladas. Marcação de horário preserva GPS, horas remuneradas e valores; horários são de Londres e a saída não pode preceder a entrada. Reabrir DONE limpa encerramento e saída e exige equipe, ausência de depósito, pagamento, fatura ativa ou folha vinculada; cancelar/reverter continua nos fluxos próprios. A troca do recebedor exige motivo e prévia vinculada ao estado da tarefa e dos documentos: transfere somente a dedução nas folhas DRAFT originais e preserva APPROVED/PAID, registrando deltas por componente para a próxima geração de folha, sem usar adiantamentos. A geração consome cada ajuste uma vez; descartar o rascunho libera sua aplicação para nova geração. Folhas de ajustes anteriores permanecem iguais: uma nova correção gera compensação, e a prévia mostra ajustes pendentes e já consumidos. Tarefa e documentos são salvos numa transação com guardas de concorrência; os novos documentos mostram tarefa, motivo e componentes, e integram a History mesmo sem serviços remunerados no período. O detalhamento de uma folha fechada identifica explicitamente as referências atuais das visitas, separadas dos totais históricos; deltas negativos também são exibidos. Remuneração acordada e outros custos de tarefas DONE/CANCELLED têm comando próprio (/visits/:id/financial): motivo, prévia vinculada ao contexto e transação única atualizam custo/lucro e pagamento manual da visita, deltas em DRAFT, compensações na próxima folha para APPROVED/PAID e movimento assinado na reserva. Outros custos confirmados também entram nos relatórios de cancelamentos, sem transformar custos planejados antigos em despesas realizadas. Edições econômicas diretas de tarefas encerradas são recusadas pelo servidor; reabrir cancelamento com folha, correção, pagamento ou fatura exige reconciliação. A cópia não carrega custos avulsos confirmados. A verificação de recebimento é uma transação única de fatura e visitas; depósitos atualizam somente o depósito, e valores inválidos não autorizam PAID. Recebimento manual e reemissão usam guardas antes da primeira gravação, sem restauração posterior que apague edição concorrente. Alterar uma dedução já incluída em folha exige reconciliação; primeira coleta ainda não aplica esses deltas automaticamente. Pagamento parcial em caixa/conta de funcionário exige revisão própria. Reversão de documento com vínculo ou conexão contábil usa estorno registrado, preservando o recebimento externo. Comissão, recebedor/método planejado e datas de tarefas encerradas não mudam pela gravação genérica. Alterar método/recebedor da fatura DRAFT exige ausência de folha/ajustes vinculados e grava fatura e visitas atomicamente; rotas da empresa não nomeiam recebedor funcionário, e a tela recarrega as versões aceitas. Cada geração guarda contribuições e configuração históricas; correções sucessivas consideram deltas anteriores e o lucro agregado do run, inclusive ajustes em outras tarefas. Legados exigem valores históricos explícitos por contribuição; a prévia mostra o destino de cada diferença. O recálculo preserva remuneração e participação no lucro registradas, inclusive o baseline confirmado de folhas antigas. Beneficiário sem folha original recebe ajuste vinculado ao run. Descartar todos os rascunhos originais registra liberação imutável, compensa esses ajustes e reverte a reserva; qualquer original sobrevivente mantém o vínculo. Apenas a liberação registrada desativa o snapshot; contribuições duplicadas em runs ativos exigem reconciliação. A geração verifica visitas, equipe, adiantamentos, configuração e vínculos usados no cálculo antes de gravar; alterações concorrentes exigem nova tentativa. O comando também corrige equipe, gorjetas e horas: preserva beneficiários históricos para compensação, exige prova explícita para gorjetas legadas e mantém horas remuneradas dentro das faturadas. Equipe histórica inativa continua disponível para reconciliar contribuições existentes. Horas faturadas passam pelo plano de preço/documentos quando alteram a cobrança. saíram os botões que forçavam status de serviço ou pagamento sem esses registros.
Estado actual — barra do shell. O shell mostra uma barra. Críticos ocupam a rotação; o anúncio fica na folha à parte. Offline absorve a falha de ler anúncios. Saúde WhatsApp mostra a hora de Londres da última leitura. O dump da Graph fica no detalhe (copiável); a solução nomeia o objecto. Carpet usa configuração e razão de comissão próprios; tarefas marcadas como terceirizadas não entram na folha nem no P&L residencial. A entidade fiscal define a taxa Flat Rate e se permite receber caixa ou conta de terceiros/funcionário — nunca o nome da entidade.
No Dashboard Overview, Needs attention → Operations conta as três filas (sem equipe, confirmação e depósito) e abre sempre Overview, mesmo que outra aba tenha sido usada antes. Qualidade usa as 14 datas de Londres incluindo hoje e apenas notas inteiras de 1 a 5. Qualidade, filas de Operations e orçamentos recalculam apenas quando seus dados ou o dia de Londres mudam; materiais e novos leads, quando seus próprios dados mudam. A chegada de um aviso não repete essas leituras. Atrasos do dia (Full Schedule → Day) e custódia de chaves continuam seguindo o relógio. O gráfico semanal agrupa as visitas em uma passagem e recalcula na mudança dos pedidos ou do dia, não a cada tick do relógio; preserva a visita antiga ainda em andamento do dia. Clientes com visita em andamento não entram em Quiet clients, ainda que ela tenha começado antes de hoje. Testes de componente usam 300 clientes, 30 funcionários e 2.703 visitas; o cenário de navegador usa 2.700 visitas sintéticas sobre autenticação/API locais, sem gravá-las ou contatar clientes. Essa validação não representa carga concorrente em produção.
Desenvolvimento e publicação. npm run check conserva os sete gates completos, mas reaproveita por até uma hora a aprovação local do mesmo conteúdo, configuração, ambiente, runtime e dependências instaladas. O registro fica no diretório Git do checkout, guarda somente hashes e exige o mesmo conteúdo de dist; qualquer mudança, erro, expiração ou artefato ausente obriga nova validação e build. npm run check:full força os gates. Alterar inputs durante a validação não gera aprovação; validações concorrentes no mesmo checkout são recusadas. Push e deploy:web consultam o mesmo gate, e o upload usa o build validado, mantendo o bloqueio de segredos e a confirmação do domínio. Deploy:backend exige checkout commitado e publica só banco, chat ou e-mail alterados desde backend-v<N> (dependências/configuração compartilhadas invalidam os Workers; baseline desconhecida exige tudo); a tag só avança quando todos os componentes necessários concluem, nunca após falha parcial. Essa aprovação é uma otimização local confiável, não uma assinatura contra quem pode editar o próprio checkout.
O módulo System atua como o “policial” do ecossistema Prime Crown. Ele executa auditorias contínuas em segundo plano buscando inconsistências de dados, gerencia as configurações globais e aplica as regras de cancelamento.
Os avisos persistentes também obedecem à governança compartilhada: informações são anunciadas como status educado, enquanto falhas operacionais e comunicados críticos recebem prioridade de alerta. Ações assíncronas bloqueiam repetição e mantêm o nome acessível durante o processamento; ícones animados são decorativos e ações de fechar permanecem nomeadas em PWA, Android, iOS e desktop.
A edição administrativa do banner global usa CFSelect, CFInput, Button e IconBadge. Ativar um banner exige mensagem não vazia; tipo, texto e estado ficam bloqueados durante a gravação. A tela só limpa o draft e anuncia publicação depois de saveBanner responder com sucesso de aplicação. Falha restaura somente o valor otimista pertencente àquela tentativa, mantém o draft para retry e nunca afirma que um comunicado local alcançou todos os usuários.
A leitura do banner também é autoritativa. “A verificar avisos” não ocupa a barra. Falha com a rede no ar vira problema com retry; offline já explica que os avisos não carregam. Um comunicado já carregado permanece visível durante atualização/falha. Owner por usuário e sequência de request descartam respostas tardias, e a troca de conta limpa imediatamente o snapshot anterior. Reconectar força nova consulta e limpa o erro offline durante a atualização, mesmo sem mudar de tela ou esperar a deduplicação. Retomar o foreground após a janela de deduplicação reconcilia o aviso em web/PWA, Android, iOS e desktop.
Salvar e excluir regras de cancelamento aplicam estado otimista, mas promovem qualquer 4xx funcional a falha e executam rollback condicional. A gravação de rede ocorre fora do updater Zustand; uma recusa restaura somente a regra ainda pertencente à tentativa, e uma exclusão recusada reinsere a linha apenas se ela não foi recriada. A tela nunca mantém uma regra rejeitada como se estivesse salva nem perde alterações paralelas.
🛡️ 1. Auditoria Contínua de Estabilidade (StabilityService)
Section titled “🛡️ 1. Auditoria Contínua de Estabilidade (StabilityService)”O StabilityService.fullSystemAudit roda no Worker, uma vez por dia (runIntegrityAudit, functions/api/common/integrityAudit.ts): lê as tabelas inteiras (visitas, faturas, clientes, equipe, empresas, holerites e folhas), por isso o cron de 5 minutos o roda uma vez por dia de Londres (maybeRefreshIntegrityAudit) e guarda o resultado em integrity_audit_results (0278, uma linha). GET /api/atomic/integrity-audit só lê esse resultado — abrir Billing não recalcula nada; antes, cada abertura da página varria as sete tabelas. POST verifica de novo na hora: o botão Verificar agora e cada Corrigir. A tela diz quando foi a última verificação. Mostrado só em Billing → Integrity (IntegrityAlertsView). Aponta apenas registros que se contradizem, cada um na visita a que se refere (cliente e data):
MISSING_CLIENT— a visita aponta para um cliente que não existe mais.NO_CHECK_IN— visita em andamento sem check-in.STATUS_WITHOUT_INVOICE— a visita diz estar numa fatura (DRAFT/AWAITING) anulada ou inexistente. Corrigir voltapaymentStatuspara NONE (pool de faturamento).VAT_MISMATCH— o total salvo não seguesplitVat. Corrigir recalcula.PAYROLL_MISSED— visita concluída num período de folha fechado que nunca entrou numa folha.
O botão Corrigir (useIntegrityRepair) só aparece nos dois casos que um save resolve, avisa depois que o servidor aceitou e roda a auditoria de novo (o POST, para o item corrigido sair da lista). Ficou de fora o que é julgamento ou já tem tela: visita concluída sem fatura (pool do Billing), visita fora da folha num período aberto (Payroll), tempo de deslocamento insuficiente entre duas visitas (Operations → Issues, TRAVEL_GAP); o atraso previsto da visita em andamento saiu — o Day mostra o atraso real (Late), visita rápida demais, troca da cleaner habitual, burnout e staff sem visitas. A tela Data maintenance não mostra mais a auditoria.
🛠️ 2. Arquivos Principais do Módulo
Section titled “🛠️ 2. Arquivos Principais do Módulo”- Serviço de Estabilidade:
src/features/system/services/StabilityService.ts - Regras de Cancelamento:
functions/api/atomic/cancellationRules.ts - Zustand Store:
src/stores/systemStore.ts - Painel de Configurações:
src/pages/Settings.tsx— abre em Fiscal Entities (também destino de um?tab=desconhecido). Grupos e abas (src/constants/settings.ts): Business — Fiscal Entities, Margins & profit (PROFIT_SHARING, com visão executiva no topo, Profit check com piso de margem para avaliação de tarefas e Manager shares para divisão direta entre gestores; a seção de Profit split com reserva de caixa e taxa admin foi removida como complexidade desnecessária); Operations — Services & prices (serviços e carpete), Online quote (área atendida, extras e descontos de recorrência; o mesmoServicesTabcomsection), Cancellation Policy (um cartão por regra, salvo pelo ✓ do cartão na tabelacancellation_rules; sem escolha de motivos: o cancelamento tem dois motivos fixos, Client asked, que aplica as regras (o escritório ainda pode dispensar a taxa), e Something else on our side, que nunca cobra —reasonCharges), Allocation rules; Messaging — WhatsApp connection (provedor, saúde, teste do webhook, token, janela de 24 h), Bot & automatic messages (respostas, opt-outs, tradução e respostas por IA); Admin — Announcement banner, Data maintenance, Account Deletions. As opções do log de atividade saíram das Configurações: um gestor as edita no próprio log (ícone de ajustes), e elas continuam sendo da equipe inteira (/atomic/settings). O/api/bootmanda emsettingssó as chaves que o app lê (BOOT_SETTINGS_KEYS: systemIdentity, profitConfig, carpetSettlementConfig, chatConfig, allocationRules, operationalFeedConfig, aiConfig, whatsAppConfig, serviceArea): o app espalhasettingspor cima do resto do boot, e uma cópia de junho decancellationRulesguardada emsystem_settingssubstituía as regras da tabela a cada carga (2026-09-30); estado só do servidor (cron, cursores) também não sai. A antiga aba Identity & Brand foi removida;companyNameethemeseguem com o valor salvo e os padrões desettingsDefaults.ts.
🔐 3. Telemetria segura do cliente
Section titled “🔐 3. Telemetria segura do cliente”Erros de renderização, eventos globais e rejeições não tratadas convergem em reportClientError, mas nenhum fluxo envia a URL completa. telemetrySanitizer preserva origem e pathname para diagnóstico e remove query/hash; também redige tokens, JWTs, senhas, cookies, authorization, API keys, credenciais e códigos em mensagens, stack e contexto aninhado. Proteções de ciclo, profundidade e tamanho evitam que um erro gere logs excessivos. O mesmo contrato sanitiza a causa e a URL copiadas pelo ErrorFallback, mantendo suporte consistente em desktop, PWA e WebViews sem expor credenciais de reset/OAuth.
A tela administrativa SystemErrorsLog só declara No errors in this snapshot depois de uma leitura HTTP válida. Falha inicial mostra alerta sem vazio; falha posterior mantém o snapshot com aviso de possível desatualização. Busca sem correspondência possui estado próprio (No matching errors). Refresh automático/manual compartilha lock síncrono, preserva a lista durante atualização, usa loading do botão compartilhado e limita a leitura a 12 segundos. Sair da aba ou sessão aborta o transporte, impedindo resposta tardia nos quatro runtimes. Para suprimir alarmes falsos e crachás vermelhos indevidos no painel e na barra lateral (Sidebar), isSystemErrorLog filtra ruídos de navegadores públicos e integrações desligadas (CLIENT_UNSUPPORTED_RUNTIME_ERROR, CLIENT_UNHANDLED_REJECTION, CLIENT_BOOT_ERROR, EVOLUTION_CONNECT_ERROR, WHATSAPP_INBOUND_CATCHUP_FAILED, WHATSAPP_CALL_REJECTION_UNVERIFIED, WHATSAPP_WEBHOOK_UNREADABLE, CHATWOOT_SWEEP_FAILED). Logs de runtime do cliente (CLIENT_RUNTIME) só qualificam como erro se forem exceções reais (CLIENT_EXCEPTION), e logs do Evolution só entram se forem ações operacionais acionáveis. Para evitar poluição visual com repetições, SystemErrorsLog agrupa erros idênticos por tipo/ação (groupSimilar), exibindo badge de ocorrências e histórico cronológico expansível, com alternador rápido entre visualização agrupada e individual. No feed de atividades (useActivityFeed e GlobalActivityLog), a configuração padrão silencia sincronizações automáticas de série (showSeriesSyncs: false) e manutenções rotineiras de CRON sem serviço associado (senderRole === 'SYSTEM' sem requestId em SYSTEM_LOG), e o cabeçalho padronizado (TabToolbar) alinha busca, filtros rápidos (StateFilterPills: Status, Equipe & Turnos, Financeiro, Sistema) e cartões no mesmo padrão visual da Inbox de notificações (cards rounded-2xl, caixas de ícone p-2.5 rounded-xl e divisores de data com linha).
A Inbox de notificações combina duas fontes por identidade: o cache IndexedDB particionado e o histórico push do servidor. O vazio All caught up só aparece depois que ambas terminam com sucesso. Falha local, remota ou estado offline preserva qualquer snapshot disponível, mantém um alerta visível e oferece retry; a tentativa mais recente e o usuário atual são validados no commit, impedindo que uma resposta tardia de outra conta altere conteúdo ou status em web/PWA, Android, iOS e desktop.
Marcar uma notificação ou toda a Inbox como lida continua responsivo por atualização otimista, mas agora aguarda success autoritativo do endpoint. Cada item e a ação em lote possuem lock síncrono, estado busy acessível e versão proprietária. Em recusa/rede indisponível, somente os itens ainda pertencentes à tentativa falha voltam a não lidos e um toast explica o rollback; conclusão de uma sessão antiga não consegue liberar lock, reverter badge ou alterar a conta atual.
A resolução automática ao abrir um pedido ou conversa segue o mesmo caminho para registros push: identifica IDs pelo snapshot atual e delega cada persistência à mutação autoritativa, incluindo lock, epoch, rollback e feedback. Toasts exclusivamente locais são resolvidos somente no cache particionado, sem round-trip inútil. Os callbacks leem refs atuais e permanecem estáveis entre renders, evitando reexecução de efeitos apenas por mudança de identidade da função.
As preferências de notificação (disponíveis no Perfil e em Configurações > Notificações) suportam controle granular por subitens para categorias com múltiplos alertas operacionais (ex.: Chatwoot com mensagens recebidas CHATWOOT:message, atribuição de conversa CHATWOOT:assignment e quebra de SLA CHATWOOT:sla). Desabilitar um subitem específico preserva as demais entregas do mesmo grupo tanto no envio de push remoto (Web Push/FCM/APNs) quanto no silenciamento da Inbox interna, respeitando categorias obrigatórias por perfil (RBAC) e persistindo em notification_push_prefs.
As ações Reply e Mark as read da bandeja do sistema também separam a confirmação do canal da confirmação individual de cada linha da Inbox. O service worker publica para a SPA somente IDs aceitos com success: true; falhas permanecem não lidas, disparam reconciliação e, na ação explícita, recriam uma notificação persistente com retry. Assim Android/Chrome/PWA não zeram canal ou badge quando apenas parte da operação chegou ao servidor, e os demais runtimes recebem o mesmo estado ao retomar.
No shell Android com FCM nativo, ReplyReceiver e MarkReadReceiver compartilham NativeNotificationActions: HTTP não-2xx, falha de rede ou success !== true nas linhas da Inbox contam como recusa. O receptor só remove a conversa quando canal e todas as linhas foram confirmados; caso contrário mantém o estado e publica Could not mark conversation as read com ação nativa de retry. O destinatário original acompanha Reply, Mark as read, dismiss e o toque em qualquer superfície da notificação — conversa, resumo agrupado ou alerta operacional — e é comparado ao dono ativo antes da rede e novamente após sua resposta, para que uma ação antiga não afete nem redesenhe a bandeja da conta seguinte. Uma resposta enviada com sucesso continua visível no estilo de conversa quando apenas a sincronização de leitura falha. Cada ação Reply leva uma chave externalId única; se Android/Chrome repetir o broadcast da mesma ação, o endpoint retorna a mesma mensagem em vez de persistir ou entregar uma segunda vez. Ao redesenhar a notificação, uma chave nova é criada para a próxima resposta distinta; o stack Android também registra as chaves já exibidas para não duplicar o balão local em uma restauração do sistema.
Logout, revogação remota e sessão offline pendente também são fronteiras de privacidade do tray: antes de navegar, a aplicação fecha todos os banners do service worker e limpa o badge; no Android, ChatShade.clearAll apaga a pilha MessagingStyle persistida e cancela as notificações do app; no iOS, o plugin oficial remove os alertas APNs já entregues. O unlink do token continua assíncrono e não bloqueia a saída, mas a rota autenticada mantém uma cópia HttpOnly do token nativo, restrita a /api/auth: se a bridge Capacitor não devolver Preferences dentro do limite, o logout ainda remove a linha daquele aparelho antes de limpar cookies. Assim uma conta seguinte no mesmo aparelho não herda a prévia de uma conversa anterior; como APNs já aceito não é revogável, permanece apenas a corrida física de uma entrega que já estava em trânsito no instante do logout.
O toque de uma notificação também falha fechado: links originados por push do service worker ou do bridge Capacitor só navegam quando recipientUserId existe e coincide com a sessão autenticada atual; App Links operacionais normais continuam sujeitos à matriz RBAC e ignoram qualquer recipientUserId presente na própria query. A prova de audiência só é anexada a partir do envelope Web Push/FCM/APNs validado pelo transport. O service worker persiste somente o identificador da audiência ativa e exige igualdade já antes de desenhar um push; logout remove esse marcador junto com os banners, portanto uma entrega enfileirada da conta anterior não revela seu corpo na bandeja. No Android, o toque no corpo do banner injeta essa prova apenas na URL da origem oficial, pois o bridge Capacitor recebe a URL — não os extras do Intent — e a valida novamente antes de enfileirar/navegar. Antes de Reply, Mark as read ou Open, o service worker confirma em /api/auth/me que o cookie atual ainda pertence ao destinatário do banner; uma sessão expirada pode fazer um refresh compartilhado, mas ausência/divergência encerra a ação sem mutar dados. No Android, o próprio serviço FCM compara o mesmo destinatário ao usuário ativo gravado nas Preferences antes de desenhar conteúdo no tray. Uma ação antiga sem destinatário, de outra conta ou recebida antes do restore da sessão é descartada, em vez de ficar pendente para a primeira identidade que abrir o aplicativo. Qualquer intenção de App Link recebida antes da autenticação é removida no logout, para não atravessar a troca de conta no mesmo WebView.
O endpoint repete o sanitizer antes do D1, fixa user_id e timestamp pela sessão/servidor e aceita no máximo 20 relatórios por conta em 5 minutos. Excesso remove apenas a tentativa recém-inserida e responde 429 com Retry-After; um ID em conflito nunca autoriza apagar outro log. Admin/manager consultam no máximo 500 registros e parâmetros inválidos caem no default seguro. Mensagens internas do banco ficam apenas nos logs do Worker, não na resposta pública.
logErrorToSystemLogs aplica o mesmo limite de conteúdo a exceções internas, incluindo stack e cause, e suporta objetos circulares. Endpoints apresentam textos públicos estáveis e mantêm a causa sanitizada no painel administrativo, evitando que detalhes de D1 ou Resend cheguem ao app.
atomicServerError compõe esse logger nos CRUDs centrais de configuração e entidades. Regras de cancelamento, clientes, funcionários e serviços não expõem detalhes internos em 500; a ação e o domínio ficam disponíveis à governança, e os erros funcionais continuam distintos para que a interface possa orientar o usuário.
Correções da auditoria de estabilidade
Section titled “Correções da auditoria de estabilidade”- Risco de atraso no deslocamento: usa a primeira visita seguinte da funcionária. O código pegava a primeira que aparecesse na lista, e uma visita da semana seguinte podia ocupar o lugar da desta tarde, escondendo o atraso que importava.
- “Funcionária sem tarefas” (
GHOST_OPERATOR): vale só para a equipe de campo e conta visitas atribuídas aguardando confirmação (PENDING). Antes, toda a administração e a gerência apareciam como ociosas em toda auditoria. - Alerta de dias trabalhados: diz “trabalhou em N dos últimos 7 dias”, e não “N dias consecutivos”, que não é o que é medido.
🚀 4. Faxina de Banco (Housekeeping)
Section titled “🚀 4. Faxina de Banco (Housekeeping)”/api/bootcarrega o histórico completo de visitas e faturas: Histórico, Relatórios e Folha filtram no cliente, então uma janela de datas no boot os deixaria errados em silêncio.- Faxina Semanal de Banco (
Housekeeping): Rotina assíncrona periódica em/api/cron/housekeeping(executada semanalmente com throttle automático via cron ou sob demanda) que purga, com mais de 45 dias, só ossystem_logsautomáticos (sem usuário,WHATSAPP/WHATSAPP_EVOLUTION/SYSTEM_MAINTENANCE) — ações de usuários e alertas como chargeback são trilha de auditoria e ficam —, descarta orçamentos que ninguém aceitou (lead_quotessem visita, abertos ou recusados) parados há mais de 30 dias e depois apaga os leads que não viraram cliente e ficaram 30 dias sem atividade — nenhuma mensagem de nenhum lado, nenhum orçamento mexido (staleLeadIds,deleteLeadCompletely: lead, conversa, orçamentos e a conta de acesso do lead; convertidos e fundidos ficam), e limpa códigos e tokens expirados, mantendo o banco D1 rápido e enxuto. No mesmo cartão (Settings → Data maintenance) ficam os dias e o que sai: áudio, foto, documento e mensagens do chat, e a foto do checklist de uma visita já fechada, mais antigos quechatConfig.mediaRetentionDays(180; 0 conserva). Áudio, foto e documento tiram o ficheiro do R2 e deixam o texto; conversas apagam a mensagem. O canal e a linha do checklist ficam. Fotos de antes e depois da visita não entram.
📦 5. Política de Retenção e Ciclo de Vida de Mídias (Cloudflare R2)
Section titled “📦 5. Política de Retenção e Ciclo de Vida de Mídias (Cloudflare R2)”Para assegurar controle de custos de armazenamento, alta performance e conformidade com retenção de dados:
- Fotos de Inspeção e Evidências Operacionais: As fotografias de preflight, checklist de início e conclusão de tarefas armazenadas no bucket Cloudflare R2 são governadas por regra de ciclo de vida (Lifecycle Rule) nativa de 12 meses (365 dias). Decorrido esse prazo, as fotos de evidência são descartadas automaticamente, enquanto o registro da visita e os metadados de execução permanecem íntegros no banco D1 para efeito de histórico.
- Documentos Fiscais e Comprovantes: Faturas PDF e recibos de pagamento são preservados pelo período legal de auditoria contábil (5 a 7 anos).