Módulo 7 - Governança, Estabilidade & Auditoria (system)

Módulo 7: Governança, Estabilidade & Auditoria (system)

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. O shell mostra Checking system announcements até confirmar o primeiro snapshot; falha ou estado offline não são tratados como banner inativo, mas como uma faixa persistente com retry. 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. 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)

O StabilityService roda varreduras automáticas no banco D1 para encontrar:

1. Impossibilidades Geográficas: Agendamentos seguidos de uma mesma funcionária em imóveis distantes sem tempo de trânsito suficiente.
2. Faturas Órfãs: Faturas geradas sem agendamento correspondente ou agendamentos concluídos sem fatura gerada.
3. Riscos de Relacionamento: Queda repentina nas notas de um cliente recorrente.

---

🛠️ 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

🔐 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 Exception Faults Logged 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 Error Logs). 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.

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 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. Uma resposta enviada com sucesso continua visível no estilo de conversa quando apenas a sincronização de leitura falha.

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, Evolution 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.