Arquivo — SYSTEM_DOCUMENTATION (até 2026-09-13)
Arquivo congelado em 2026-09-13. Este era o
SYSTEM_DOCUMENTATION.mdda raiz do repositório. Ele repetia o que as páginas deste site já descrevem e passou a existir só como registro histórico: não é mais atualizado. Para o comportamento atual, use as páginas de módulo.
Documentação Técnica e Arquitetural do Sistema Prime Crown
Section titled “Documentação Técnica e Arquitetural do Sistema Prime Crown”forward.ts e move-to-direct.ts validam a direção de transferência no Worker. O forward consulta a tarefa alvo e exige mesmo cliente e hasTeamChannel, impedindo que uma chamada direta use um request ID externo para atravessar a fronteira DIRECT/JOB.
Comunicação Tripartite Operacional (Manager, Equipe & Cliente)
Section titled “Comunicação Tripartite Operacional (Manager, Equipe & Cliente)”O sistema de mensagens suporta comunicação contextual integrada em três vias:
- Notas Internas da Equipe (
INTERNAL_NOTE): Mensagens enviadas em canaisJOBcom a categoriaINTERNAL_NOTEsão marcadas comdirection = 'INTERNAL'. Elas são estritamente isoladas: o endpointPOST /api/channels/:id/messagesnão faz envio Meta/WhatsApp nem push notifications ao cliente (isInternalNote: true). Uma nota só pode citar outra nota; cliente ou mensagem pública de staff não pode apontar para ela. O endpointGET /api/channels/:id/messagesaplicane(messages.category, 'INTERNAL_NOTE')caso o usuário requisitante possua roleCLIENT, e oculta também previews de citações internas que possam existir em linhas legadas ou broadcasts compartilhados. No frontend, as notas internas possuem apresentação âmbar com badge🔒 Internal Note · Team only. - Polimento e Tradução Assistida por IA (
POST /api/ai/polish-message): Integrado ao Google Gemini 2.0 Flash (com Workers AI e fallback seguro), permite que funcionários ou gerentes redijam mensagens em rascunho rápido ou português e as polam instantaneamente para inglês britânico formal (en-GB) antes do disparo. - Ações Rápidas em 1 Toque (
QuickActionChips): Chips rápidos no topo do compositor para avisos de trânsito (ETA 15m/30m integrados viasendTransitNotice), chegada ao imóvel, solicitação de interfone/chave e conclusão de serviço. O aviso de trânsito valida tarefa–cliente antes de materializar o canal/contato, aceita gestores e somente a profissional alocada, e recusa cotações. - Indicador Dinâmico de Audiência e Escopo: O compositor exibe dinamicamente o destino antes do envio (Client & Team WhatsApp, Direct WhatsApp ou Internal Note - Team Only), garantindo transparência total e prevenindo vazamentos acidentais.
O chat embutido nos detalhes da tarefa encaminha o mesmo contrato do Inbox, incluindo mediaUrl, replyTo e o cliente proprietário; anexos e respostas citadas não perdem contexto e o upload não cai no diretório fallback unknown ao mudar o ponto de entrada. Ao encaminhar uma mensagem DIRECT com anexo para JOB, o Worker copia os bytes para a árvore team daquela tarefa antes de mover a linha; a equipe recebe um anexo realmente legível, sem ganhar acesso à árvore privada direct. Autoria também é autoritativa: sender_id, papel e nome visível são derivados da sessão e D1 no Worker; o senderName enviado pelo browser serve apenas ao balão otimista e nunca pode fazer um cliente aparecer como manager ou funcionário. A origem também é autoridade do servidor: todo POST /api/channels/:id/messages persiste source = APP, ignorando a origem declarada pelo browser; somente o processamento autenticado de webhooks Meta/WhatsApp pode gravar uma entrada WHATSAPP e abrir a janela de 24 horas. O acesso R2 reforça a mesma separação: funcionário só alcança a árvore team de tarefa à qual está alocado; uma atribuição a qualquer tarefa do cliente não libera mídia direct da conversa privada Management. Ao criar mensagem, o Worker verifica outra vez que a URL começa na rota R2 interna e pertence ao clientId, tipo e requestId do canal; colar uma URL de outro canal, cliente ou host é recusado antes de persistência, push ou relay Meta. O mesmo gate é aplicado a criar, listar e cancelar agendamentos, antes de uma mensagem futura alcançar a fila ou revelar seus próprios metadados: ter um ID antigo não autoriza quem perdeu acesso ao canal a removê-la. Anexos agendados também passam pelo vínculo R2/canal. O upgrade WebSocket, fan-out de push, recibo de leitura e rotas auxiliares de digitação, reação e tradução reutilizam exatamente o gate de mensagens: uma linha de participante nunca perfura o DIRECT cliente–gerência para escutar broadcasts, receber conteúdo de notificação, confirmar WhatsApp, consultar atividade do cliente ou alterar estado lateral, enquanto JOB continua exigindo a alocação. A API de participantes recusa novas linhas em DIRECT de cliente/lead — mas aceita removê-las para limpeza — e o criador genérico rejeita essa combinação antes da inserção. Ao abrir o próprio JOB, um cliente não pode criar audiência: qualquer participantIds no corpo é ignorado, enquanto somente gestão aplica os participantes atuais e a sincronização da atribuição continua sendo a única fonte de remoções. DIRECT de funcionário é identificado por owner_type=EMPLOYEE, gravado tanto no provisionamento quanto na criação genérica e reparado para linhas legadas, portanto continua recebendo a conversa privada de gestão sem herdar janela ou audiência de cliente. Chaves R2 legadas, que não carregam client/scope no caminho, são tratadas como recuperação administrativa e exigem ADMIN/MANAGER tanto para leitura quanto exclusão.
O upload também usa channel.clientId como raiz quando não há objeto Client em memória: lead pré-conversão e funcionário no DIRECT privado não caem mais em unknown. A autorização R2 resolve esses dois owners explicitamente: cada um só lê/escreve sua própria árvore DIRECT, enquanto ADMIN/MANAGER conserva a visão operacional. Essa exceção não muda a proteção principal — funcionário alocado em tarefa de cliente segue bloqueado da mídia DIRECT daquele cliente.
templateCatalogueCache isola memória, geração e deduplicação do catálogo da consulta HTTP. clearPrivateClientStorage importa apenas esse módulo leve para invalidar a sessão, preservando o carregamento sob demanda do cliente de comunicação.
O banner de roteamento valida sucesso explícito e lista de opções antes de publicar o snapshot da leitura. Respostas incompletas/recusadas convergem no estado de falha recuperável.
O banner de roteamento mantém erro/loading visíveis também abaixo de 640 px, com semântica alert/status e retry sem encolhimento por flexbox.
forwardScheduleLabel centraliza o rótulo temporal do encaminhamento em Europe/London. Datas não relativas incluem ano para distinguir tarefas históricas. Dias relativos são comparados por calendário civil, sem supor que todo dia tenha 24 horas.
Testes de interação podem optar por jsdom com a diretiva de ambiente por arquivo; a suíte padrão permanece em Node. O banner de permissão possui cobertura DOM com React real, mocks apenas das dependências externas e verificação de concorrência, recuperação e desmontagem.
As ações assíncronas de ChatPermissionBanner possuem lock síncrono, loading local e epoch de desmontagem, contendo cliques duplicados e feedback tardio.
As mensagens de recusa/ausência de permissão em usePushNotifications orientam às configurações do dispositivo e à nova tentativa, sem referências exclusivas ao Android ou a um botão Subscribe que pode não existir no consumidor.
O banner de chat usa openNativeAppSettings('notifications') quando push está bloqueado no shell nativo; web oferece “Check permission again”. Erros do adaptador apresentam fallback manual.
ChatPermissionBanner adapta a orientação de permissão bloqueada via isNativePlatform, direcionando shells nativos às configurações do aplicativo e web/PWA às permissões do site.
O catálogo importa templateFill sob demanda, após validar a resposta HTTP, mantendo sua invalidação síncrona independente do código de preparação de templates.
ClosedWindowComposer recebe key={composerOwner} de ServiceChatInput, vinculando o estado de templates à identidade composta de usuário e canal, inclusive quando duas contas abrem o mesmo canal.
fetchCatalogue rejeita respostas sem success antes de interpretar configuração ou templates; a falha permanece fora do cache e pode ser recuperada pelo retry do composer.
clearPrivateClientStorage invalida também o catálogo de templates em memória, antes das operações assíncronas de storage. A geração do catálogo impede repovoamento por requests anteriores à limpeza da sessão.
O cache de templates utiliza geração na invalidação. Uma consulta iniciada antes de clearTemplateCatalogue não pode publicar cache ou apagar o marcador da consulta subsequente.
Falhas de catálogo de templates possuem retry touch/teclado no composer. A nova tentativa reexecuta a leitura protegida por lifecycle, compartilhando requests simultâneos pelo catálogo e mantendo erros fora do cache.
O editor de templates mantém variáveis e seleção bloqueadas durante envio para impedir que uma conclusão apague um novo rascunho. Erros e carregamento possuem roles alert/status, e a ação de envio publica aria-busy.
groupForwardTargets classifica tarefas elegíveis em futuras, passadas e sem data válida. O seletor mostra explicitamente “Schedule unavailable” para o último grupo, evitando falso estado vazio e exceções de formatação.
ForwardToTaskSheet usa useNowMinute para reclassificar tarefas futuras/passadas enquanto a seleção está aberta e ao retornar do background, mantendo a mesma atualização temporal em web, PWA e shells nativos.
Transferências entre DIRECT e JOB usam locks síncronos, AbortSignal e invalidação por usuário/canal em ChatInbox. Após a mutação e após o refresh dos canais, a conclusão verifica se ainda pertence à conversa corrente antes de navegar. A ação de mover publica loading e aria-busy na mensagem. Cancelamento HTTP contém a conclusão local, sem prometer rollback de uma operação já aceita pelo servidor.
Integridade da preparação Chatwoot
Section titled “Integridade da preparação Chatwoot”O gate de ativação exige verify token, teste de API, fila vazia e um callback autenticado da conta/inbox configurada nos últimos 30 minutos. chatwootWebhookPreflight em system_settings guarda apenas fingerprint e timestamps, sem conteúdo do evento. Durante preflight, eventos não são ingeridos; trocar parâmetros invalida a prova e TEST não troca uma conexão já ativa. Um rollback imediato para Meta não depende do NAS, porém não permite substituir a conexão Chatwoot enquanto houver trabalho Chatwoot PENDING, PROCESSING ou HELD: cada linha carimba o provider, mas o runner lê as credenciais da conexão para enviar, e essa trava impede que uma mensagem antiga seja desviada para outro inbox. Ao permitir uma conexão nova, o sistema também descarta chatwoot_conversation_links e suas leases, pois o índice desses IDs remotos não carrega host/conta e não pode sobreviver a uma instalação diferente que reutilize o mesmo inbox. Webhooks validam conta/inbox e ignoram notas privadas/atividade. Envios de texto e mídia carregam canal, tarefa e autor como metadados administrativos e preservam chatwoot:<id>; recibos aceitam também IDs Meta/legados e solicitam reentrega se a mensagem local ainda não existir. Downloads processam todos os anexos (máximo 10, 16 MiB agregado, timeout de 15s/arquivo), validam origem inclusive nos redirects e falham explicitamente com log administrativo antes de persistir texto incompleto. Escolhas de rota persistidas prevalecem sobre o último diálogo humano; resposta citada segue o canal original somente para o mesmo cliente e tarefa aberta. O mesmo resolve o destino antes de gravar anexos de entrada: resposta a JOB usa R2 team/requestId, mantendo o arquivo acessível somente à equipe autorizada. Intenção privada, citação ambígua/inválida e tarefa fechada mantêm fallback seguro em DIRECT, inclusive para a árvore de mídia. A homologação real no NAS permanece necessária antes da troca operacional.
O seletor de destino WhatsApp consome startDateTime do contrato real da API e formata a data em Europe/London, independentemente do fuso do dispositivo. Datas inválidas preservam o identificador da tarefa como fallback. A expiração visual usa o relógio compartilhado de foreground, evitando manter uma rota vencida marcada como ativa com a conversa aberta. Leitura tardia de outro cliente não substitui o estado atual; falha de carregamento nunca é apresentada como Management confirmado e oferece retry, enquanto a gravação publica confirmação ou erro explícito.
O chat usa o mesmo breakpoint reativo de 768 px no layout e no controlador e monta exclusivamente a árvore desktop ou mobile. ChatInbox e ClientChatView não deixam conversas escondidas por CSS executando em paralelo; assim cada tela mantém apenas um polling/WebSocket, uma marcação de leitura, um composer e um seletor de rota WhatsApp ativos durante rotação, split-screen e resize.
O composer de templates exibido quando a janela WhatsApp de 24 horas fecha também pertence ao canal corrente. A troca de conversa redefine template e variáveis, invalida o resultado tardio do catálogo compartilhado e aborta qualquer envio em voo. Um lock síncrono bloqueia dois toques antes do próximo render, e somente a conclusão pertencente ao canal ativo pode limpar o formulário ou executar o callback de atualização.
O endpoint de template não confia no preenchimento da interface: além de reler o catálogo Meta e exigir template aprovado/suportado com a quantidade exata de parâmetros, recusa cada variável vazia após normalização. A rejeição acontece antes da reserva idempotente e do provider, portanto não cria uma bolha local nem consome uma conversa paga com texto incompleto.
Listas de clientes, funcionários e custódia de chaves aplicam a mesma fronteira: cards mobile e tabelas desktop compartilham dados, métricas e callbacks, porém somente a apresentação ativa é montada. A busca da gestão de usuários também mantém uma única instância. Cadastros grandes não duplicam toda a árvore DOM nem controles interativos apenas para ocultá-los por CSS.
Na agenda, sidebars de equipe e tarefas sem alocação só são montadas nos breakpoints em que aparecem (1024/1280 px). Em telefones e tablets estreitos o grid não carrega controles drag-and-drop invisíveis, e sua altura usa dvh com mínimo móvel de 420 px em vez de impor os 700 px do desktop.
Data de Atualização: 20 de Agosto de 2026 Versão da Arquitetura: 5.7 Escopo: Documento Mestre de Referência para Agentes IA (Codex, Antigravity, Claude Code) e Engenheiros de Software Full-Stack.
Os proxies Capacitor de Push Notifications e Preferences ficam no bundle inicial. Assim, o fluxo nativo de Subscribe não depende de baixar chunks pela rede antes de chamar o bridge. @capacitor/app não faz parte dessa fronteira crítica: App.getInfo() é carregado sob demanda somente no enriquecimento best-effort posterior, com promise compartilhada e retry após falha.
Atualização 5.7 — identidade de lead, cadastro verificado e cotações
Section titled “Atualização 5.7 — identidade de lead, cadastro verificado e cotações”Cadastro não significa contratação. Uma pessoa nova que entra por senha, Google ou Apple recebe primeiro um token curto de cadastro pendente; somente depois de provar a posse do telefone por um código de seis dígitos enviado pelo WhatsApp nasce uma conta. Se o telefone já identifica um cliente ou lead, a conta é ligada ao registro existente; caso contrário, cria-se um lead com origem APP_SIGNUP. A conta mantém role = CLIENT para compatibilidade de autorização, enquanto auth_accounts.reference_type (LEAD, CLIENT ou EMPLOYEE) define a entidade real que /api/auth/me, /api/boot e os endpoints de escopo devem resolver. Um cadastro abandonado antes do código não deixa conta, cliente ou lead órfão.
Pedidos de preço do site e da tela autenticada Request Service convergem em lead_quotes. Um lead possui no máximo uma cotação OPEN; reenviar atualiza essa intenção, enquanto CONFIRMED e DECLINED permanecem como histórico. Nenhuma cotação aberta cria clients ou service_requests. A tela administrativa Quotes confirma preço, entidade fiscal e horário; essa confirmação cria ou reutiliza o cliente por telefone, materializa o atendimento, calcula VAT conforme a entidade fiscal, marca lead/cotação e redireciona qualquer conta ligada ao lead para reference_type = CLIENT. Recusar mantém a pessoa como lead, registra a decisão no chat e cancela follow-ups pendentes.
A integridade estrutural de “um número, uma conversa” é aplicada também para leads e cotações: ensureDirectChannel e ensureDirectChannelForLead seguem leads convertidos (converted_client_id), leads fundidos (merged_into_id) e resolvem irmãos ou clientes existentes pelo número de telefone via resolveContactIdentity (com suporte a variantes britânicas com trunk zero +44 (0) 7... e telefones brasileiros). O autosave de orçamento e o envio final convergem já na criação: chat-initiate faz o insert condicional atômico pelo telefone normalizado e resolve novamente o dono antes de criar canal, cotação ou token, de modo que duas requisições em voo não abrem leads/canais paralelos. Na recusa de cotações (declineLeadQuote), a nota interna de cancelamento é roteada para o canal direto canônico existente sem criar canais duplicados ou fragmentar o histórico de mensagens. No frontend, ChatSidebar agrupa os canais por contactGroupId ou chave canônica de telefone de leads, mantendo a conversa mais recente e eliminando conversas duplicadas na lista de mensagens da caixa de entrada (ChatInbox). As migrações 0129 e 0133_merge_duplicate_leads_and_channels.sql também reconciliam o histórico: a última considera ambos os campos de telefone, normaliza as variantes locais/internacionais, ignora valores vazios e transfere mensagens/agendamentos antes de apagar o canal redundante; se duas cotações equivalentes ainda estiverem OPEN, a canônica permanece aberta e a outra é encerrada antes do repoint.
/api/boot devolve leadQuotes para ADMIN/MANAGER e somente as cotações pertencentes ao lead autenticado. O cache de boot projeta a coleção em entityStore; RequestService faz upsert do resultado autoritativo e o dashboard do lead acompanha a cotação sem criar uma segunda fonte de verdade. A unicidade parcial (lead_id, service_type_id) WHERE status = 'OPEN' é a fronteira contra reenvio concorrente: após um conflito, createLeadQuote relê e atualiza a cotação canônica. As antigas rotas públicas de conversão direta foram removidas: conversão é um evento administrativo explícito de confirmação da cotação.
As quatro superfícies novas seguem o design system compartilhado: PhoneVerificationStep usa IconBadge, CFInput e Button; RequestService usa PageHeader, Card, CFPillSelector e campos canônicos; Quotes usa cards/empty states semânticos; QuoteConfirmationPanel abandonou o painel escuro legado por uma superfície clara e responsiva. OTP e envio de cotação possuem locks síncronos; a requisição do lead é abortada no teardown. O gestor edita o preço final positivo antes de confirmar, e VAT/WhatsApp recalculam a partir dele. Confirmar ou recusar aguarda o servidor e atualiza entityStore; não existe toast de sucesso antecipado. IDs de série usam o UUID criptográfico compartilhado, inclusive no iOS 15.
Na confirmação administrativa, confirmar e recusar compartilham um lock síncrono anterior à rede, impedindo comandos duplicados ou cruzados no mesmo frame. O composer WhatsApp usa CFInput e Button, bloqueia edição durante a entrega e trava antes do diálogo; o texto aparado é capturado ao abrir a confirmação e é exatamente o payload enviado. A mensagem de confirmação de agendamento segue estritamente a estrutura do modelo aprovado pela Meta (booking_confirmation: "Hello {{1}}, your Prime Crown {{2}} is confirmed for {{3}} at {{4}} with {{5}}. Please confirm if this works for you. Thank you!"), mesmo quando a janela de 24h estiver aberta, assegurando padronização institucional e conformidade total com o WhatsApp Business. Todos os horários de clientes e agendamentos respeitam estritamente o fuso operacional de Londres (Europe/London via londonTime.ts), independentemente de o gestor estar acessando do Brasil ou de qualquer outra região: o timestamp de envio da solicitação (quote.createdAt) é exibido no horário de Londres nos cards da fila (Quotes.tsx), no cabeçalho e acima do composer em QuoteConfirmationPanel, e o horário selecionado é mapeado com precisão para UTC em parseLondonWallClock.
O wizard público também usa CFSelect para a semana e CFInput para observações, preservando o picker nativo e o limite de 500 caracteres. O grupo manhã/tarde/flexível possui nome e estado pressionado, portanto teclado, TalkBack e VoiceOver recebem a mesma seleção visível em PWA, Android, iOS e desktop. As opções de semana geram datas no calendário local sem conversão prematura para UTC. Na confirmação do orçamento (QuoteConfirmationPanel e SlotSuggestionService), a preferência de semana (preferredWeek) é interpretada por parseDate e ancorada na segunda-feira da semana de atendimento, evitando que fusos horários a oeste de UTC ou strings de domingo desloquem as sugestões para a semana anterior.
O editor administrativo do banner global usa CFSelect, CFInput, Button e IconBadge, exige texto quando ativo e bloqueia todos os campos durante a persistência. updateSystemBanner agora devolve a Promise autoritativa e faz rollback condicional do valor otimista; Configurações só limpa o draft e anuncia alcance global depois de saveBanner aceito. Falhas preservam o rascunho para retry e não produzem falso sucesso em desktop, PWA, Android ou iOS.
Configurações do Chat migrou instruções do bot e mensagem de ausência para CFInput e os saves para Button. O lock é adquirido sincronamente, a área editável fica inert e aria-busy, e horário comercial ativo exige resposta não vazia. Texto é aparado no snapshot; saveSettings conclui antes de atualizar os stores e emitir háptico/toast de sucesso. Assim uma recusa do servidor mantém a edição disponível e não deixa Android, iOS, PWA ou desktop aparentarem uma configuração que desapareceria no próximo boot.
Quando a permissão Android já está concedida, mas token local e registro do backend estão ausentes, o sistema não tenta solicitar novamente uma autorização que o Android não exibirá. Subscribe consulta o cache/token FCM atual e o registra na conta autenticada. Uma falha de rede/backend nunca apaga automaticamente o token Firebase: invalidá-lo nesse estado transformava uma falha transitória em uma segunda inscrição ainda mais lenta e podia regravar um token revogado.
Para não depender de o evento registration do Capacitor disparar novamente, o shell Android registra NativePushTokenPlugin, que consulta FirebaseMessaging.getToken() diretamente e devolve o token ao provider web antes da espera por evento. Essa recuperação é código nativo e requer publicação de uma nova versão Android.
NativePushTokenPlugin.getStatus() diagnostica separadamente autorização global, importância dos canais prime_crown_messages/prime_crown_notifications e disponibilidade do token Firebase, sem devolver o token à interface. Uma leitura Android síncrona da permissão evita depender da ponte @capacitor/push-notifications quando a autorização já existe. PrimeCrownMessagingService.onNewToken() também mantém uma cópia nativa do último token; Subscribe consulta memória/cache nativo antes de Preferences e de uma nova resposta de Play Services. O POST autenticado ao backend é a única persistência no caminho crítico; a cópia em Preferences e os metadados são enriquecidos depois, sem manter o botão ocupado. Reconciliações concorrentes compartilham uma única operação, e unsubscribe/reset limpam tanto Preferences quanto o cache nativo antes de invalidar o token Firebase. O Profile apresenta a falha exata e permite repetir a leitura. Login e resume reconciliam de forma idempotente o token autorizado com o backend mesmo quando a cópia local já existe. O Android doctor exige plugin, registro no MainActivity, provider web e integrações Firebase/NotificationManager antes de autorizar uma release.
O registro primário também envia um limite inferior seguro de app_build quando Capacitor.isPluginAvailable('NativePushToken') confirma sincronamente o shell build 10+: esse plugin surgiu depois do renderer data-only do build 5. Assim o backend não regride para o bloco notification legado quando App.getInfo() fica indisponível. O payload data-only chega ao PrimeCrownMessagingService, que oferece Reply, Mark as read, MessagingStyle e uma única pilha por channelId; builds antigos sem prova continuam no formato conservador desenhado pelo SDK.
Check native força a reconciliação e apresenta feedback visível mesmo quando o diagnóstico não muda. Um token apresentado por uma sessão autenticada é transferido de eventual conta anterior para a atual em /api/native-push-tokens: o token comprova posse do aparelho, e preservar o vínculo antigo bloquearia o novo usuário e continuaria enviando conteúdo da conta anterior ao dispositivo.
O registro inicial devolve o usuário autenticado no header X-Prime-Crown-Registration-Owner, sem exigir leitura do corpo no caminho crítico. Tarefas posteriores que enriquecem instalação e build enviam esse valor como expectedUserId; se logout/login já mudou o cookie, a API responde 409 antes de alterar a linha. A proteção bloqueia somente trabalhos atrasados — uma nova ação explícita sem expectedUserId ainda transfere legitimamente o aparelho para a sessão atual.
Preferences aplica saves e remoções do token por uma fila serial com geração. Um novo token invalida persistências mais antigas; recovery e logout invalidam todas as tarefas anteriores imediatamente. Caso um set já esteja dentro do bridge, o remove aguarda e executa depois, garantindo que o estado final local permaneça limpo.
Além da fila, a própria fronteira síncrona de logout suspende callbacks de registration e aborta o POST primário e o enriquecimento tardio de token ainda em voo antes de tocar Preferences. Assim, o NativeBridge persistente não consegue concluir um registro da conta anterior na pequena janela de saída; o token fica disponível somente para o request autenticado de cleanup. A suspensão só é removida por uma nova reconciliação/inscrição explícita (ensureNativePushRegistration) ou pelo recovery, vinculando a próxima atividade à nova sessão.
Fotos recuperadas depois de process death são consumidas uma única vez pelo primeiro observer do contexto opaco correto. A entrega pendente em microtask mantém um guard de montagem; fechar ou trocar a tela antes dela executar cancela o callback, evitando upload na tarefa/chat anterior. Logout ou troca de conta também invalida uma geração de recuperação, remove Preferences e fotos pendentes imediatamente e faz um appRestoredResult que já esteja lendo o blob falhar fechado antes de publicá-lo. Cancelamento, falha de Preferences ou arquivo restaurado ilegível são contidos pelo provider, removem o contexto persistido sem tentar roteá-lo e devolvem a tela ao retry; uma foto sem observer expira da memória após cinco minutos, e substituição/consumo também cancela o timer correspondente.
Somente uma Activity de câmera pode ficar ativa por WebView. O provider rejeita silenciosamente a segunda tentativa antes de trocar o contexto de recovery; no checklist, um lock síncrono bloqueia toque duplo, aria-busy comunica processamento e o ticket de owner descarta o retorno se usuário/item mudou enquanto a câmera estava aberta.
Persistência de push prioriza o destino: o primeiro POST envia imediatamente token/plataforma/dispositivo; installId e appBuild enriquecem a linha depois, em chamada best-effort. Assim Preferences ou App lentos não deixam Firebase pronto sem registro no backend. Check native encerra loading em até 15 segundos; o watchdog mais amplo de Subscribe ainda reserva tempo para um diálogo real de permissão do sistema.
📖 Tabela de Conteúdos
Section titled “📖 Tabela de Conteúdos”- Visão Geral e Objetivos do Sistema
- Arquitetura de Alto Nível (Diagramas Mermaid)
- Modelo de Dados e Esquema ER D1 (SQLite)
- Gestão de Estado Frontend (Zustand + TanStack Query)
- Fluxos Principais da Aplicação (Diagramas de Sequência)
- Análise Detalhada dos 7 Módulos de Domínio
- Integração de Comunicação Omnichannel & WhatsApp
- Camada de Inteligência Artificial (Gemini API)
- Segurança, Autenticação e Impersonação
- Guia de Manutenção, Testes e Protocolo de Deploy
1. Visão Geral e Objetivos do Sistema
Section titled “1. Visão Geral e Objetivos do Sistema”No shell Android, o primeiro toque em Google Sign-In aguarda a inicialização serializada do provider mesmo que ela ainda esteja concluindo; ele não é descartado pelo estado visual de readiness, e o lock síncrono impede Activities duplicadas. A leitura deduplicada do Web Client ID tem teto de 12 segundos, combina cancelamento do consumidor e libera nova tentativa depois de falha ou desmontagem, portanto uma rede móvel degradada não prende o primeiro toque. O início de qualquer sessão nova cancela também a restauração inicial de /auth/me; essa fronteira cobre WebViews que respondem depois do abort e impede que a conta anterior apareça durante uma tentativa de senha, Google, Apple, telefone, biometria, magic link ou impersonação. Logout é uma operação idempotente compartilhada entre Perfil, chat e navegação por useLogoutAction: a trava precede inclusive confirmações, cada acionador preserva nome/aria-busy e feedback de seleção, e nenhum produz sucesso tátil antecipado. A identidade local é removida imediatamente, enquanto limpeza de push, provider e cookie termina com timeout e navegação de segurança. Durante essa janela, nenhuma porta de criação de sessão — senha, Google, Apple, biometria, telefone ou magic link — inicia um cookie novo na mesma árvore React, evitando que a resposta tardia de logout o apague. Na troca de identidade, o CloudClient também aborta requests autenticados em voo — leitura, mutação e multipart — e mantém a geração como segunda barreira contra replay ou publicação tardia sob a nova conta. Leituras e ações autenticadas fora dos fluxos de transporte especiais — Perfil, catálogo de carpetes, fila de exclusão, auditoria de erros e QuickBooks — usam esse mesmo cliente, para que nem uma resposta tardia nem uma mutação iniciada pelo usuário anterior possam alcançar a sessão seguinte. O deep link de uma notificação que alcança a PWA/WebView antes da restauração é guardado exclusivamente com o destinatário vindo do envelope de push; a comparação só acontece quando a identidade reaparece, evitando tanto perder o clique legítimo quanto entregar chat/tarefa a uma conta trocada. Essa mesma prova agora entra nos atalhos dinâmicos de conversa do launcher Android, não só nos banners: um atalho que sobreviva momentaneamente ao logout não navega a identidade seguinte para a thread anterior. A audiência autorizada do Service Worker fica em cache estável, separado do cache versionado do bundle; atualizações preservam a capacidade de receber push válido com o app fechado, e o logout continua removendo a prova antes que conteúdo da sessão anterior possa voltar à bandeja. A mesma audiência é exigida antes de o evento pushsubscriptionchange renovar e persistir uma assinatura Web Push: depois do logout o worker ainda pode avisar uma aba aberta, mas nunca registra um endpoint substituto enquanto o cookie antigo pode estar em revogação.
A exclusão de conta trava antes da confirmação, não depois do primeiro await, e seu POST possui teto de 15 segundos. Cancelamento libera o controle; falha restaura loading com mensagem recuperável; sucesso o mantém ocupado até a saída. Um epoch por identidade e cleanup de desmontagem impedem que uma resposta de outra conta ou tela altere o Perfil atual.
Vínculo Google no Perfil respeita o runtime: Android/iOS usam @capgo/capacitor-social-login, enquanto PWA e desktop usam Google Identity Services. A leitura da configuração pública via /api/boot usa o transporte limitado de 12 segundos, inclui as credenciais da sessão, é cancelada no teardown e reiniciada por identidade depois de limpar o Client ID anterior; uma resposta tardia não configura outra conta. Inicialização nativa é serializada, o primeiro toque aguarda readiness sem ser descartado e todo callback captura o owner da sessão; trocar de conta durante o sheet ou popup impede o vínculo de alcançar a nova identidade. O unlink também trava antes da confirmação e publica sucesso somente após o DELETE aceito pelo servidor.
Mutações do Perfil são isoladas por identidade. Salvar dados trava antes das gravações de cliente/funcionário e só atualiza sessão/toast/loading se o epoch ainda pertence ao usuário original. Ativar/desativar passkey usa a mesma fronteira em torno do prompt do sistema; a remoção local acontece somente após resposta HTTP bem-sucedida do servidor, portanto uma falha não deixa credencial ativa acompanhada de falso “Biometrics Disabled”.
Impersonação administrativa aplica lock síncrono e epoch da identidade na interface. Seleção não é anunciada como sucesso: confirmação tátil acontece apenas após autorização, confirmação do cookie e limpeza do conteúdo privado; falha restaura o controle com feedback visível, e respostas de um lifecycle antigo não alteram a tela. O carregador de autenticação permanece ativo durante a navegação bem-sucedida e só é removido no caminho de erro.
O Prime Crown é uma plataforma SaaS full-stack para a gestão completa de serviços de limpeza residencial de alto padrão. O sistema automatiza desde a captura do cliente na Web (orçamento em tempo real), passando pelo agendamento inteligente com otimização geográfica de rotas, telemetria de campo por funcionárias, atendimento de chat omnichannel via WhatsApp até o faturamento fiscal automático e o fechamento da folha de pagamento.
A interface React é compartilhada por navegador/PWA e shells Capacitor para Android e iOS. Os projetos nativos vivem em android/ e ios/ e abrem a aplicação publicada em https://app.primecrowncleaning.co.uk, mantendo a origem canônica exigida pelas rotas relativas /api, cookies de sessão HttpOnly, OAuth e WebAuthn. O dist/ ainda é sincronizado para os projetos nativos como artefato de build, mas não deve ser tratado como modo offline da aplicação autenticada. A detecção central fica em src/shared/platform/runtime.ts; integrações nativas devem ser implementadas por providers com fallback web, sem bifurcar os modelos de domínio ou os fluxos de estado. O diagnóstico de boot usa a mesma autoridade e rotula separadamente Android App, iOS App, PWA instalada e Browser/Desktop; uma WebView Capacitor nunca aparece no suporte como navegador comum apenas por não publicar display-mode: standalone.
A auditoria remota do schema também faz parte do gate operacional. A migração 0126 restaura os índices de telefone da conta e e-mail de recuperação removidos pela reconstrução de tabelas da migração 0115, além de materializar o índice de itens ativos do catálogo de carpetes que já constava no schema-base. Os índices preexistentes de assinatura push por usuário e adiantamento por folha também estão espelhados no schema-base e no Drizzle, deixando de depender de exceções da auditoria. São mudanças aditivas e idempotentes; db/schema.sql, Drizzle e D1 remoto devem continuar sem drift.
O shell de autenticação responde também à altura útil: em orientação horizontal com até 560 px, cabeçalho, corpo e opções usam a composição compacta compartilhada, mantendo os métodos primários visíveis sem alterar o retrato. A região externa continua rolável para cadastro, recuperação e campos expandidos quando teclado, split-screen ou uma janela desktop curta reduzirem ainda mais o viewport.
O Worker chat-do mantém dois triggers independentes: manutenção idempotente a cada cinco minutos e Google Business Profile às segundas 09:00 UTC. A rotina semanal é selecionada exclusivamente por event.cron === "0 9 * * 1"; ela não usa inferência pelo relógio, pois o evento de manutenção das 09:00/09:05 também cairia nessa janela e duplicaria publicação/sincronização. Todas as chamadas permanecem reunidas em Promise.allSettled(tasks) sob ctx.waitUntil().
As entradas públicas /quote, /pay, /statement, /proposal e /rate são reconhecidas por segmento completo: somente o caminho-base ou seus descendentes são aceitos. Prefixos coincidentes, como a rota autenticada /payroll, continuam no shell principal; esse contrato evita que links internos sejam capturados por uma página pública em navegador, PWA ou WebView.
As superfícies públicas de cotação, fatura, extrato, proposta de horário e avaliação usam o viewport seguro e um transporte limitado compartilhado: leituras têm teto de 12 segundos, mutações de 15 segundos e ambas são canceladas ao desmontar. A mesma primitiva protege o envio autenticado de Request Service, que preserva o lock síncrono e retorna ao estado interativo em timeout. Falha de rede/servidor nunca vira falso “not found”; somente 404 representa ausência e os quatro portais de link oferecem retry explícito. Fatura e extrato copiam dados pelo provider que seleciona Clipboard nativo ou fallback web e somente confirmam sucesso depois da escrita real. Até existir uma integração PISP credenciada, elas não simulam Open Banking nem enviam sort code/account number a um domínio intermediário: orientam a transferência pelo aplicativo bancário do cliente. Proposta e avaliação possuem lock síncrono além do estado visual, impedindo dois POSTs antes do próximo render. stars recebido na URL é arredondado e limitado a 1–5, o comentário é aparado e CFInput, Button e IconBadge alinham campos, loading e toque nas quatro experiências.
Os modais de conciliação bancária e QuickBooks usam useModalLifecycle: registram-se na pilha compartilhada de Back/History, recebem z-index acima da camada anterior, contêm e restauram foco, travam o scroll da página e tratam Escape somente quando são o topo. Ambos preservam safe areas, possuem lock síncrono contra toque concorrente e recusam fechamento durante conciliação, exportação ou sincronização, evitando duplicar ou perder o resultado de uma operação financeira em andamento. Seus transportes são limitados a 15 segundos e recebem o AbortSignal da superfície; fechar/desmontar cancela trabalho tardio. QuickBooks congela filtros e seleção enquanto opera e somente success: true do servidor produz háptico de sucesso e fechamento. Conciliação preserva relatório/seleção após falha e limpa a referência do request ao terminar, mantendo retry honesto em web, PWA, Android e iOS.
Manual da residência, pausa de férias e aviso de trânsito também adotam esse lifecycle, preservando Back/Escape, foco, scroll e safe areas em desktop, PWA e WebViews. Pausa e trânsito usam locks síncronos, mutações limitadas a 15 segundos e controllers associados ao cliente/pedido visível; fechar, desmontar ou trocar owner aborta o transporte, e uma resposta tardia não publica store, cache, toast, háptico ou fechamento. Datas e presets ficam congelados durante a ação. A pausa de férias não percorre mais visitas pelo cliente: /api/scheduling/holiday-suspension cancela somente PENDING, PENDING_REVIEW e SCHEDULED em um único UPDATE, zera a receita faturável preservando preço/VAT originais e incrementa versões. holiday_suspensions torna a intenção auditável e retomável pelo mesmo UUID; perder a resposta e tentar novamente devolve o resultado original sem nova mutação. A custódia de chaves é outro domínio D1 real: key_tags mantém o inventário e key_custody_records a trilha imutável. Triggers criam o evento no mesmo statement da transição, e version + estado esperado recusam retirada/devolução concorrente com 409. Ambos os endpoints restringem dados a ADMIN/MANAGER e as interfaces só confirmam o estado autoritativo. As duas interfaces usam os primitives oficiais (Button, CFInput, CFSelect, CFKpiCard, CFEmptyState, IconBadge e HubToolbar), superfícies semânticas e breakpoints móveis; a retirada exige seleção explícita do responsável e nunca escolhe silenciosamente a primeira pessoa da equipe.
Relatos de incidente e o passo correspondente do fechamento de turno compartilham CFSelect, CFInput, IconBadge e Button, seleção aria-pressed, superfícies semânticas e layout adaptativo. A descrição é normalizada e um lock síncrono impede dois relatórios no mesmo toque. A análise por IA aceita somente uma execução, aborta no teardown e transforma falha em alerta visível com retry, em vez de deixar apenas um erro no console.
As operações de turno leem o snapshot corrente de requestsStore imediatamente antes de calcular check-in, check-out ou finalização, aplicam uma substituição local concreta e somente então disparam sync/log/feedback. Assim efeitos externos não ficam dentro de atualizadores que React ou Zustand podem reinvocar, sinais sequenciais no mesmo frame não perdem o check-in anterior e uma solicitação ausente não gera toast de finalização bem-sucedida nas quatro plataformas.
As ações genéricas updateRequest e atomicBatchUpdate seguem o mesmo limite de pureza. Elas calculam o próximo array pelo snapshot atual, publicam uma única vez e só então executam syncAtomic; o batch persiste apenas os itens encontrados e alterados. Nenhum request de rede nasce dentro do callback de set, evitando gravação duplicada sob middleware, debug ou reexecução do updater.
Quando uma mesma tarefa recebe alterações rápidas, syncAtomic as serializa e não invalida o cache TanStack após uma confirmação intermediária. A projeção otimista continua visível até o último item da fila encerrar; somente então ocorre uma releitura autoritativa, também em caso de erro. A fila carrega a geração de identidade que a criou: logout, login ou revogação impedem um sucessor atrasado de usar o cookie da nova conta, e uma fila antiga com ID coincidente não bloqueia a gravação da sessão recém-iniciada nem invalida seu cache. Assim uma resposta inicial não pode fazer PWA, desktop, Android ou iOS exibirem transitoriamente um estado anterior à alteração já enfileirada ou cruzarem contas.
O gate automatizado de pureza reconhece setters React e o set do Zustand. A recarga de carteira do cliente foi alinhada ao contrato: o updater calcula e publica somente dados, depois a API persiste o objeto capturado; falha reverte apenas se aquela versão ainda for proprietária. Isso impede crédito/request duplicado e protege uma edição posterior do cliente.
Alocação, propagação de equipe para recorrências, conclusão manual e override de status também calculam snapshots fora dos updaters. Um mapa de ownership por request bloqueia mutações concorrentes no mesmo frame e condiciona rollback à tentativa ativa; reagendamento, cancelamento, reversão e decisões de aprovação também comparam a versão otimista antes de restaurar o snapshot anterior. O lifecycle limpa os owners no teardown e toda resposta assíncrona de save, ocorrência ou notificação confere atividade antes de alterar store ou feedback. Isso elimina persistência duplicada sob Strict Mode e conclusão tardia após troca de sessão em desktop, PWA e shells nativos.
Identificadores UUID criados no cliente passam por src/shared/uuid.ts. Navegadores modernos usam crypto.randomUUID; as primeiras versões suportadas do iOS 15 usam o fallback RFC 4122 v4 baseado em crypto.getRandomValues. Pedidos, grupos recorrentes, clientes/endereço, mensagens/toasts, incidentes, suprimentos, logs, telemetria, pausa idempotente, instalação push, uploads e importação CSV não dependem mais de uma API ausente nesses WebViews. npm run pwa:doctor percorre todo o código de produção e recusa qualquer nova geração de identificador baseada em Math.random.
O projeto iOS tem bundle ID uk.co.primecrowncleaning.app, deployment target iOS 15 e scripts ios:sync, ios:open e ios:run. O Info.plist declara câmera, localização enquanto em uso, microfone e o scheme primecrown://. App.entitlements prepara Universal Links, credenciais compartilhadas e o ambiente APNs por configuração; AppDelegate.swift encaminha o device token ao plugin Capacitor. ios:doctor deriva das dependências instaladas todos os pacotes que declaram suporte Capacitor iOS e exige que os 21 apareçam no Swift Package e na lista de classes gerada; também compara bundle, origem HTTPS, cleartext e App-Bound Domains no capacitor.config.json copiado. functions/.well-known/apple-app-site-association.ts publica a associação usando APPLE_TEAM_ID do Cloudflare. Assinatura, credenciais APNs, App Store Connect e OAuth iOS continuam dependentes da conta Apple e devem ser concluídos antes do TestFlight.
O gate compartilhado de release captura o commit antes de qualquer acesso ao cofre e aceita somente um índice/worktree sem alterações rastreadas; arquivos não rastreados permanecem fora do snapshot. Android e iOS repetem a verificação depois do sync/build e antes do upload, exigindo o mesmo HEAD. Isso impede que um AAB/IPA contenha código ausente da tag, inclusive se uma ferramenta de build regenerar arquivo versionado ou se ocorrer um commit concorrente. Os doctors das duas plataformas validam que o wrapper automático e o script direto preservam essa fronteira.
No Perfil, a lista de dispositivos push separa ready, loading, error e o snapshot. Uma falha de /api/push/devices não apaga mais dispositivos nem produz o falso vazio No devices subscribed yet; o snapshot anterior permanece com alerta e retry. Sem snapshot, a tela informa que ainda está verificando ou que a leitura falhou, e o diagnóstico Android não declara o registro backend ausente enquanto a fonte está indisponível. Ticket da identidade, abort do lifecycle e single-flight com passe final protegem o mesmo contrato em web, PWA e shells nativos.
Séries abandonadas no Ops Commander dependem da leitura autoritativa de recurring_series. O controller e o badge da Sidebar compartilham useRecurringSeriesQuery; enquanto a fonte carrega ou falha, nenhum dos dois interpreta grupos terminados desconhecidos como problemas ativos. A página mantém alerta com retry e não mostra all clear baseado em evidência incompleta. Retomar e encerrar usam locks síncronos, epoch da sessão e confirmação explícita do endpoint; somente uma mutação aceita atualiza o cache e remove o cartão, evitando duplicação por toque e conclusão tardia em outra conta nos quatro runtimes.
Preferências de categorias push separam o cache local do snapshot confirmado pelo servidor. pushPreferencesState carrega owner, readiness, loading e erro; login, foreground e retry usam sequência latest-wins e recusam resposta inválida/offline. O Profile bloqueia somente os toggles server-side até a confirmação, mantendo som, mute da Inbox e duração como preferências locais independentes. O save adquire lock síncrono e valida success; recusa restaura somente as categorias anteriores no React e no storage, mantém outras alterações locais e publica alerta/toast. Epoch de sessão impede que leitura, rollback ou conclusão de uma conta alcance outra em desktop, PWA, Android ou iOS.
Fotos operacionais de chat, checklist e evidência usam cameraProvider. Android/iOS chamam a API atual Camera.takePhoto com câmera traseira, JPEG, correção de orientação, limite de 1920 px e saveToGallery: false; o caminho depreciado Camera.getPhoto não faz mais parte da aplicação. O PWA preserva capture="environment". Cancelamento retorna null em todos os casos, enquanto leitura/captura inválida continua sendo falha real.
O PrivacyInfo.xcprivacy está incluído nos Resources do target, declara ausência de tracking, os required reasons CA92.1 (preferências) e C617.1 (metadados de arquivos no contêiner), e as categorias operacionais vinculadas à conta descritas na política pública.
No iOS, limitsNavigationsToAppBoundDomains e WKAppBoundDomains restringem o bridge Capacitor à origem oficial. Links externos usam o navegador nativo pelo externalBrowserProvider; ações fire-and-forget passam por launchExternalUrl, que contém rejeições do plugin, reivindica cada URL sincronamente contra toque duplo e permite feedback contextual sem gerar promessa não tratada. Sem callback próprio, uma falha produz feedback tátil e toast recuperável. Evidências de incidentes abrem no lightbox compartilhado, preservando preview autenticado e entrega externa segura em vez de enviar a URL para outra sessão de navegador. Privacidade e Termos permanecem acessíveis diretamente no Profile. O envio à App Review requer uma conta de demonstração externa ao repositório, Review Notes para os recursos protegidos e validação final do archive em iPhone físico/TestFlight.
Exportações compartilhadas de relatórios, gráficos, usuários, histórico, payslips, faturas e QuickBooks usam locks síncronos em ref antes do primeiro await; o estado React é apenas visual. Toques repetidos no mesmo frame não duplicam a geração nem abrem duas share sheets, e cada lock é liberado em finally nas quatro experiências.
Fotos de evidência do checklist mantêm lock e estado ocupado da captura/seletor até o upload terminar, inclusive quando o Android restaura o resultado da câmera após recriar a WebView. Epoch, permissão de edição e AbortController impedem conclusão em outra tarefa/sessão; cancelamentos permanecem silenciosos e falhas reais mostram spinner, toast recuperável e háptico nas quatro experiências.
O listener de recuperação da câmera também contém falha de upload: um arquivo devolvido depois de Android recriar a WebView pode encontrar rede indisponível, mas sua promessa não vaza do event listener. Enquanto o mesmo item e epoch continuam válidos, o checklist encerra o estado ocupado e mostra toast/háptico recuperável; desmontagem, troca de tarefa ou perda de edição continuam descartando a conclusão sem publicar feedback no destino seguinte.
O composer mantém a prévia local de uma mensagem de voz até o backend confirmar upload e envio/agendamento. O contrato retorna um resultado autoritativo, um lock síncrono impede toque duplo e falha/timeout preserva a gravação para retry; a troca de conversa invalida o ticket e impede que uma conclusão antiga limpe o composer novo.
Texto agendado só sai do composer depois da confirmação autoritativa e apenas se ainda corresponder ao snapshot enviado; falha mantém texto e menu para retry, sem apagar edição mais nova. Agendamento e rascunho por IA reivindicam locks síncronos antes do primeiro await e usam epoch por usuário/conversa nas quatro experiências.
Ao vencer, uma agenda pode ser observada pelo cron e pelo drain disparado por /channels ao mesmo tempo. dispatchDueScheduledMessages usa scheduled:<id> como chave externa única no insert de messages; somente quem vence a inserção materializa, notifica e encaminha a mensagem, eliminando duplicação de chat e WhatsApp sob concorrência.
Sign in with Apple usa functions/lib/appleIdentity.ts para validar criptograficamente o ID token contra o JWKS público da Apple, issuer, audience, expiração e subject. POST /api/auth/apple vincula primeiro pelo identificador estável, exige e-mail Apple verificado apenas no primeiro vínculo/criação, suporta relay privado e emite a sessão HttpOnly compartilhada. O authorization code é trocado server-side por functions/lib/appleOAuth.ts; o refresh token fica cifrado em D1 e é revogado pela API oficial da Apple quando a exclusão é solicitada. Capability, entitlement e provider nativo estão incluídos; login e cadastro exibem o botão Apple somente no runtime iOS, sem alterar Android ou PWA.
Profile possui uma aba About com versão web, plataforma, versão/build nativos e acesso direto a Privacy e Terms. A área destrutiva fica visualmente separada e permite iniciar exclusão sem sair para e-mail: POST /api/auth/account-deletion persiste uma solicitação idempotente em account_deletion_requests, registra deletion_due_at em 30 dias, marca a conta como inativa, revoga todas as sessões, bloqueia novo acesso e limpa os cookies. Todos os administradores recebem aviso por e-mail para revisar a solicitação em Settings → Account Deletions; falha do Resend é auditada sem reativar a conta. A resolução por /api/auth/admin/account-deletions exige confirmar a revisão de retenção e registra status, horário e responsável. A fila administrativa serializa confirmação, resolução e retries por um lock síncrono global, limita mutações a 15 segundos e cancela leituras antigas; outros itens também ficam desabilitados enquanto uma decisão está em voo. Revogação de acesso da equipe compartilha o mesmo teto de rede. A conclusão ou rejeição dispara confirmação ao usuário. A conclusão operacional remove ou anonimiza dados sem base de retenção antes de marcar COMPLETED; /account-deletion oferece alternativa de contato somente para quem perdeu acesso ao aplicativo.
npm run ios:doctor audita os arquivos versionados e relata separadamente Xcode/credenciais ausentes; --strict transforma pendências externas em falha para uso no pipeline de release. O gate também verifica bundle ID, versão/build inicial, iOS mínimo, APNs de Release, criptografia isenta, ausência do requisito legado armv7 e as descrições de privacidade exigidas por câmera, geolocalização, microfone e biblioteca de fotos. O DOM recebe data-platform antes do primeiro render para que diferenças de safe area, scroll e interação sejam aplicadas por capacidade/plataforma sem duplicar os componentes de domínio.
O login Google segue essa separação por runtime. Navegador/PWA continuam usando Google Identity Services com redirect server-side como fallback; Android usa @capgo/capacitor-social-login para abrir o seletor nativo de contas e entrega o ID token ao mesmo endpoint e à mesma validação de sessão já usados pela web. Somente o provider Google é incluído no bundle. O preload disparado pela restauração de auth e o controller do login compartilham a mesma leitura tipada de /api/public/config, portanto uma abertura fria não baixa duas vezes a configuração pública para obter o webClientId; em falha, o single-flight é liberado para retry. O login Android usa os scopes OIDC padrão (openid, e-mail e perfil) fornecidos pelo próprio plugin; não envia options.scopes nem exige uma MainActivity customizada. Depois da troca, o cliente aguarda a confirmação real do cookie por /api/auth/me (com janela adequada à WebView) e só então confirma o usuário e recarrega; uma tentativa inconclusiva não navega de volta ao formulário como falso sucesso. Na web/PWA, slot e wrapper onde o GSI monta DOM e iframe cross-origin permanecem em 48 px; o iframe já nasce com os 44 px finais e é centralizado pelo CSS. A transição anterior de 22 para 44 px foi removida, portanto a alternância anônima/personalizada não desloca o card nem modifica o documento ou branding controlado pelo Google. O manifesto PWA não usa mais resposta stale-while-revalidate: worker e cabeçalhos fazem leitura de rede antes do fallback offline, para que theme_color e a barra superior adotem a revisão atual. As superfícies de login, redefinição de senha e verificação operacional usam o viewport dinâmico e o mesmo contrato de safe area do shell, acompanhando teclado, barras móveis e recortes sem criar uma página 100vh maior que a área visível. O OAuth client Android deve corresponder a uk.co.primecrowncleaning.app e possuir os SHA-1 das chaves que assinam cada variante instalada (upload/debug e Google Play App Signing), enquanto o webClientId continua sendo a audience validada pelo backend.
Os textos auxiliares e divisores da autenticação preservam contraste AA sobre o card branco. O documento raiz também publica uma descrição estável para navegadores e indexadores.
robots.txt e llms.txt são assets textuais explícitos, roteados antes do fallback da SPA: robôs não recebem index.html como se fosse uma política e as rotas de API, chat e guia interno permanecem excluídas. A telemetria de Web Vitals iniciada antes do React mantém apenas a métrica mais recente em memória enquanto a sessão HttpOnly é restaurada; autenticação confirmada descarrega a fila, enquanto uma tela anônima a descarta sem gerar POSTs 401 inúteis.
O fallback de navegação da SPA é o comportamento nativo do Cloudflare Pages, habilitado pela ausência de 404.html na raiz. _redirects não contém catch-all que forme ciclo com a canonicalização de /index.html; mantém apenas assets e rotas estáticas explícitas. /slides usa a canonicalização e o índice naturais do diretório. assets/404.html limita o fallback nessa subárvore, de modo que um chunk hash inexistente responde 404 real e nunca HTML 200.
A rota permanente /slides compõe o material visual de treinamento dos usuários. Os utilitários versionados scripts/capture-slide-*.mjs e scripts/capture-wizard-shots.mjs reproduzem as telas móveis a partir do ambiente local, usando um perfil isolado do Chrome e gravando as capturas em public/slides/img; eles não participam do bundle nem são executados em produção.
O seletor administrativo de simulação mantém somente a identidade corrente durante o boot e materializa as opções de funcionários/clientes ao receber foco ou toque. Ao perder foco, remove novamente essas opções extensas. O controle continua sendo um <select> nativo com nome acessível e picker do sistema, porém centenas de opções deixam de permanecer no DOM e na árvore de VoiceOver/TalkBack quando a ação não está em uso.
Cards e linhas do Dashboard consomem um índice de relacionamentos criado uma vez por seção. O índice resolve entidade fiscal e funcionário em O(1), prepara equipes atribuídas preservando a ordem global de exibição e calcula posição/total de cada recorrência agrupando e ordenando a série uma única vez. Isso elimina assinaturas fiscais por card e os antigos filtros/sorts multiplicados pela quantidade de visitas, sem alterar valores financeiros, avatares ou sequência visível.
A seção Verify bank claims renderiza 12 aprovações por etapa e mantém total/status acessível antes do botão de expansão. Um índice único relaciona cliente, entidade fiscal e visitas em ordem estável, removendo buscas completas e assinaturas fiscais por card. Aprovar e rejeitar compartilham lock síncrono contra toque duplo; finally sempre libera a operação após sucesso ou falha e o teardown impede atualização tardia da interface. O servidor continua sendo a autoridade da decisão financeira.
O progresso do orçamento público mantém contraste AA inclusive nos passos ainda inativos sobre o fundo claro. O link de retorno da marca inclui no nome acessível todo o texto visível “Prime Crown Cleaning Services”, evitando divergência entre reconhecimento de voz, leitor de tela e o rótulo apresentado em mobile e desktop.
O login biométrico usa passkeys WebAuthn descobríveis nos dois runtimes: a chave privada permanece no autenticador do dispositivo e somente a chave pública é persistida em D1. Em navegadores WebAuthn e nos shells nativos com provider empacotado, a capacidade é conhecida já no primeiro render, portanto o botão não entra depois e não desloca o cartão centralizado. A autenticação aceita autenticador de plataforma, provider de passkeys sincronizadas ou chave de segurança externa; sem e-mail, o autenticador seleciona uma credencial descobrível e o backend resolve a conta pelo credential ID verificado. Opções, verificação e remoção WebAuthn possuem teto de rede de 15 segundos; startRegistration e startAuthentication não recebem timeout cosmético, preservando o tempo legítimo do prompt biométrico ou de uma chave externa. O cliente persiste somente marcadores opacos para decidir o estado visual da conta; a migração v3 converte e remove as antigas chaves que continham e-mails completos. A dica temporária do login Google usa sessionStorage, desaparecendo ao encerrar a sessão do navegador. Respostas autenticadas nunca incluem password_hash; além da seleção mínima nos endpoints, mapRecord remove esse campo defensivamente de qualquer registro recebido.
Senha, Google, Apple, cadastro, telefone, solicitação/verificação de magic link, recuperação, redefinição, impersonação, vínculo Google e troca de senha compartilham o transporte limitado de mutação, com teto de 15 segundos. Os formulários públicos acrescentam lock síncrono e AbortController vinculado à tela; trocar de formulário, desmontar o login ou sair da redefinição cancela I/O e invalida a conclusão antiga. Após emissão do cookie, /api/auth/me é confirmado por até oito segundos, com cada tentativa limitada a dois segundos, preservando retry sem prender o ciclo inteiro em uma leitura. Assim browser, PWA, desktop e WebViews nunca dependem de um segundo toque nem permanecem indefinidamente em loading quando a conexão móvel degrada.
CloudClient atribui uma geração à sessão que iniciou cada leitura ou mutação autenticada. Logout, revogação remota, login bem-sucedido, magic link, biometria e impersonação invalidam a geração antes de a nova identidade poder usar o cookie. Uma resposta 401 antiga pode até terminar o transporte compartilhado de refresh, mas não é publicada nem repetida com a sessão seguinte; isso impede que dados de uma conta anterior alcancem a árvore que pertence ao novo usuário em browser, PWA, Android ou iOS. Repetição automática é exclusiva de leituras: uma falha de rede ou 5xx em POST/PUT/PATCH/DELETE/multipart não reenvia uma escrita cujo primeiro envio pode ter sido aceito, e as operações recuperáveis usam sua própria chave de idempotência.
Mutações atômicas versionadas do mesmo recurso passam por uma fila por endpoint+ID. A store de tarefas avança sua versão otimista a cada edição rápida, enquanto a fila entrega esses payloads ao Worker na sequência correspondente; se a primeira escrita for recusada, as posteriores são descartadas e o cache é revalidado, em vez de gerar uma cascata de conflitos 409 ou salvar parcialmente mudanças de uma tela. Cliente, profissional e tarefa aceitam apenas a versão persistida ou a sucessora imediata: o segundo formato mantém compatibilidade com helpers legados que já incrementam localmente, mas uma versão arbitrariamente futura de uma tela antiga não pode mais atravessar o compare-and-swap e sobrescrever a edição atual.
Quando o Chatwoot é o centralizador, a cópia de uma resposta humana de volta ao Prime Crown não assume que toda conversa pertence à Management. O webhook resolve primeiro a mensagem citada e, em seguida, metadados de contexto da conversa; canal, cliente, tarefa e estado aberto são validados no D1. Sem vínculo válido — inclusive citação de outro cliente ou tarefa encerrada — a resposta cai em DIRECT privado. Tanto essas respostas quanto a entrada do cliente recebem o phoneNumberId ativo, preservando a janela de 24 horas da linha que realmente atendeu a conversa mesmo após uma troca de configuração. Assim a centralização no mesmo número não expõe a conversa do gerente para o grupo da tarefa nem esconde uma resposta de tarefa da equipe correta.
Durante a autenticação biométrica, a tela apresenta somente o estado Signing in with Biometrics… e suspende temporariamente Google e senha, prevenindo tentativas concorrentes; cancelamento ou erro restaura as opções.
Os controles textuais do login e cadastro — expansão de email/senha, cadastro manual, recuperação, criação e retorno — mantêm alvo mínimo de 44 px e touch-manipulation. O rótulo continua visualmente leve, mas a área acionável atende polegar e toque impreciso nos mesmos componentes usados por PWA, Android e iOS.
No orçamento público, botões compactos de quantidade e duração mantêm a densidade visual do desktop e ganham área mínima de 44×44 px em dispositivos de ponteiro coarse por meio de touch-target. Ações de aumentar/diminuir incluem o serviço no nome acessível, e a seleção de adicional expõe aria-pressed, alinhando mouse, teclado, TalkBack e VoiceOver sem duplicar o fluxo por plataforma.
O avanço progressivo do formulário mantém somente um scroll atrasado por vez. Uma nova seleção substitui o destino anterior e teardown cancela a operação, impedindo que interações rápidas façam PWA, WebView ou desktop estreito saltar de volta para uma etapa já respondida.
A conversão manual de lead recebe obrigatoriamente o ID do cliente já salvo ou já vinculado à tarefa. O cadastro é aguardado antes de mover/consolidar a conversa; a store não cria uma segunda pessoa nem depende de setTimeout(0). Um singleFlight por lead coalesce repetições e sinaliza destino concorrente divergente. Destino ausente não altera o lead, e recusa do backend restaura somente o objeto otimista que ainda pertence àquela tentativa, preservando mudanças paralelas nos demais leads com feedback explícito nas quatro plataformas.
O wizard também trata catálogo, configuração e rascunho como entradas assíncronas independentes. Se os adicionais chegarem depois de uma seleção restaurada, suas durações mínimas são recalculadas; se o serviço chegar depois da frequência/endereço do rascunho, o progresso retorna ao piso correto em vez de parar no passo 2. A reconciliação preserva durações maiores escolhidas pelo visitante e nunca rebaixa o avanço atual. O contrato puro em quoteAsyncSync.test.ts cobre ambas as ordens de resolução compartilhadas por web, PWA, Android e iOS.
O catálogo administrativo de preços de carpetes também é autoritativo nas quatro plataformas. Leituras são limitadas, latest-wins e canceladas no teardown; loading, falha preservando snapshot e vazio confirmado não se confundem. Save/delete possuem timeout de 15 segundos, controller de lifecycle e lock síncrono compartilhado, adquirido antes da confirmação destrutiva. A interface desabilita as demais ações durante a mutação, comunica busy/sucesso/falha e só libera um novo item quando o catálogo foi realmente confirmado pelo servidor.
A Custódia de Chaves mantém o mesmo contrato em web/PWA, desktop e shells nativos. Leituras/mutações são limitadas a 12/15 segundos e recebem o AbortSignal do painel. Cadastro, retirada e devolução compartilham uma trava síncrona e um controller vinculado ao epoch da identidade; teardown ou troca de conta aborta a operação, descarta commits/toasts tardios e limpa imediatamente inventário e histórico sensíveis antes da nova leitura. Todos os controles conflitantes ficam realmente desabilitados durante a mutação, alinhando affordance visual, toque e autoridade do backend.
O transporte do orçamento público limita leituras a 12 segundos e mutações a 15 segundos, combinando esse prazo com o AbortSignal do consumidor. Catálogo, cálculo, rascunho de lead e confirmação são cancelados no teardown; cálculo e confirmação possuem locks síncronos contra duplo toque. Falha no catálogo expõe uma tentativa manual e as demais operações sempre devolvem a tela a um estado recuperável. Esse ciclo de vida único é usado por browser, PWA, desktop e WebViews Android/iOS.
UKAddressAutocomplete reconcilia a lista de cobertura de forma bidirecional: quando districts assíncronos passam a aceitar um postcode já resolvido, status, validação e completude retornam ao estado coberto sem exigir nova busca. O Reset centraliza a notificação ao proprietário e chama onReset exatamente uma vez, impedindo limpeza/remontagem duplicada no orçamento público e preservando o mesmo evento semântico em mouse, teclado e toque.
As chamadas externas de postcode e geocodificação do mesmo componente usam coordenação latest-wins, AbortController e limites de 12/8 segundos. Nova busca, Reset e teardown cancelam I/O anterior; verificações de geração impedem callbacks tardios de repor endereço ou coordenadas antigas. Timeout produz erro recuperável, e o cleanup da busca automática reabre seu gate na remontagem de ensaio do StrictMode. Assim uma rede móvel lenta não prende o wizard nem deixa uma resposta obsoleta atravessar navegação em web, PWA ou WebView.
Estados assíncronos de autenticação usam o mesmo contrato assistivo nos fluxos de entrada e cadastro: Google e biometria expõem um status ocupado com anúncio educado; Apple mantém o nome estável da ação, publica aria-busy e bloqueia nova ativação enquanto o provider responde. Spinners são decorativos, evitando que VoiceOver/TalkBack anunciem o ícone em vez da ação.
Ações inline que não usam os componentes compartilhados aplicam o mesmo estado aria-busy diretamente. Retomar/encerrar série, salvar chat, testar WhatsApp, analisar incidente/conflito e regenerar respostas rápidas bloqueiam ativação concorrente, preservam o rótulo textual ou nome explícito e ocultam o spinner decorativo; o carregamento inicial das respostas rápidas também é anunciado como status.
Falhas de login, cadastro, recuperação, redefinição e troca obrigatória de senha usam alert, enquanto confirmação de recuperação usa status educado. A troca obrigatória reutiliza o loading do Button em vez de apenas substituir o texto, e os controles de revelar senha têm nome e estado pressionado. O teste real do WhatsApp também diferencia sucesso (status) de falha (alert), mantendo feedback equivalente a anúncios nativos.
CFInput centraliza também a validação assistiva: o campo publica aria-invalid, referencia o texto com aria-describedby, anuncia erros dinâmicos como alert e mantém o ícone decorativo fora da árvore. Os seletores de autenticação por senha e cadastro manual publicam aria-expanded/aria-controls; assim o estado fechado/aberto é perceptível sem depender da rotação visual da seta.
Os demais controles-base seguem o mesmo princípio. CFSelect associa e anuncia erro como CFInput; CFCheckbox envolve um input checkbox nativo controlado no card visual; CFTabs implementa tablist com um único tab stop, aria-selected e navegação circular por setas, Home e End; CFPillSelector mantém aria-pressed. Ícones visuais são decorativos, e mouse/toque/haptics existentes permanecem inalterados.
Superfícies sobrepostas compartilham o contrato modal completo. AdaptiveBottomSheet e o lightbox do chat são diálogos nomeados/modais, travam a rolagem, recebem foco ao abrir, contêm Tab/Shift+Tab, restauram o elemento anterior e só aceitam Escape quando estão no topo da pilha usada também pelo back nativo. O lightbox preserva pinch/double-tap/pan, e sua entrega externa bloqueia repetição, publica aria-busy e mostra Opening… enquanto o provider de arquivo/navegador responde.
O drawer de navegação usa esse contrato apenas abaixo do breakpoint desktop: torna-se diálogo modal, move foco ao primeiro destino, contém Tab/Shift+Tab, trava a rolagem e restaura o gatilho inferior ao fechar. Escape fecha o drawer somente quando não há um modal acima; o back Android/iOS/PWA continua usando a hierarquia central de overlays. No desktop o mesmo componente permanece um landmark complementar, sem trap ou scroll lock.
Avisos persistentes seguem um contrato único de prioridade. ToastCard anuncia prompts comuns como status educado e permite modo assertivo somente para negação ou falha que exige atenção; PromptToast bloqueia ativações repetidas, publica aria-busy e preserva o nome original da ação durante o processamento. O opt-in de WhatsApp reforça esse limite com lock síncrono e epoch de lifecycle: não aceita segundo toque ou dismiss durante a gravação, aguarda saveClient, mantém o prompt para retry quando o store reverte e só emite háptico/toast de sucesso depois da confirmação backend; o antigo delay cosmético foi removido. Falhas operacionais do WhatsApp e comunicados críticos usam alertas, enquanto comunicados informativos/de aviso permanecem status educados. Pontos pulsantes e ícones são decorativos, e todo dismiss tem nome explícito para VoiceOver, TalkBack e leitores de tela no desktop/PWA.
O NativeBridge conecta o lifecycle Android/iOS ao focusManager do TanStack Query, permanece montado durante carregamento e login, aplica no Android a hierarquia do botão voltar (overlays → Dashboard → encerrar app) e recebe deep links nos dois shells. O Query só fica focado quando o shell está ativo e a WebView está visível; appStateChange: true recebido antes de visibilitychange: visible não antecipa refetch ou mutação de cache. Na montagem, App.getState() estabelece foreground/background sem disparar uma retomada artificial; quando o shell nasce já em background, porém, a pausa inicial é publicada aos consumidores já montados para impedir trabalho, polling ou captura em segundo plano. appLifecycleReconciler impede que essa leitura assíncrona sobrescreva um evento appStateChange mais recente ou sobreviva ao teardown. Um guard avulso do lifecycle, quando não há assinantes, também relê o estado atual da WebView e do shell antes de autorizar trabalho de foreground; assim um callback tardio não usa um valor em memória anterior ao app switcher. Sua política de toque longo remove menus de imagem/link próprios da WebView no app instalado, mas preserva clique direito físico, modificadores, edição de campos e o menu de cópia quando existe texto selecionado. Plugins exclusivos do shell são importados dinamicamente depois da confirmação do runtime ou da ação nativa, exceto os proxies críticos Push Notifications e Preferences mantidos eager para recuperação de inscrição sem rede adicional. Lifecycle, privacidade, status bar, haptics, login social, badge, atualização, teclado, rede, splash, configurações, câmera, localização, clipboard, navegador externo, filesystem e share sheet permanecem sob demanda. appInfoProvider lê versão/build do pacote somente ao abrir About e identifica separadamente Android, iOS, PWA instalada e desktop/browser; nenhuma visita comum ao Perfil consulta a bridge. Providers que registram listeners de forma assíncrona mantêm uma flag de atividade e removem imediatamente qualquer listener resolvido depois do cleanup, evitando vazamento ao desmontar durante o import(). A fronteira de logout/revogação limpa clientes, tarefas e também configuração/logs operacionais em memória, inclusive o marcador de erros vistos, antes que outra conta possa renderizar. Destinos externos que chegam antes da restauração da sessão ou do boot ficam em uma fila de intenção única na sessão da WebView, sobrevivem ao reload de autenticação e são consumidos quando usuário e dados estão prontos; mensagens do service worker usam o mesmo caminho, mantendo PWA, Android e iOS alinhados. src/shared/platform/nativeNavigation.ts valida apenas o domínio oficial e o scheme privado, aceitando tanto primecrown://chat quanto caminhos HTTPS e convertendo-os nos mesmos ViewState, reqId e channelId usados pelo PWA. Um App/Universal Link comum é apenas destino: recipientUserId na query é ignorado; só o envelope Web Push/FCM/APNs validado pelo transport pode anexar essa prova de audiência. Antes de navegar, canRoleAccessView aplica a matriz RBAC também a links nativos, parâmetros web e mensagens do service worker; AppRoutes repete a proteção defensivamente. Detecção nativa consulta getRuntimePlatform() antes de qualquer fallback por user-agent, evitando classificar iPad/WebView como desktop e garantindo instruções corretas de permissões e calendário. O manifesto Android declara App Links para app.primecrowncleaning.co.uk. src/shared/platform/androidAppLinks.ts é o contrato dos certificados; functions/.well-known/assetlinks.json.ts o publica explicitamente pelo Pages e public/.well-known/assetlinks.json permanece como fallback estático. Os SHA-256 da upload key e da app signing key do Google Play permitem links verificados tanto em builds locais assinados quanto em instalações distribuídas pela loja.
CloudClient também fecha a fronteira de identidade no transporte: cada request autenticado captura uma geração, é abortado no logout/login e recusa resultado ou replay de geração anterior. O refresh compartilhado só remove a própria referência se ainda for o voo atual; por isso um refresh lento da sessão anterior não apaga o single-flight da nova conta nem provoca dois refreshes concorrentes em web, PWA ou WebViews Android/iOS.
O estado da conversa ativa, usado pelo renderer Android para suprimir somente a notificação do chat que está aberto, consulta isNativePlatform() antes de importar Preferences. Em browser, PWA e desktop ele permanece exclusivamente em memória; abrir ou trocar de conversa não chama uma ponte Capacitor sem consumidor.
O Inbox associa a seleção de canal à conta autenticada. Impersonação ou qualquer troca de identidade limpa canal, detalhe mobile e filtro antes de a nova conta usar a tela, o que também remove o marcador nativo de conversa ativa; uma UUID de chat da conta anterior não pode sobreviver para suprimir ou marcar como lida uma notificação da conta seguinte.
A fila offline de chat é segregada por ownerUserId, mas sua chave IndexedDB é o externalId idempotente (UUID). Por isso, a leitura que reconstrói e envia rascunhos na reconexão ordena explicitamente por createdAt: duas mensagens compostas offline chegam ao canal na ordem humana de criação, sem usar a ordem aleatória da chave. Registros antigos sem timestamp permanecem determinísticos e não ultrapassam rascunhos datados.
O webhook Meta confirma mídia inbound somente depois de o download protegido e a gravação R2 concluírem. Falha temporária responde 503, para a Meta reentregar: como a mensagem já pode ter vencido a chave única external_id, o caminho de duplicata encontra essa linha e repara exclusivamente o anexo, sem redobrar roteamento, push, janela de 24 horas ou automação.
CommandPalette e SearchIntelligenceService são carregados somente quando a pesquisa global abre. Ctrl/Cmd+K mantém resposta imediata com um status modal acessível durante a transição; o índice de busca não ocupa o shell de usuários que não usam essa função.
MobileRequirementGate é uma fronteira lazy condicionada a EMPLOYEE/MANAGER; durante a leitura do chunk, uma tela anunciada e bloqueante preserva a precedência do gate. O modal detalhado de localização negada também só é carregado quando necessário. Clientes e administradores não baixam instruções e integrações exclusivas do onboarding operacional.
As telas de login e redefinição de senha são carregadas apenas na rota/estado correspondente, fora do shell autenticado. O modal de troca obrigatória também forma uma fronteira lazy condicionada a mustChangePassword, com fallback de segurança bloqueante enquanto o chunk chega; o aviso de nova versão só é solicitado quando há atualização a apresentar.
O shell divide integrações contínuas por função: somente EMPLOYEE carrega o tracker e a recuperação de GPS; somente ADMIN/MANAGER carrega o monitor e os banners de saúde do WhatsApp. O monitor administrativo revalida no visibilitychange, evita requests sobrepostos e ignora respostas resolvidas após desmontagem, cobrindo retorno do background e troca de sessão sem estado tardio.
NativeBridge é uma fronteira lazy condicionada por isNativePlatform(): somente os shells Capacitor carregam lifecycle App, Back Android, launch/deep links, câmera restaurada, teclado, rede, privacy screen e push. A supressão seletiva do menu de toque longo fica no pequeno InstalledContextMenuGuard, compartilhado com PWA e preservando seleção, campos editáveis e clique direito físico sem importar a ponte nativa no browser/desktop.
O gesto pull-to-refresh do shell é carregado somente em dispositivos com entrada touch (maxTouchPoints ou ponteiro coarse). Desktop convencional não baixa o controller/indicador/hápticos nem registra eventos touch; Android, iOS, PWA móvel e computadores híbridos preservam soft refresh. O Chat mantém gestos próprios nos seus scroll roots, e o hook comum também recusa listeners quando o runtime não oferece touch.
Conectividade é multiplexada pelo networkProvider: no Capacitor todos os consumidores dividem um listener do plugin Network; no browser/PWA/desktop dividem um único par de eventos online/offline. Layout, verificação de atualização e flush da fila de chat recebem o mesmo estado sem três pares globais concorrentes; callbacks duplicados são contados separadamente e o listener físico só sai após a última inscrição.
O sincronizador de badge do launcher é carregado por capacidade: Android/iOS sempre o habilitam; browser/PWA apenas quando a Badge API expõe setAppBadge ou clearAppBadge. Desktop incompatível não baixa hook/provider nem executa promises sem efeito. A fronteira preserva serialização/latest-wins e desmonta junto do MainLayout, limpando o contador da identidade anterior no logout ou troca de conta.
A detecção de conectividade continua imediata e global, porém o OfflineBanner completo é uma fronteira lazy montada apenas quando isOnline fica falso. Durante a leitura do chunk, um fallback leve, visualmente equivalente, com role=status, aria-live=polite e a mesma mensagem honesta informa que updates pararam e somente mensagens de chat serão reenviadas; sessões online não baixam essa UI.
Preferências críticas do shell passam por uiPreferenceStorage, adaptador síncrono exclusivo para estado visual. Ele tenta localStorage e mantém um espelho/fallback em memória quando o navegador, modo privado, sandbox ou WebView bloqueia acesso. Assim a leitura inicial e os toggles de sidebar, háptico e notificações do chat nunca derrubam o app e continuam funcionando na sessão; HapticsService consulta o mesmo adaptador, portanto a vibração não diverge do estado mostrado na tela quando a persistência está bloqueada. Nenhum dado de negócio ou identidade usa esse adaptador.
O push nativo recebe um AbortSignal do NativeBridge: desmontagem interrompe inicialização parcial, remove imediatamente listeners já registrados, remove uma única vez handles que resolvam depois e cancela saves de token. Callbacks de Back e resultado restaurado da câmera também consultam active dentro do listener, impedindo saída/navegação ou entrega de mídia no intervalo anterior à remoção assíncrona do Capacitor. A câmera atribui uma geração a cada resultado restaurado: cancelamento, erro, logout ou um callback posterior invalidam a conversão/entrega da foto anterior ainda em voo, portanto nenhuma superfície recebe uma captura que já foi superada.
O teclado nativo registra Show/Hide como um par atômico, com isolamento de falhas e cleanup idempotente. Se qualquer registro falhar, todo handle parcial é removido imediatamente e os safe areas são restaurados; assim um listener de Show nunca pode deslocar a interface sem existir o Hide correspondente. Se um handle resolver depois do teardown, ele também é removido imediatamente e uma única vez. A restauração dos safe areas ocorre sincronamente no cleanup e também ao entrar em background: Android/iOS podem ocultar o teclado sem entregar keyboardWillHide, portanto nenhum inset reduzido sobrevive ao retorno a outra tela. Um keyboardWillShow que tenha ficado enfileirado antes da pausa também é ignorado até o lifecycle voltar ao foreground, evitando que a WebView em background reaplique um inset temporário sem o Hide correspondente. Rodapés de bottom sheets, disponibilidade e toasts fixos consomem as variáveis vivas --safe-*/--content-safe-*, em vez de congelar diretamente o inset do navegador; teclado, rotação e mudanças da barra do sistema reposicionam também essas superfícies. No bottom sheet full, o inset superior pertence ao contêiner inteiro do cabeçalho, mantendo título, ações extras e fechar abaixo do notch/Dynamic Island; variantes parciais não somam esse inset novamente porque já começam abaixo do topo. Quando o header padrão é ocultado, o próprio sheet reserva os insets antes e depois do conteúdo customizado; perfil e configurações ficam fora da barra de gestos. A conversa declara explicitamente que seu composer já possui pb-safe-gap, evitando dupla reserva.
O watch compartilhado de localização respeita ownership por AbortSignal antes e depois do carregamento do plugin. Um owner já desmontado não inicia localização nativa; cancelamento durante o registro limpa o ID que resolver tardiamente, e rejeições removem o listener de abort antes de retornarem ao chamador.
O provider de conectividade compartilha um único listener do plugin entre consumidores, mantendo contagem por callback para preservar assinaturas de owners distintos mesmo quando reutilizam a mesma função. O disposer de cada assinatura é idempotente, e o handle Capacitor só é removido quando a contagem global chega a zero.
A sincronização da status bar aplica CSS e theme-color imediatamente, mas serializa o plugin nativo por geração. Uma mudança mais recente invalida intenções ainda aguardando carregamento, sempre é aplicada depois de uma chamada já iniciada e continua mesmo que a operação anterior falhe; assim, retomadas e trocas rápidas de tema não deixam contraste antigo nos ícones do sistema.
O badge do ícone compartilha uma fila latest-wins entre o plugin Android/iOS e a App Badge API da PWA. Escritas em andamento são respeitadas para evitar inversão, enquanto contagens intermediárias ainda na fila são coalescidas na intenção mais recente; a limpeza disparada no logout continua ordenada depois de qualquer escrita anterior.
O mesmo lifecycle publica eventos explícitos de pausa e retomada. Uma nota de voz ativa é finalizada ao entrar em background ou quando a página fica oculta, liberando o microfone e mantendo o áudio já capturado como prévia não enviada. O compositor desanexa o recorder antes de stop(), portanto os sinais simultâneos do Capacitor e de visibilitychange não encerram a mesma stream duas vezes; PWA e desktop reutilizam a proteção do navegador.
O histórico interno persiste pcView e pcDepth em cada entrada. Reload restaura a tela atual; Back e Forward recuperam a profundidade daquela entrada em vez de depender de um contador que apenas diminuía em memória. Isso mantém gesto do PWA, histórico desktop e botão Voltar Android alinhados depois de avançar novamente. Ao autenticar uma identidade ou alterar o papel da mesma identidade, a tela mais recente passa outra vez por accessibleViewOrDashboard, impedindo que uma conta herde ou conserve uma rota sem permissão. O efeito lê a tela por uma referência atualizada durante o render, portanto a revalidação de RBAC não cria um ciclo com a própria navegação.
Essa hierarquia de retorno usa resolveNativeBack: primeiro ModalStackContext.closeTopModal(), depois o fallback de agendamento ainda não registrado, drawer móvel do shell, histórico de views e somente então saída do aplicativo. Cada camada real registra sua ação de fechamento, inclusive AdaptiveBottomSheet, lightbox de imagem, conversa móvel em tela cheia e drawer de navegação; uma pressão ou gesto fecha exatamente a superfície visual superior. O drawer permanente do desktop não entra no histórico, e os antigos estados sem UI de feed/notificações foram removidos. O lightbox mantém callbacks em referência estável para não recriar a entrada de histórico quando o componente pai renderiza novamente.
Essa garantia inclui o próprio NativeBridge: se push termina de inicializar depois da desmontagem, seu disposer é executado imediatamente. Lifecycle do App, teclado e rede contêm falhas de import, registro, leitura e remoção sem gerar unhandledrejection; listeners já resolvidos continuam sendo removidos mesmo em uma corrida de teardown. Os callbacks keyboardWillShow/keyboardWillHide também validam a flag de atividade, impedindo que um evento já enfileirado volte a alterar --keyboard-height ou safe areas depois da restauração feita no cleanup.
A inicialização do push é transacional: os quatro listeners (token, erro, recebimento e abertura) são acumulados conforme resolvem; qualquer falha posterior — inclusive checkPermissions() ou registro no APNs/FCM — invalida os callbacks e aguarda o rollback de todos os handles antes de propagar o erro. O disposer também invalida sincronamente token, erro, recebimento e abertura antes da remoção assíncrona, de modo que um callback nativo já enfileirado não atravessa teardown ou troca de sessão. Cada POST de token possui AbortController; teardown cancela os requests e impede persistência/evento posteriores. O token transitório fica separado do estado de readiness, mas é exposto ao cleanup de logout para excluir uma eventual gravação que já tenha alcançado o servidor antes do abort. O cleanup usa Promise.allSettled, tenta remover todos mesmo se um plugin falhar e contém cada rejeição. Imports concorrentes de Preferences/Push reutilizam a mesma promise, com retry após falha. A criação do installId também é serializada e faz uma segunda leitura antes de persistir, garantindo uma única identidade por instalação mesmo quando mais de um callback de token chega no mesmo boot. No PWA, pushsubscriptionchange compara a audiência persistida com /api/auth/me antes de recriar a inscrição; um evento atrasado nunca pode vincular o endpoint à conta que entrou depois.
O update flexível do Google Play segue o mesmo princípio: registra o listener de progresso, mas o remove se startFlexibleUpdate() falhar; estados cancelado/falhou e conclusão baixada usam cleanup idempotente. Uma trava local aceita apenas o primeiro DOWNLOADED, evitando duas chamadas concorrentes a completeFlexibleUpdate() antes da remoção assíncrona do listener. As consultas de disponibilidade no mount/resume também são serializadas: uma rajada compartilha a leitura ativa e mantém somente uma repetição final, sem publicar valor ou falha intermediária já superada. Isso reduz chamadas à bridge/loja e consumo de rede/bateria no Android e iOS. Falhas ao completar ou remover são contidas e registradas, sem unhandledrejection. iOS continua usando o encaminhamento oficial à App Store, sem carregar estados exclusivos do Play.
O retorno ao foreground e a recuperação da rede reconciliam dados centrais e canais de chat mesmo quando a WebView nativa não produz visibilitychange. PWA e navegador usam os eventos equivalentes de visibilidade e online; limiar de obsolescência e deduplicação impedem chamadas repetidas quando dois sinais chegam juntos.
O onboarding de campo revalida GPS/precisão, câmera e notificações pelo mesmo evento de retomada depois que o usuário volta das Configurações nativas. A leitura de precisão chama o provider Capacitor sob demanda no Android/iOS e só exige navigator.geolocation no navegador/PWA. Arquivos gerados ou anexos autenticados são gravados no cache nativo apenas durante a share sheet e removidos em finally, inclusive em cancelamento ou falha, evitando crescimento permanente do armazenamento.
cameraProvider também é o contrato único de permissão da câmera: Android/iOS usam @capacitor/camera; navegador, PWA e desktop consultam Permissions API quando disponível e solicitam getUserMedia somente após ação do usuário. O stream de verificação web é sempre encerrado imediatamente, e ausência da API ou incompatibilidade do Safari/Firefox retorna unknown sem fingir concessão ou bloqueio.
O teste de áudio do onboarding usa o mesmo AudioContext compartilhado pelos sons de chat/notificação. Ele aguarda resume() dentro do gesto, agenda um tom real e só persiste a confirmação quando o contexto está em execução; não cria nem fecha contextos paralelos. Falha ou ausência de Web Audio mantém a etapa pendente em vez de registrar um sucesso fictício, reduzindo diferenças de autoplay e limites de contexto no Safari/iOS, PWA, Android WebView e desktop.
O viewport compartilhado permite pinch-to-zoom, inclusive nas WebViews, preservando acessibilidade sem provocar zoom automático em campos (inputs usam 16 px). Além do login/Keychain, orçamento público, leads, perfil, clientes e equipe declaram inputMode e autocomplete para nome, organização, e-mail, telefone, endereço e URL conforme o contexto; iOS/Android abrem o teclado adequado e oferecem autofill sem contaminar configurações sensíveis. A matriz completa de 48 campos type="number" classifica dinheiro, percentuais, multiplicadores e horas fracionárias como decimal, e contagens, limites, minutos e dias como numeric; somente o offset UTC permanece sem inputMode por exigir sinal negativo. As 16 buscas e filtros textuais usam type="search", teclado de busca, ação Search no Enter móvel e autofill desligado; a busca de postcode mantém postal-code, capitalização e a mesma ação Enter porque também coleta um dado de endereço. Os 17 campos de data/hora continuam inputs temporais reais — portanto abrem o picker do navegador, Android ou iOS — e todos têm nome acessível direto, inclusive edição rápida, jornada semanal e confirmação final de orçamento. npm run pwa:doctor analisa cada campo e mantém esses contratos verificáveis. A capability de localização declara explicitamente uso somente em foreground. O iOS mantém NSLocationAlwaysAndWhenInUseUsageDescription porque o plugin oficial a exige internamente, mas a aplicação não solicita localização permanente nem declara background location mode.
A interface respeita prefers-reduced-motion globalmente: animações Tailwind, keyframes próprios, transições e smooth scrolling completam de forma praticamente instantânea quando a preferência do sistema está ativa, preservando estados finais e eventos de conclusão. Em dispositivos com ponteiro coarse e sem hover, controles interativos usam touch-action: manipulation; desktop mantém hover, seleção e comportamento de mouse normais. Controles focados por teclado recebem um indicador global com :focus-visible, inclusive quando um componente usa outline-none, sem mostrar o anel em foco por toque. Em forced-colors, a cor desse indicador acompanha a paleta de alto contraste do sistema. npm run pwa:doctor verifica esses quatro contratos.
Ações nunca dependem exclusivamente de hover. Controles de folha de pagamento, remoção de evidência, sugestão de review, faturamento de grupo, dividendos, entidades fiscais e tipos de serviço ficam visíveis por padrão no touch; apenas runtimes que anunciam (hover: hover) escondem e revelam esses controles com o mouse. Os alvos usam no mínimo 44 px, possuem nome contextual, ícone decorativo e estado expandido quando aplicável. Os três elementos que continuam com opacity-0 group-hover:opacity-100 são indicadores puramente decorativos e aria-hidden. O doctor deriva da AST todas as instâncias de Button e exige texto ou nome ARIA, além de rejeitar novas ações hover-only.
Tooltips são apenas aprimoramento de mouse, nunca o nome principal. Ações icon-only de edição, fatura, abas/diretório/filtros do chat, mensagem/telefone/e-mail, navegação, reações, falhas WhatsApp, perfil/sidebar, calendário, mapa, descontos, equipe, estoque e jornada possuem aria-label contextual independente e, nas superfícies touch, alvo de 44 px. Ações de mensagem ficam visíveis sem hover; as duas setas hover-only do DateScroller existem somente no layout desktop e têm o scroll horizontal nativo como alternativa touch. O gate AST audita os 52 controles que mantêm title e exige texto visível real ou nome ARIA separado, inclusive anchors.
Os filtros segmentados da Inbox (All / Leads / Jobs / Direct) e do Directory (All / Clients / Leads / Team) mantêm a altura compacta de 36 px com mouse e ganham piso de 44 px em ponteiro coarse. Cada opção publica aria-pressed a partir do mesmo estado que define a cor; assim seleção, toque e nome permanecem coerentes em desktop, PWA, TalkBack e VoiceOver.
Em layouts de telefone (max-width: 767px), input, select e textarea mantêm no mínimo visual de 16 px para impedir o zoom automático de foco do Safari/WKWebView. A regra não alcança o desktop, onde a escala tipográfica de cada componente volta a prevalecer. Os formulários de autenticação também declaram name e autocomplete semânticos (username, current-password, new-password, name, email e tel) para integrar gerenciadores de senha e preenchimento nativo nos três shells.
Overlays compartilhados usam src/components/ui/AccessibleBackdrop.tsx: um botão semântico, nomeado e operável por teclado substitui fundos baseados em div com clique. O padrão cobre busca global, menu móvel, folhas de conversa e instruções de instalação iOS, mantendo toque, teclado e leitores de tela consistentes entre PWA e WebViews nativas.
Modais e folhas reais convergem em AdaptiveBottomSheet: o painel recebe role="dialog", aria-modal, nome acessível e foco inicial; títulos visíveis são ligados por aria-labelledby e subtítulos por aria-describedby, enquanto cabeçalhos personalizados ou ocultos conservam um aria-label explícito. Todos os consumidores fornecem title, inclusive perfis, configurações do chat e detalhes do serviço, portanto nenhuma superfície é anunciada apenas como “Dialog”. Tab/Shift+Tab permanecem dentro da camada ativa e o foco retorna ao acionador ao fechar. ModalStackContext atribui uma identidade estável a cada camada, portanto somente o modal no topo responde a Escape. Operações atômicas podem usar closeDisabled para bloquear simultaneamente backdrop, botão fechar, Escape, Android Back e gesto Back do browser/PWA; quando a camada recusa o gesto web, o stack restaura sua entrada de histórico e não permite navegar a tela por baixo. O contrato cobre também a paleta de comandos, seletor móvel de conversas, sugestões de IA, painel operacional do WhatsApp, instruções de instalação iOS, fechamento de período, detalhes da disponibilidade da equipe, ForwardToTaskSheet e SettingsEntryModal; FiscalBalanceSheet é apenas uma tabela financeira apesar do nome.
Menus ancorados não entram na pilha de modais. O compositor do chat usa usePopoverMenu para anexos, respostas rápidas e agendamento: o acionador informa aria-haspopup, aria-expanded e aria-controls; a superfície e suas ações usam menu/menuitem; o primeiro item recebe foco ao abrir; setas percorrem os itens circularmente; Escape ou pressão externa fecham a superfície e devolvem foco ao acionador. Esse contrato mantém o comportamento consistente em teclado, toque, PWA e shells nativos sem bloquear a página como um diálogo.
Confirmações de ações usam a API assíncrona useConfirmation, fornecida por ConfirmationProvider dentro de ModalStackProvider. Ela substitui window.confirm por uma folha adaptativa com título, mensagem, ações nomeadas, foco contido, retorno de foco, Android Back e variante destrutiva com feedback háptico. Se uma segunda confirmação for solicitada enquanto outra está aberta, a anterior é resolvida como cancelada; desmontar o provider também cancela a promessa pendente.
Rascunhos das configurações vivem em settingsDraftStore, em memória e vinculados ao ID do usuário autenticado. Sair de Settings por navegação interna, gesto PWA ou Android Back não descarta campos: ao retornar, o editor recupera os valores e grupos sujos. Os seletores validam o proprietário sincronicamente, impedindo que o primeiro render após uma troca de conta exponha o rascunho anterior enquanto o efeito de limpeza ainda não executou. Valores novos do servidor atualizam apenas grupos limpos; um erro de persistência mantém o grupo sujo. UnsavedSettingsGuard, montado no shell, conserva o aviso de beforeunload mesmo quando a página está desmontada, mas registra o listener somente durante a existência de um rascunho sujo; ao salvar, descartar, trocar ou encerrar a sessão, o listener é removido. Nenhum dado de configuração é gravado em localStorage.
O bloqueio de rolagem passa por src/shared/bodyScrollLock.ts, com contagem por Document. Fechar uma camada superior não libera o body enquanto outra camada ou o lightbox continua aberto; a última liberação restaura exatamente o valor inline anterior e callbacks repetidos são inofensivos. Nenhum componente de aplicação grava body.style.overflow diretamente.
Fallbacks bloqueantes de modais lazy usam src/components/ui/ModalLoader.tsx em vez de overlays duplicados. O loader publica role="status", aria-live="polite" e aria-busy, oculta o spinner decorativo e aceita um rótulo contextual, cobrindo o registro de ações e a prévia de fatura.
O formulário global de nova reserva também é uma fronteira lazy: seu hook de formulário, regras de agenda e etapas visuais não entram no shell inicial. O módulo só é solicitado após isGlobalBookingOpen, com ModalLoader durante a transição; Android Back ainda consegue cancelar imediatamente pelo fallback explícito do shell. Fluxos críticos de senha obrigatória e bridge nativa permanecem eager.
A captura única de beforeinstallprompt permanece eager no SystemContext e no cache anterior ao mount, mas a interface opcional de instalação é uma fronteira lazy montada em período ocioso depois do boot autenticado. Apenas clientes e administradores solicitam esse chunk; funcionários e gerentes continuam exclusivamente no MobileRequirementGate. O fallback por timer cobre navegadores sem requestIdleCallback, e o cleanup cancela trabalho pendente em logout ou troca de perfil.
A paleta de comandos expõe o campo como combobox ligado a uma listbox: a opção visual corrente é refletida por aria-activedescendant/aria-selected, o estado vazio é anunciado e setas não alteram o índice quando a lista está vazia. Enter executa somente uma opção existente, enquanto Escape e contenção de foco vêm do diálogo compartilhado.
CFSelect gera um ID estável com useId e associa seu rótulo ao controle nativo, de modo que os mesmos formulários tenham nome acessível no navegador, TalkBack e VoiceOver. Cartões selecionáveis/expansíveis usam botões reais com aria-pressed ou aria-expanded; gráficos e logotipos cujo conteúdo já existe em texto são explicitamente decorativos para não produzir anúncios duplicados ou vazios.
CFInput aplica a mesma associação estável e conecta mensagens de erro com aria-invalid/aria-describedby; CFPillSelector expõe o grupo por fieldset/legend. No checklist de campo, conclusão e captura de evidência são botões independentes: o primeiro anuncia o estado com aria-pressed, enquanto o segundo abre a câmera nativa ou o seletor web sem marcar a tarefa acidentalmente.
A auditoria noLabelWithoutControl está zerada na interface compartilhada. label é reservado para controles de formulário associados por htmlFor; títulos de filtros, coleções, intervalos e grupos usam texto ou legend. Campos compostos de data/hora recebem nomes individuais, evitando que VoiceOver e TalkBack anunciem rótulos ambíguos.
Primitivos como UserAvatar e CFKpiCard renderizam botão somente quando recebem uma ação; versões informativas permanecem fora da ordem de foco. Cartões de serviço, holerites e séries recorrentes usam botões com nome/estado acessível. Os seletores de data e hora deixam o input nativo transparente cobrir toda a ação, preservando os pickers do navegador, Android e iOS sem uma segunda camada de clique.
A matriz de disponibilidade reutiliza AccessibleBackdrop e expõe o painel como diálogo modal. A lista arrastável de equipe funciona também como seleção múltipla por teclado (listbox/option), preservando drag-and-drop no desktop. Já a coluna de trabalhos não alocados é uma lista comum de botões nativos — não simula um listbox sem navegação por setas — e conserva drag-and-drop como aprimoramento de mouse. Cartões com ações secundárias, como agenda e logs de erro, separam o botão principal dos botões de mensagem, cópia ou configuração.
Linhas acionáveis de dashboard, histórico, auditoria, pagamentos e faturas mantêm a área inteira disponível para toque e mouse, mas também entram na ordem de foco e abrem com Enter ou Espaço. O contrato compartilhado src/shared/keyboardActivation.ts ignora eventos originados em controles internos, evitando que um botão filho também abra a linha, e cada superfície fornece nome acessível e indicador de foco visível.
Filas extensas do Dashboard são progressivas nas quatro experiências: cards montam inicialmente 24 grupos completos e a lista 50 linhas, preservam o total num status acessível e expandem por um botão compartilhado com alvo touch e háptico nativo. Faturas, contas e recorrências não são partidas entre páginas. O agrupador e a tabela preparam mapas lineares para relacionamentos, removendo buscas e filtros quadráticos sem mudar a prioridade da primeira fatura ativa nem a fonte de verdade dos dados.
As filas do Dashboard são classificadas por DashboardIntelligenceService.classifyRequests em uma passagem sobre as visitas, mantendo a ordem original e as sobreposições deliberadas entre execução, cobrança e revisão. Outra passagem única pelas faturas constrói o conjunto de visitas já faturadas, a fila de aprovação e as pendências limitadas ao cliente autenticado. O cálculo de liquidado compartilha o mesmo predicado de não faturado da visita e não procura mais cada cancelamento dentro de outra lista; testes de equivalência preservam inclusive a divisão exaustiva de PENDING entre alocação e confirmação.
A página do Dashboard recebe queries, stores e operações exclusivamente de useDashboardController, evitando observers React Query e assinaturas Zustand/contexto duplicados no mesmo caminho de render. O preparo de dados cria os índices de clientes e serviços uma vez, compartilha-os entre desnormalização e resoluções seguras dos cards e mantém RBAC e ordem cronológica em um contrato puro testado.
Dashboards de cliente e funcionário classificam seus pedidos em passagens lineares preservando ordem, primeira visita ativa, próxima visita cronológica e separação financeira/finalização. Os cálculos temporais usam o useNowMinute compartilhado, que possui um único intervalo e pausa quando a aplicação vai ao background; ao retomar PWA ou shell Android/iOS, próximos atendimentos e janelas de sete dias convergem sem depender de um render incidental.
O mapa de rastreamento constrói índices lineares de clientes e visitas em andamento por funcionário, preservando a precedência da primeira atribuição ativa. Presença online é recalculada pelo relógio foreground, coordenadas numéricas válidas incluem zero e o primeiro lote de marcadores enquadra o mapa automaticamente sem reposicionar atualizações seguintes. Nomes de funcionário e cliente são escapados na fronteira dos fragments HTML exigidos pelo Leaflet, impedindo que dados operacionais sejam interpretados como markup executável.
A disponibilidade semanal constrói numa passagem os índices de tarefas por funcionário/dia, horas individuais e totais diários, preservando a ordem das tarefas, atribuições múltiplas e a exclusão de cancelamentos. Datas derivadas permanecem estáveis entre renders e o destaque do dia acompanha o relógio foreground compartilhado. No mobile/PWA/WebView, a coluna da equipe fica fixa no scroll horizontal e cada célula publica funcionário, data, estado, contagem e horas para VoiceOver/TalkBack; desktop mantém a mesma matriz densa.
Os relatórios de carga e desempenho agregam horas, avaliações, receita, pontualidade, compliance e frequência funcionário-cliente por atribuição, em passagens lineares. A retenção continua exigindo ao menos três atribuições ao cliente e uma visita concluída, sem refiltrar o histórico inteiro para cada par. A tabela de capacidade mantém o profissional visível durante o scroll horizontal móvel, adapta espaçamento ao viewport e apresenta vazio confirmado quando não há equipe ativa; desktop preserva as colunas analíticas completas.
Growth/Marketing e margem preparam índices de clientes, serviços, entidades fiscais e funcionários e agregam as visitas concluídas em passagem única. O candidato a review mantém contagem de avaliações e serviço mais recente sem ordenar um array por cliente; margem conserva VAT absorvido, custos, horas, equipe, taxa negociada, drivers e ordenação por gap sem buscas cruzadas repetidas. O resumo visual separa filtros, abaixo da meta e em dia no mesmo percurso, e uma busca vazia não é apresentada como carteira saudável.
Os radares de retenção agrupam pedidos por cliente em passagem única. Reengajamento ordena cada histórico concluído somente uma vez para determinar frequência, inatividade e severidade; o score de churn separado foi removido com o Quality Control (as colunas ai_urgency_score/ai_sentiment ficam sem uso), e o hook consolida mapa, clientes críticos e score global no mesmo percurso. O relógio foreground compartilhado atualiza sinais temporais após retomada no navegador, PWA e shells Android/iOS. A superfície diferencia falta de histórico, retenção saudável e filtro sem correspondência; os filtros são um grupo com estado pressionado, scroll touch e linguagem consistente com o restante do produto.
O Portfolio de fidelidade filtra a carteira antes de agrupar pedidos e percorre cada histórico uma vez para preservar fidelidade de pagamento, cancelamentos pagos e não pagos, LTV e taxa horária efetiva. Lifecycle e momentum são pré-computados com o relógio foreground no controller; cartões recebem a métrica completa e deixam de assinar a coleção global ou repetir cálculos. Assim busca, passagem do tempo e mutações produzem uma única atualização compartilhada em web, PWA, Android, iOS e desktop.
Prova social e ranking de equipe seguem a mesma estratégia linear. Uma passagem acumula avaliações, promotores, receita, tarefas, conclusões, atrasos e visitas por cliente para cada profissional conhecido; atribuições duplicadas no mesmo pedido são normalizadas. O resultado mantém cancelamentos fora do ranking, preserva avaliações e receita de tarefas não canceladas, exige três conclusões para conta retida e ordena por retenção e avaliação como antes.
Capacidade e governança não materializam mais listas intermediárias nem filtram/ordenam todo o histórico para cada cliente. O relatório cria uma vez o intervalo do mês, soma horas elegíveis e, em outra passagem compartilhada, acumula leakage, avaliações e última visita por cliente. Ambos recebem o relógio foreground: virada mensal, cobrança aguardando há 15 dias e inatividade de 30 dias avançam após retomada em web, PWA, Android, iOS e desktop sem reload.
O Business Intelligence calcula em um agregador puro o histórico móvel de seis meses, a distribuição de serviços e a eficiência da equipe. Um mapa substitui a busca linear de tipo de serviço e uma única passagem pelos pedidos concluídos atualiza meses, serviços e profissionais, normalizando atribuições repetidas. O controller removeu a consulta de clientes sem consumidor e usa o relógio foreground, mantendo janela, margem média, top 8, receita e avaliações sincronizados nas cinco superfícies.
A divisão por entidade fiscal é calculada por um agregador puro indexado. Clientes e entidades são resolvidos por mapa; pedidos elegíveis e faturas percorrem suas coleções uma vez, acumulando receita de serviço, VAT, custo e sobretaxas antes de formar cada entidade e o consolidado no mesmo percurso. Permanecem idênticas as regras de VAT absorvido, reembolso parcial, cancelamento com taxa, métodos oficiais no modo HMRC, cobranças SENT/PAID e exclusão de entidades desconhecidas em web, PWA, Android, iOS e desktop.
O dashboard contextual do chat projeta nome, e-mail e telefone do snapshot atual e reinicializa o editor tanto ao trocar tipo:id quanto ao receber valores novos para a mesma entidade. Cada save captura owner e epoch, impedindo conclusão, timer ou háptico tardio no contato seguinte. O histórico de adiantamentos é ordenado sobre uma cópia; apenas abrir o perfil não muta o funcionário mantido pela store nem altera outras telas sem persistência.
O gerenciador de endereços do cliente também preserva imutabilidade estrutural: remover a localização padrão filtra uma nova lista e clona o primeiro endereço remanescente ao promovê-lo. O objeto recebido por props/store não é alterado antes da confirmação do modal; cancelar a edição não deixa isDefault modificado em outras telas. Tentativas inválidas ou de remoção da última localização mantêm a referência original e não disparam onChange.
A área financeira do colaborador deriva um snapshot único por mudança de dados. Holerites visíveis são ordenados uma vez, IDs já pagos formam um conjunto, pedidos são indexados e tarefas por período ficam prontas para todos os cartões; DRAFT não é exposto, APPROVED não quita trabalho e custo manual zero continua sendo uma decisão explícita. “Cash I Have” resolve cliente e entidade por mapas antes de aplicar o tratamento de VAT, removendo buscas repetidas por tarefa nas cinco superfícies.
Transições de pagamento de faturas incluem requests nas dependências dos callbacks e, portanto, nunca calculam uma confirmação sobre um snapshot antigo quando somente a agenda mudou. A aplicação de visitas atualizadas usa mergeListById: um índice linear preserva a ordem da lista, mantém referências não afetadas, não muta entradas e conserva a semântica anterior de primeira atualização em IDs duplicados. A mesma primitiva substitui o cruzamento quadrático ao propagar alterações financeiras para uma série recorrente.
O resumo financeiro central foi extraído para um agregador puro que primeiro aplica o escopo de EMPLOYEE/CLIENT e reutiliza as fachadas autoritativas de P&L e auditoria fiscal. A ordenação descendente ocorre sobre uma cópia, impedindo que a tela Finance altere in-place o array do cache TanStack consumido por agenda, dashboard e operações. Uma passagem acumula salários realizados/projetados, horas e receita por serviço, resolvida por índice de catálogo; RBAC, custos manuais, cancelamentos e percentuais permanecem iguais nas cinco superfícies.
O Supply Hub compõe o aviso de reposição por uma função pura: cria uma cópia, ordena HIGH/MEDIUM/LOW e nunca reorganiza client.shoppingList no cache compartilhado. Auditoria de risco por IA e notificação no chat usam single-flight keyed por identidade + cliente; dois toques no mesmo frame compartilham uma única chamada e clientes distintos permanecem independentes. Auditorias têm teto de 30 segundos, cancelamento e validação do payload; falha não publica um insight vazio. Loading usa conjuntos de IDs, refletindo corretamente operações paralelas. Troca de conta aborta análises, limpa todos os insights e invalida commits/toasts da identidade anterior. O clipboard provider contém rejeições com feedback recuperável em web, PWA, Android, iOS e desktop.
A baseline compartilhada zera toda a categoria Biome a11y em src, e as regras recomendadas de acessibilidade agora fazem parte do npm run lint normal. Uploads e pickers usam controles nativos; lightbox e evidências têm botões nomeados; o diretório de contatos separa perfil, telefone, e-mail e chat; zonas/listas arrastáveis mantêm alternativas semânticas de seleção. Exceções pontuais são justificadas junto ao elemento: regiões nativas de drop mantêm alternativa operacional, e a prévia local de voz não possui transcrição antes do envio. A antiga prop de domínio role do UserAvatar, que não afetava a renderização, foi removida para não colidir conceitualmente com ARIA.
A revisão contextual de useButtonType está limpa: as ocorrências foram resolvidas separando ações dos envios reais. Ações usam type="button", enquanto submits preservam type="submit", evitando submissões acidentais sem quebrar o envio pela tecla Enter. npm run pwa:doctor percorre a AST de todos os TSX e falha se qualquer botão HTML novo omitir o tipo.
Tabelas operacionais, financeiras, de histórico, relatórios e importação declaram scope="col" em todos os cabeçalhos de coluna. Cada tabela de dados também possui um caption somente assistivo, específico para o seu conteúdo — inclusive faturas aninhadas e prévias CSV — para que VoiceOver, TalkBack e leitores desktop identifiquem a tabela antes de percorrer suas células. Colunas visualmente vazias de ações, opções e expansão recebem um nome ARIA contextual, sem ocupar espaço ou alterar densidade. O mesmo gate AST do pwa:doctor exige nome próprio para tabela e cabeçalho e aceita somente escopo explícito col ou row, protegendo componentes criados futuramente.
Cabeçalhos ordenáveis mantêm a estrutura no <th>, publicam aria-sort (none, ascending ou descending) e delegam a ação a um botão HTML que preenche a célula. Clique, toque, Enter e Espaço percorrem o mesmo handler, enquanto setas visuais ficam ocultas da árvore assistiva. O pwa:doctor rejeita handlers de clique aplicados diretamente ao cabeçalho e exige botão descendente sempre que existir aria-sort.
Saídas externas preservam o comportamento de cada plataforma por externalBrowserProvider: HTTP(S) abre o navegador seguro do Capacitor no Android/iOS e uma aba isolada no PWA/desktop; tel:, mailto: e webcal: são entregues ao aplicativo do sistema. Todo link _blank declara simultaneamente noopener noreferrer, inclusive mapas, calendário, WhatsApp e anexos. O gate AST exige proteção contra window.opener e handler nativo em novas janelas, além de interceptação para protocolos do sistema.
src/shared/platform/privacyScreenProvider.ts no Android fica sempre desligado: FLAG_SECURE bloqueava screenshots e interferia no diálogo de permissão de notificações (Subscribe → “Permission Needed”). No iOS aplica blur só em background para a miniatura do app switcher. As escritas na bridge são serializadas e estados intermediários ainda enfileirados são descartados, portanto uma sequência rápida background/foreground termina sempre no último estado observado mesmo se o plugin demorar. Captura pela câmera e upload de evidências permanecem normais. O provider é inativo no navegador/PWA.
O manifesto Android desativa Auto Backup. data_extraction_rules.xml também exclui todos os domínios de cloud backup e transferência aparelho-a-aparelho, cobrindo fabricantes que não tratam allowBackup=false de forma uniforme. Cookies WebView, tokens FCM e IDs da instalação não são restaurados em outro aparelho; dados de negócio são recarregados do backend após nova autenticação.
A baseline de dependências de agosto de 2026 elimina os 21 advisories anteriormente reportados pelo npm, incluindo os riscos de runtime em Hono, jsPDF/DOMPurify e Resend. npm run security:audit reproduz o gate manual. Vite, Wrangler, Workers Types e Sharp foram atualizados em conjunto; um override limitado a xcode → uuid >=11.1.1 corrige a cadeia do Capacitor CLI sem rebaixar o ecossistema Capacitor 8.5.
npm run android:doctor oferece o gate equivalente ao iOS para package/SDK, Firebase, App Links, push, permissões, backup, privacy screen, origem HTTPS, ícones e assinatura. O doctor deriva os plugins Android das dependências instaladas e exige correspondência exata dos 21 módulos em capacitor.settings.gradle e app/capacitor.build.gradle; também confere bundle, origem, scheme HTTPS e cleartext no capacitor.config.json copiado. Assim, configuração ou grafo nativo fora de sincronia bloqueiam antes do Gradle. JDK 21 e as quatro variáveis externas da upload key são informados separadamente; --strict os torna obrigatórios apenas no release CI.
No painel de manutenção, limpeza de logs, liberação de fotos em memória e reset compartilham uma trava síncrona antes da confirmação. Uma ação desabilita as demais, aguarda a operação real sem atrasos cosméticos e só encerra seu loading enquanto ainda pertence ao mesmo lifecycle; sair de Settings invalida conclusões tardias. O reset também possui estado ocupado visível e não pode ser disparado duas vezes enquanto a confirmação ou limpeza está ativa.
npm run pwa:doctor fecha o mesmo contrato para a plataforma web: valida manifestos principal/chat, ícones any/maskable, atalhos contra o ViewState compartilhado, registro e lifecycle do service worker, isolamento do boot offline, cache e rotas Cloudflare, associações Android/iOS, viewport acessível, fonte local e Web Push. O atalho Live Map usa LIVE_TRACKER; a matriz RBAC continua sendo aplicada quando ele é aberto. VAPID_PRIVATE_KEY permanece um secret externo e só é obrigatório com --strict.
npm run platforms:doctor executa em sequência os diagnósticos de PWA, Android e iOS e separa configuração verificável do repositório de credenciais externas de loja/assinatura. O contrato de registro do service worker aceita formatação TypeScript equivalente (inclusive encadeamento em múltiplas linhas), e um teste executa o doctor real para impedir falsos negativos que interrompam os diagnósticos nativos seguintes. O gate geral npm run check também executa npm audit --audit-level=moderate; releases não devem avançar com advisories moderados ou altos na árvore instalada. Em agosto de 2026, o lockfile foi renovado para Hono 4.13.1, DOMPurify 3.4.13, Mermaid 11.16.1, Wrangler 4.120.0, Undici 7.29.0 e Nanoid 3.3.18, eliminando os advisories então conhecidos sem mudança de API da aplicação.
A fonte da aplicação é Plus Jakarta Sans Variable, importada de @fontsource-variable/plus-jakarta-sans/wght.css e emitida pelo Vite como assets versionados. O documento principal e a instalação do service worker não dependem de Google Fonts: uma falha, bloqueio ou ausência de rede externa não impede mais o cache offline, e PWA/Android/iOS/desktop usam exatamente os mesmos arquivos e métricas tipográficas. O fallback de emoji continua explícito por sistema operacional.
Controles compactos que precisam preservar densidade no desktop usam a classe compartilhada .touch-target. Em dispositivos pointer: coarse, ela garante uma área mínima de 44×44 px para ações rápidas e botões de fechar; mouse e teclado mantêm as dimensões compactas originais. A auditoria cobre busca, gravação/reprodução de voz, agendamento, resposta, encaminhamento e reação no chat, filtros da Inbox/Directory, seleção de equipe/frequência da cotação, navegação semanal, folha, faturamento, reconciliação, estoque, configurações, sincronização de calendário, simulador/saúde do WhatsApp, CTAs dos banners globais, logout do drawer móvel, formulários de serviços, recuperação de erro, séries abandonadas e recolhimento da sidebar. O teste AST reconhece h-*, w-*, min-h-*, min-w-* e variantes importantes !, percorre todos os botões TSX compactos e só permite duas exceções nomeadas: setas hover-only com rolagem touch equivalente e checkboxes de uma tabela que não é renderizada no layout móvel. A geometria crítica também é conferida na produção em viewport de 390×844, porque tamanho composto pode escapar da leitura isolada das classes. Isso aproxima PWA, Android e iOS das convenções nativas sem dilatar a interface desktop e impede regressões futuras.
Estado selecionado também é um contrato compartilhado, não apenas uma variação de cor. Serviço/frequência do orçamento, equipe, data, horário, endereço, período, forma de pagamento, tema, IA, WhatsApp, filtros e reconciliação usam aria-pressed; o dashboard do chat usa tablist/tab + aria-selected, e links manuais, simulador, grupos, mapas e aprovações expansíveis publicam aria-expanded. TalkBack, VoiceOver, teclado e automação recebem o mesmo estado apresentado visualmente, protegido por teste de contrato dedicado.
As tablists compartilhadas seguem o padrão completo: somente a aba ativa participa do Tab, setas circulam a seleção, Home/End navegam às extremidades e o foco acompanha a mudança. CFTabs e o dashboard do chat ligam cada tab ao seu tabpanel por aria-controls/aria-labelledby; Android, iOS, PWA e desktop recebem o mesmo comportamento sem forks de interface.
Listas compostas também evitam foco fragmentado. A Command Palette conserva foco no combobox e aponta a opção ativa por aria-activedescendant; resultados ficam fora do Tab, o índice reinicia ao pesquisar e a seta mantém o item visível. O filtro multisseleção de equipe conserva apenas uma option no Tab e aceita setas, Home/End e Enter/Espaço. TalkBack, VoiceOver, teclado físico e tecnologias de switch percorrem as mesmas listas sem visitar cada cartão desnecessariamente.
Menus ancorados compartilham usePopoverMenu: Arrow Down/Up no gatilho abre e posiciona o foco, abertura comum prefere o item radio selecionado, setas circulam, Home/End alcançam as extremidades, Escape fecha e devolve o foco, e Tab fecha permitindo que o navegador siga ao próximo controle. Digitação incremental encontra rótulos sem diferenciar maiúsculas ou acentos; repetir uma inicial circula pelos resultados e o buffer curto não captura Espaço nem atalhos modificados. Settings, seletor desktop de conversas e ferramentas do composer usam esse único lifecycle; fora do desktop, conversas continuam no bottom sheet nativo ao toque.
Botões icon-only que conservam title como tooltip para mouse também publicam aria-label: exportação de gráfico, análise de incidente, última visita de série, atualização de calendário, abertura da tarefa, falhas do WhatsApp e detalhes do chat. O toggle de detalhes ainda expõe aria-expanded. Outras 21 ações compactas sem tooltip — semanas, mapa, seleção em massa, pin/close, sidebar, voltar, adicionar e enviar — também têm nome; toggles publicam aria-pressed/aria-expanded. Assim o mesmo controle tem descoberta visual no desktop e nome/estado confiáveis em VoiceOver e TalkBack; o PWA doctor protege as duas matrizes.
Inputs brutos com placeholder não dependem desse texto transitório como único nome. As 22 buscas e entradas rápidas auditadas (tarefas, inventário, motivo, destinatário, tarifa, respostas, materiais, keywords, simulador, cobertura e cobrança) publicam aria-label contextual; campos que adicionam/enviam pelo Enter usam enterKeyHint="done" ou send, e distritos postais solicitam capitalização de caracteres. O placeholder continua apenas como exemplo visual.
As superfícies fixas anteriores à navegação principal — login/cadastro, redefinição de senha, boot e falha de conexão — compartilham system-viewport-safe. O contrato reserva recortes superiores e gestos inferiores em PWA, Android e iOS, usa 100dvh/border-box para acompanhar o teclado e deixa o chrome nativo ser pintado fora da área de conteúdo. Agenda, menus de conversa/configuração e modais de manual/QuickBooks também limitam altura com dvh; barras móveis, teclado e split-screen não escondem suas ações sob um vh estático. O orçamento público também abre WhatsApp pelo provider externo: Capacitor entrega a URL ao navegador nativo e a web mantém um link explícito caso o popup pós-request seja bloqueado.
Conectividade é observada no MainLayout, durante toda a sessão autenticada, em vez de ser desmontada ao sair do Dashboard. Todas as rotas recebem o aviso compacto e os toasts de offline/online pelos eventos web ou pelo provider Capacitor. O texto não promete persistência inexistente: informa que atualizações ao vivo estão pausadas e que mensagens de chat serão enviadas ao reconectar; demais mutações continuam dependendo de rede.
O contrato honesto cobre também superfícies temporárias: o toast repete a capacidade limitada, o prompt de instalação fala em dados recentes durante interrupções breves, e softRefreshBoot retorna sem iniciar fetch quando o provider declara offline. A retomada da rede dispara os listeners globais que atualizam boot/chat e drenam a fila implementada.
Entregas de arquivos gerados ou anexos autenticados usam a share sheet no Android/iOS, Web Share quando disponível e download no navegador como fallback. Cada operação nativa grava em um subdiretório exclusivo do cache mantendo o nome original como folha; duas exportações simultâneas chamadas report.pdf não sobrescrevem nem removem o arquivo uma da outra. Arquivo e diretório temporários são limpos após compartilhamento, cancelamento ou falha.
Cópias para o clipboard usam o plugin nativo sob demanda em Android/iOS e o Clipboard API com fallback de seleção em PWA/desktop. A bridge nativa serializa escritas pela ordem dos toques, impedindo que uma resposta antiga substitua o valor mais recente; uma falha é devolvida somente ao chamador correspondente e a fila continua utilizável. O navegador não recebe essa espera para preservar a ativação transitória necessária à permissão de cópia.
Permissões bloqueadas podem abrir diretamente detalhes do aplicativo, notificações ou serviços de localização conforme a plataforma. openNativeAppSettings adquire um single-flight síncrono compartilhado por todos os gates e modais antes de carregar o plugin; toque duplo não empilha duas telas do sistema. Ao retornar ao foreground, as permissões são relidas, e qualquer resolução ou falha libera o provider para nova tentativa.
A barra de status nativa usa a cor primária efetivamente pintada e calcula sua luminância relativa. O estilo dos ícones Android/iOS muda no ponto matemático em que glyphs claros e escuros têm contraste equivalente, em vez de um limite visual arbitrário; Blue/Indigo/Rose/Slate mantêm glyphs claros e Amber/Emerald usam glyphs escuros. No PWA, o chrome superior permanece no azul institucional e color-scheme: light; a safe area superior expõe esse fundo e uma cor personalizada clara recai para azul, impedindo ícones claros invisíveis em uma barra branca.
O feedback tátil global reconhece controles compartilhados e controles HTML brutos. Seu tick leve é adiado até o fim do dispatch; quando a própria ação emite feedback explícito no mesmo clique, ela cancela o genérico antes de acessar a bridge. Assim o Button e handlers especializados não geram vibração dupla em Android/iOS ou PWA, enquanto controles sem integração continuam recebendo um único tick. Desktop sem Vibration API não registra o listener.
Os sete editores multilinha compartilhados também têm nome persistente: incidente, avaliação, confirmação por WhatsApp, corpo de e-mail, banner global, chat e mensagem de ausência. O compositor do chat publica enterKeyHint="enter": no touch/teclado virtual Return continua inserindo nova linha, enquanto o atalho Enter para envio permanece restrito ao desktop e protege composição IME. Ele mantém textarea especializada para capitalização, spellcheck e crescimento nativos, anuncia upload/câmera com aria-busy, desabilita o envio durante essas operações e usa lock síncrono antes do dispatch; dois toques no mesmo frame não geram mensagens com chaves de idempotência diferentes.
Os nove select brutos preservam o controle nativo e expõem nome contextual: semana do orçamento, incidente, overrides de status/pagamento, migração de endereço, impersonação, banner público, dividendos e destinatário do simulador WhatsApp. CFSelect continua cuidando automaticamente de id/label nos demais formulários; o doctor audita apenas a fronteira manual.
Os 11 inputs brutos restantes que não recebem nome de um <label> envolvente publicam identificação direta: preço, pagamento por profissional, assunto, slider de alocação, status da conta, desconto, VAT e toggles Stripe/GoCardless. O slider anuncia também o valor com sua unidade; checkboxes realmente envolvidos por labels e inputs de upload display:none continuam usando a semântica nativa existente.
O botão compartilhado Button trata loading como estado semântico além do spinner: ficam disabled, publicam aria-busy="true", mantêm o texto original em um status somente assistivo e ocultam os ícones decorativos. Assim os aproximadamente 30 fluxos consumidores evitam toque duplo e não perdem o nome da ação durante processamento em navegador, PWA, TalkBack ou VoiceOver.
O carregamento de superfícies segue o contrato equivalente: PageLoader e ModalLoader publicam um status ocupado e educado, mantendo animações decorativas fora da árvore assistiva. PageLoader agora opera em tela cheia padronizada (system-viewport-safe fixed inset-0 z-[9999]), alinhado à geometria e à barra de progresso das telas de boot (Connecting Engine) e atualização de versão, eliminando o antigo artefato de caixa flutuante/incompleta. Mapas e feeds operacionais lazy usam a mesma semântica local; a Edição Rápida agora mostra o fallback modal bloqueante em vez de deixar o toque sem resposta visual enquanto o chunk chega.
Status compactos de boot, atualização, PageLoader e carregamento do histórico usam slate-600 estável sobre branco. A antiga animação de opacidade fazia o texto de 10 px cair a 1,68:1 em parte do ciclo; agora somente indicadores decorativos de progresso se movem. Metadados do dashboard, cabeçalhos de página, categorias/perfil da barra lateral e rótulos inativos da navegação inferior seguem o mesmo contraste. Contadores visíveis participam do nome acessível dos itens de navegação, e cartões operacionais derivam o nome do próprio conteúdo visível; isso evita divergência entre a interface e VoiceOver/TalkBack. Badges LOCAL/DEV também usam pares AA, mantendo auditorias confiáveis sem alterar produção. O contrato vale em desktop, PWA, Android e iOS.
O mesmo piso de contraste cobre os estados expandidos de login, recuperação e cadastro, além dos metadados sobre fundos claros dos portais públicos de pagamento, extrato, proposta de agenda e avaliação. Superfícies desabilitadas ou históricas não reduzem a opacidade do contêiner quando ele contém texto: a hierarquia visual é expressa por cor de fundo, borda e peso, preservando AA em Safari, Chrome e WebViews.
Pagamento, extrato, proposta de agenda e avaliação públicos preservam uma única região <main> tanto no carregamento e em links inválidos quanto no conteúdo resolvido. Os papéis status e alert ficam no texto anunciado, sem substituir a semântica da região principal. Isso mantém o landmark descoberto por VoiceOver, TalkBack e leitores de tela desktop sem alterar o layout compartilhado; o diagnóstico PWA rejeita regressões para uma raiz genérica ou com papel conflitante nesses quatro fluxos.
O componente compartilhado Button adota type="button" por padrão. Envios reais declaram type="submit" no ponto de uso; assim, ações secundárias nunca passam a submeter um formulário acidentalmente quando a composição da tela muda, e o comportamento permanece idêntico no navegador e nas WebViews nativas.
Grupos de escolha mantêm contexto além do destaque visual. As frequências permitidas de um serviço usam fieldset/legend, fazendo VoiceOver, TalkBack e leitores desktop anunciarem a pergunta junto de cada checkbox. Os modos de resposta do WhatsApp formam um grupo nomeado e cada cartão-botão publica aria-pressed, preservando a seleção para teclado e tecnologia assistiva sem trocar o layout touch.
ProgressBar centraliza indicadores quantitativos. Progresso temporal ou de conclusão publica progressbar com mínimo, máximo, valor e texto contextual; métricas escalares usam um <meter> nativo assistivo, mantendo a barra visual customizada separada e decorativa. Valores inválidos ou acima do limite são normalizados. Voz no chat, checklist, margem, capacidade, fidelidade, receita por colaborador e cartões da agenda compartilham esse contrato. Carga semanal empilhada publica um resumo único de horas executadas/agendadas, enquanto aging e distribuição ocultam barras redundantes porque suas legendas já expõem cada valor; assim leitores não recebem silêncio nem repetição.
A navegação lateral tem dois contratos no mesmo componente: complementary permanente no desktop e drawer modal no mobile. Quando o drawer está fechado abaixo de 1024 px, inert e aria-hidden retiram todos os links fora da tela da ordem de foco e da árvore assistiva. O botão Menu publica aria-controls/aria-expanded; ao abrir, o foco entra no primeiro item de navegação e, ao fechar, retorna ao gatilho inferior.
Os manifestos PWA principal e de chat não fixam orientation: telefone, tablet, dobrável e janela desktop seguem a rotação ou redimensionamento escolhidos pelo usuário. O Android igualmente não declara android:screenOrientation; o configChanges existente mantém a WebView durante a rotação. No iOS, Info.plist habilita retrato e as duas orientações de paisagem no iPhone, além de retrato invertido no iPad. Os três doctors protegem esse alinhamento.
A classificação de instalação usa somente sinais fornecidos pelo runtime: display-mode, navigator.standalone, referrer TWA ou Capacitor. Os start_url dos manifestos são canônicos e parâmetros como source=pwa/mode=system não alteram permissões nem escondem o onboarding em uma aba comum. O evento único beforeinstallprompt é preservado antes do mount React, compartilhado por um provider tipado e apagado tanto ao ser consumido quanto em appinstalled; a tela de requisitos passa imediatamente a orientar o usuário a abrir o ícone instalado. As instruções manuais do Safari reutilizam DeviceService.isIOS(), incluindo iPadOS quando ele anuncia a identidade desktop MacIntel, sem confundi-lo com um Mac sem toque.
Na instalação inicial do service worker, precacheAppShell busca index.html sem usar o cache HTTP, guarda a resposta sob /index.html e /, extrai apenas scripts, modulepreloads e CSS declarados no documento e inclui os assets referenciados por url() nesse CSS (fontes locais). Assim uma PWA recém-instalada pode reabrir offline mesmo antes de uma segunda navegação controlada. Chunks lazy das 117 rotas/assets continuam fora do precache e entram sob demanda, evitando transformar a instalação em download integral da aplicação. O boot autenticado usa network-first e um único snapshot canônico, independentemente do parâmetro t usado para evitar cache HTTP. Respostas 401/403, logout, troca de conta e impersonação removem o snapshot; a limpeza percorre também gerações e chaves legadas, impedindo que dados operacionais de uma sessão reapareçam em outra. A limpeza também incrementa uma geração no worker: uma requisição antiga que conclua depois da fronteira de identidade não consegue regravar o cache, e nem pode fazer fallback para aquele snapshot.
O namespace do cache não é incrementado manualmente. Durante vite build, o plugin prime-crown-service-worker-build-id calcula SHA-256 sobre o index.html emitido e o template do worker, grava os primeiros 12 caracteres em dist/service-worker.js e mantém o token apenas em public/. Assim qualquer mudança no grafo publicado ou no próprio worker altera seus bytes, dispara o lifecycle de atualização e remove caches anteriores na ativação. Isso impede PWA e shells Capacitor de permanecerem presos a um bundle antigo depois de releases web-only.
O gate de orçamento lê o artefato final e falha se o token ainda existir ou se o namespace não terminar em exatamente 12 caracteres hexadecimais. Portanto o diagnóstico verifica a configuração-fonte e npm run check verifica o resultado realmente publicável.
O hook de atualização combina o evento imediato sw-update-available com uma leitura autoritativa de registration.waiting ao montar, cobrindo WebViews restauradas e workers que instalaram antes do React. Retorno ao primeiro plano e primecrown:app-resume solicitam registration.update() com deduplicação de um minuto; reconexão confirmada pelo provider compartilhado ignora esse intervalo, pois a checagem anterior pode ter falhado offline. A aplicação silenciosa é limitada ao Dashboard ocioso, sem modais, reserva global ou Chat isolado; telas e fluxos potencialmente editáveis recebem o banner e só recarregam após confirmação. O handler compartilhado de controllerchange ignora apenas o primeiro claim de uma instalação nova; toda substituição posterior recarrega exatamente uma vez, mesmo que primeira instalação e upgrade ocorram na mesma página longa. Se outra aba promover o worker entre o banner e o toque, a ação converge por reload network-first. Se uma WebView restringir a leitura do registro ou rejeitar SKIP_WAITING, a mesma ação faz reload imediato em vez de manter o overlay e o lock aguardando um controllerchange impossível.
Falhas de lazy chunk (vite:preloadError) também convergem pelo mesmo canal: a primeira em uma janela de 60 segundos é suprimida, força registration.update(), promove eventual worker em espera e recarrega por navegação network-first. O timestamp fica em sessionStorage; uma repetição dentro da janela não é suprimida nem recarregada automaticamente e chega ao ErrorBoundary, evitando loops infinitos quando o problema é indisponibilidade real e não apenas um bundle antigo. Se o storage estiver bloqueado, o comportamento seguro é não autorrecarregar. Esse handler é a única autoridade de reload para imports dinâmicos; as rotas usam React.lazy diretamente, sem um segundo timestamp que possa contornar o cooldown compartilhado.
Se uma exceção ocorrer antes de React montar, renderEarlyBootFailure cria o fallback apenas com createElement, textContent e listeners programáticos; mensagens nunca passam por innerHTML nem atributos inline executáveis. A tela usa safe areas, alvo de toque de 48 px, foco inicial no retry e role=alert/aria-live, mantendo recuperação utilizável em desktop, PWA e WebViews mesmo se o CSS principal falhar.
Depois do mount, ErrorBoundary registra o erro sanitizado na telemetria administrativa e apresenta ErrorFallback. A causa visível e o relatório copiado passam por telemetrySanitizer: URLs preservam apenas origem/pathname, sem query ou fragmento, e tokens, JWTs, senhas, cookies, authorization, chaves de API, credenciais e códigos de pareamento/verificação são redigidos. O contexto é percorrido recursivamente com proteção contra ciclos/profundidade e mensagens/stacks têm limite de 8.000 caracteres; contexto do chamador não pode sobrescrever URL, mensagem ou user-agent canônicos. Stack JavaScript e árvore de componentes continuam disponíveis na interface somente em desenvolvimento. O fallback anuncia role=alert, move o foco para o título, respeita safe areas e tema escuro, empilha ações em telas estreitas e mantém alvos de toque de pelo menos 48 px.
SystemErrorsLog mantém hasLoaded e loadError separados da lista. Somente resposta HTTP válida pode produzir o vazio verificado; falha conserva snapshot e alerta, enquanto filtro sem correspondência usa copy distinta. requestRef serializa refresh no mesmo frame, a leitura encerra em 12 segundos, o AbortController encerra I/O no teardown e o commit exige que o controller ainda seja o proprietário. O botão compartilhado anuncia loading e a lista existente não desaparece durante refresh.
Antes de qualquer inicialização própria do app, index.tsx instala clientConsolePrivacy nas builds de produção compartilhadas por browser, PWA e WebViews Android/iOS. Dezessete métodos que aceitam dados — incluindo log/error/warn/debug, group, table, dir, trace e timers — mantêm o primeiro rótulo já redigido e valores operacionais numéricos/booleanos; objetos, exceções, respostas de provedor e strings auxiliares viram [details omitted], enquanto e-mail, telefone, UUID e query/hash do próprio rótulo viram [redacted]. Desenvolvimento preserva o console original. Assim, as chamadas atuais continuam úteis localmente sem copiar payload de cliente para DevTools, Logcat ou diagnóstico do WebKit em produção; o doctor exige que a fronteira seja instalada antes do reporter global e de window.onerror.
O boundary de logout agora cobre o dispositivo inteiro. A identidade local é removida imediatamente, e QueryClient.clear() cancela e apaga as consultas autenticadas de forma síncrona, antes de qualquer espera de rede. A fronteira não aguarda um cancelamento separado: assim uma limpeza iniciada pela conta anterior não pode apagar o boot recém-semeado pela conta seguinte. Enquanto o cookie ainda é válido, disconnectPushForLogout remove o endpoint Web Push ou token FCM/APNs da conta e encerra a inscrição local, com limite de três segundos por operação; o próprio request de logout também tem limite. O alvo capturado vai a /api/auth/logout; o Worker valida formato e JWT, repete o delete com reference_id em ambas as cláusulas e só então limpa cookies, tornando unlink + revogação uma operação server-side idempotente sem afetar outros aparelhos. Para token nativo, a rota de registro também mantém uma cópia HttpOnly, SameSite=Strict, limitada a /api/auth: se a leitura Capacitor de Preferences vencer o limite de 300 ms, o logout usa essa cópia somente para excluir o dispositivo da sessão que está saindo. O primeiro POST nativo carrega também o reference_id da identidade React que o iniciou; ao mudar de conta, o cliente aborta o request anterior e o Worker recusa qualquer request cujo cookie já tenha passado a outro usuário. Em seguida clearPrivateClientStorage apaga todas as partições IndexedDB da fila offline e do histórico de notificações, chaves legadas, dica Google e snapshot de boot; o shell também encerra a sessão local do provider Google. Um failsafe conclui a navegação mesmo se uma ponte nativa/storage não responder. Restauração com sessão inválida, revogação remota, logout e impersonação aplicam a limpeza; preferências visuais opacas permanecem. O service worker recebe a audiência atual em cada troca de identidade e remove seu marcador junto aos banners no logout; push sem destinatário, da conta anterior ou recebido antes do novo restore não chega a desenhar conteúdo na bandeja. Links originados por push do service worker ou bridge nativo exigem também recipientUserId explícito e igual ao usuário vivo; no cold-start da PWA, o Worker acrescenta a prova ao URL interno somente após consultar /api/auth/me, e a inicialização React apaga todas as seleções se a conta restaurada divergir. Ausência, outra conta ou chegada antes do restore falham fechadas e não ficam pendentes para a próxima sessão. App Links operacionais normais continuam a usar a matriz RBAC. A sessão é revalidada em app-resume, recuperação de rede e retorno a uma aba browser/PWA visível, agrupando sinais simultâneos em uma leitura; a validação é ignorada sem usuário autenticado, evitando que o 401 esperado ao voltar do seletor Google interrompa a troca nativa do token. O doctor verifica ordem, transports, retenção e os quatro pontos de troca de identidade.
Em cold-start, o recipientUserId presente na URL que o service worker ou o PendingIntent Android criou é preservado somente como guarda de rejeição. Se outra conta terminar de restaurar, a rota e suas seleções são descartadas antes de navegar; uma URL não concede acesso, que continua dependente do payload de push, RBAC e backend. Isso fecha a troca de conta entre o toque na bandeja e a montagem React sem transformar App Links operacionais em um novo mecanismo de autorização.
No iOS, Apple e Google usam o mesmo lock de login social nativo. A interface desabilita o provider alternativo enquanto um sheet está aberto e o hook repete essa exclusão no limite da Activity, impedindo callbacks concorrentes de cruzarem loading ou troca de sessão mesmo sob toques rápidos. Browser e PWA aplicam a mesma exclusão no callback Google: um ID token em andamento toma um lock síncrono antes do estado React, portanto replay do provider ou One Tap paralelo não abre uma segunda troca de sessão.
A fila offline de chat só anuncia queued depois de gravar no IndexedDB. Quando armazenamento privado ou restrito recusa a escrita, a bolha otimista continua visível como failed, com retry explícito, em vez de ficar presa em sending ou prometer uma entrega que não sobrevive ao restart. O mesmo vale quando uma falha de rede exige persistência para retry e essa persistência não está disponível.
Entrega de arquivos remotos propaga cancelamento do consumidor até o adaptador nativo. Fechar lightbox, trocar anexo ou desmontar durante a conversão/base64 ou a escrita em Directory.Cache limpa o arquivo e impede a abertura tardia do share sheet; uma folha que já foi aberta continua sendo decisão do sistema. Browser/PWA, Android e iOS conservam o mesmo contrato de cancelamento silencioso e sem sucesso falso.
Na transição Chatwoot, um 404/410 ao enviar invalida somente o vínculo que aponta para a conversa exata que falhou. Se outro request já tiver resolvido a mesma linha WhatsApp para uma conversa nova enquanto a resposta antiga chegava, esse vínculo novo permanece; a próxima tentativa usa-o em vez de criar uma terceira conversa. O mesmo compare-and-delete protege texto e mídia.
Uma revogação remota de sessão também invalida o GET /api/auth/me iniciado no boot, além da revalidação de foreground. Assim, mesmo se uma WebView concluir a leitura inicial após o abort, ela não pode republicar a conta revogada no intervalo anterior ao redirect para login.
Resultados derivados de cancelamento/remarcação pelo cliente pertencem à sessão que iniciou a mutação. Após logout, impersonação ou novo login, a resposta antiga ainda pode ser devolvida ao chamador para encerrar seu fluxo, mas não pode espelhar visitas, bônus ou invalidar o cache da conta nova.
O registro FCM/APNs trata installId como posse do aparelho, não da conta. Ao registrar um token identificado, tokens diferentes da mesma instalação são removidos mesmo se pertencerem a uma conta anterior; isso recupera logout offline somado a rotação de token sem deixar o telefone recebendo notificações privadas da identidade que saiu.
A restauração de autenticação conserva cancelamento e timeout durante toda a cadeia /me → refresh → /me, e o teardown invalida seu commit. Revalidações de resume abortam a leitura anterior, capturam o ID corrente e só aceitam 401/403 se request e identidade ainda forem atuais. Uma revogação válida retira imediatamente o usuário e as telas protegidas, antes de aguardar push, storage e reload; respostas antigas não conseguem deslogar uma conta posterior.
O inventário de elementos estáticos clicáveis chegou a sete superfícies: seis linhas de tabela (agenda do dashboard, item de fatura, pagamento, auditoria, serviço histórico e fatura histórica) e o seletor lateral da equipe. As linhas mantêm toque integral, mas expõem role=button, nome contextual, foco visível e activateOnEnterOrSpace; pagamento só é interativo quando possui fatura e informa aria-expanded. A opção de equipe usa role=option, aria-selected e nome adicionar/remover. O doctor constrói a lista pela AST TSX e exige onKeyDown, tabIndex, role e nome em todo div/span/li/tr/td/section/article que receber onClick.
/api/atomic/system-logs repete a sanitização no servidor para cobrir bundles antigos e requests adulterados. O schema limita IDs, ação, entidades e payload bruto; detalhes persistidos ficam em até 8.000 caracteres ou em um envelope JSON válido marcado como truncado. Autor e timestamp vêm da sessão/Worker, nunca do corpo. Funcionários podem reportar erros, clientes continuam proibidos e cada conta possui orçamento de 20 inserções por 5 minutos; a tentativa é inserida antes da contagem e removida pelo próprio ID se exceder, evitando corrida de requests simultâneos, com 429 + Retry-After. Consultas de admin/manager normalizam limit para 1–500 (default 200), rejeitam entityId excessivo e não devolvem mensagens internas do D1 em falhas 500.
Erros originados nos próprios Workers passam pelo mesmo contrato. logErrorToSystemLogs serializa Error com nome, mensagem, stack e causa, tolera objetos circulares e sanitiza antes do insert; até a falha interna do logger chega ao console sem o objeto bruto. Nos fluxos mais expostos, chat-initiate nunca devolve error.message do D1/Evolution, e send-invoice não envia mais o objeto do Resend ou a exceção bruta. O painel mantém o diagnóstico sanitizado, enquanto todas as plataformas recebem mensagens 500 estáveis com possibilidade de retry.
O mesmo isolamento cobre toda a API autenticada de canais por functions/api/channels/channelError.ts. As 15 saídas inesperadas de listagem/criação, mensagens, participantes, reações, leitura, digitação, agendamento, tradução, encaminhamento e movimentação registram ação e tipo de entidade em system_logs, mas retornam apenas Unable to complete this chat request. Please try again.. Respostas funcionais 400/401/403/404/423 continuam específicas e não são confundidas com falha interna.
Os CRUDs atômicos centrais usam atomicServerError para o mesmo isolamento. Clientes, funcionários, serviços, leads, entidades fiscais, adicionais, regras de cancelamento, descontos por frequência, área de atendimento, lançamentos/fechamentos de folha e faturas somam 22 caminhos protegidos: exceções do D1 são sanitizadas e classificadas por ação/domínio no painel, enquanto web, PWA, Android, iOS e desktop recebem somente Unable to save or load this data. Please try again.. Validação, autorização, conflito e recurso ausente continuam com seus códigos e mensagens funcionais.
No systemStore, salvar/excluir regra de cancelamento mantém a resposta visual otimista, mas o request vive fora do updater e toda resposta passa por assertMutationOk. Recusa funcional ou de rede restaura condicionalmente somente a regra daquela tentativa; uma edição ou recriação mais recente não é sobrescrita. Toast e estado permanecem coerentes sem exigir reload nas quatro plataformas.
Autenticação usa functions/api/auth/authError.ts em 15 handlers de login, cadastro, sessão, impersonação, recuperação/troca de senha, vínculo/entrada Google e WebAuthn. Exceções inesperadas são sanitizadas como AUTH_ACCOUNT; fluxos JSON recebem mensagem estável ou orientação específica da ação, e callbacks redirect mantêm apenas o código público server_error. Credenciais inválidas, conta existente, token expirado e demais respostas funcionais não são convertidos em 500. O sanitizer textual cobre nomes compostos como client_secret e refresh_token, além de chaves privadas, de assinatura e de acesso.
Login por senha ou biometria, cadastro, recuperação, troca obrigatória e redefinição de senha usam trava síncrona de envio, desabilitam edição/navegação enquanto a operação está em curso e descartam respostas tardias após troca de tela, identidade ou desmontagem. O token de redefinição é capturado em memória e removido imediatamente da URL por history.replaceState, reduzindo exposição em histórico, captura de tela e compartilhamento. O feedback tátil nativo ocorre no início e somente confirma sucesso após a resposta válida do servidor; cancelamento biométrico não é tratado como falha.
No Android, o fluxo flexível de atualização da Play Store mantém a ação bloqueada até o sistema informar cancelamento ou até completeFlexibleUpdate() realmente terminar. Falha de download/instalação e falha de conclusão rejeitam a operação para que o banner preserve a versão atual e ofereça nova tentativa, em vez de apresentar sucesso antecipado. O listener nativo é removido em todos os encerramentos.
Instalação PWA usa o mesmo lifecycle no convite opcional e no gate obrigatório de campo: o evento beforeinstallprompt, que é de uso único, recebe lock antes da primeira espera, tem prompt()/userChoice aguardados e é descartado após aceite ou recusa. Falha do navegador ativa instruções manuais, sem Promise rejeitada fora do controle; respostas tardias após troca de usuário/tela são ignoradas e o loading impede fechar ou repetir a ação.
As etapas obrigatórias de GPS, câmera, notificações e som usam flights separados para coalescer toques concorrentes sem serializar recursos distintos. Cada solicitação captura um epoch do usuário; retorno de permissão, posição, token push ou áudio após logout, impersonação ou troca de funcionário é descartado. Mudança de identidade invalida leituras pendentes, reinicia os três estados do sistema como checking e executa nova reconciliação autoritativa.
Fotos de evidência bloqueiam a superfície desde a abertura da câmera até a resposta do R2. O owner do epoch combina usuário e destino operacional; mudança de serviço/conta invalida câmera e upload, e tornar a superfície somente leitura aborta a requisição em curso. Antes de adicionar a URL, o componente revalida disabled e o limite atual, impedindo foto tardia ou excedente. Falhas de câmera/upload são anunciadas inline e por háptico; cancelamento da câmera não é apresentado como erro.
Checklist e chat revalidam autorização também depois que câmera/seletor retorna. Ao perder permissão de edição, o checklist invalida captura, aborta uploads por item e não aceita foto restaurada. O compositor do chat mantém lock síncrono durante a câmera, bloqueia menu/campo/microfone, rejeita arquivo se canal travou ou outro upload começou e limpa tudo na troca de conversa/usuário. Erro nativo é visível por toast; cancelamento continua silencioso.
Os endpoints do orçamento em functions/api/public/ usam publicServerError nas saídas inesperadas. Catálogos de serviços/adicionais, criação de lead e cálculo não devolvem mensagens do D1 nem informam detalhes de configuração fiscal; o diagnóstico sanitizado é classificado como PUBLIC_QUOTE. As antigas conversões públicas por senha/Google foram removidas: cadastro passa pelo gate telefônico e conversão comercial passa pela confirmação autenticada de lead_quotes. Erros funcionais 400/409 permanecem específicos, e somente respostas bem-sucedidas dos catálogos mantêm cache público.
Preferências e entrega de notificações compartilham o mesmo isolamento. notification-prefs, push-subscriptions, atomic/notifications e system-banner possuem dez saídas atômicas seguras; a décima primeira registra separadamente falha de configuração VAPID sem interpolar a exceção criptográfica na resposta 503. Leitura de dispositivos também fica dentro do boundary. 401/403/409, ausência de VAPID, lista vazia, rejeição do provedor e instrução de re-inscrição mantêm contratos funcionais para PWA, desktop, Android e iOS.
Requests, configurações, onboarding, séries recorrentes e o fallback manual de snapshot somam outras oito saídas protegidas. Falhas totais usam atomicServerError; falhas parciais de settings/snapshot registram o diagnóstico por entidade e devolvem somente label, id e a mensagem estável. O onboarding também não repassa a resposta do Resend. Assim, os quatro runtimes recebem o mesmo contrato de retry sem stack, SQL, segredo ou detalhe do provedor, enquanto validações e recusas funcionais preservam seus status específicos.
Tipo de arquivo servido: o envio grava o tipo permitido pela extensão (contentTypeForUpload), não o declarado pelo navegador. A leitura manda nosniff e entrega como download tudo o que não é imagem, PDF, áudio ou vídeo. Antes, um “PDF” declarado como HTML rodava como página do app com a sessão de quem abrisse o anexo.
Upload, leitura e exclusão de mídia moderna validam {clientId}/direct|team/{job?} contra os mesmos predicados de escopo usados pelo boot. Cliente só acessa a própria pasta; funcionário precisa ter visibilidade do cliente e atribuição à tarefa; jobCode deve pertencer ao clientId até para administradores. Chaves legadas permanecem legíveis para compatibilidade, mas criação e exclusão ficam restritas a admin/manager. As três operações de R2, as duas rotas do chat de convidado, o cron e a migração legada somam sete boundaries sanitizados. Falhas parciais da migração conservam o request ID e descartam o diagnóstico bruto. O endpoint sem consumidor /api/test-db foi removido da produção.
O inventário final de respostas brutas inclui também boot, status/reconexão WhatsApp, envio Meta e webhooks Meta/Evolution, com seis saídas adicionais em atomicServerError. A falha funcional do endpoint de QR conserva apenas o status HTTP e registra o corpo do gateway de forma sanitizada. O doctor agora percorre todos os .ts de functions/ e falha se qualquer Worker voltar a responder com .message ou String(error); atomicUtils e safeErrorLog são as únicas exceções deliberadas porque serializam a exceção para sanitização antes do log, nunca para o cliente.
Telemetria assíncrona converge em functions/api/common/safeErrorLog.ts. logSanitizedError e sanitizedErrorDetails serializam Error/objeto/contexto circular, removem segredos e limitam o payload antes de console, fila ou alerta. Trinta e oito módulos usam 141 saídas protegidas para D1, canais, Evolution/Meta, Web Push, scheduler, onboarding e Google Calendar. A fila WhatsApp não persiste mais error.message; last_error e o push administrativo recebem a mesma versão redigida. O doctor varre todo o backend e rejeita console.error com objetos/strings brutos conhecidos.
Logs informativos preservam mensagens fixas e somente interpolam contagem, booleano, delay e status HTTP. Não interpolam mais e-mail, telefone, Google sub/account, IDs de cliente/usuário/canal/mensagem/subscription, categoria/modo configurável, status textual externo nem objetos de resposta do Resend/Evolution. O doctor inventaria toda interpolação restante e protege essa allowlist estruturalmente, impedindo que uma futura mensagem de debug reintroduza identidade ou conteúdo controlado por provedor em sucesso ou warning.
Os ícones legacy e adaptativos do Android reutilizam a coroa e o azul #2563EB do PWA. A splash screen usa o mesmo foreground vetorial dentro da safe zone do Android, evitando recortes nos diferentes formatos definidos pelos launchers.
Cada transporte de push tem saúde/configuração independente: sucesso VAPID não mascara ausência ou falha da credencial Firebase em uma conta que também possui Android.
Notificações mantêm três transportes: Web Push/VAPID para navegador e PWA, Firebase Cloud Messaging para Android e APNs direto para iOS. Consulta, solicitação e observação da permissão passam pelo contrato compartilhado notificationPermissionProvider, reutilizado pelo onboarding móvel e pelas preferências do perfil; a Permissions API e seu cleanup ficam isolados no provider, enquanto os shells nativos revalidam no resume. Refreshes sobrepostos do provider global, Perfil, evento de token e retomada compartilham uma operação keyed pelo modo da sessão, sem cruzar impersonação. O diagnóstico Android do Perfil usa singleFlight por usuário e epoch em todos os commits, portanto respostas do plugin após logout/troca de conta são descartadas. Depois da concessão, cada runtime registra seu transporte próprio. src/shared/platform/nativePushProvider.ts cria dois canais Android de alta importância (prime_crown_messages para chat e prime_crown_notifications para o resto), registra tokens e encaminha recebimento/toque para os mesmos toasts e deep links do PWA. Somente Android com app_build ≥ NATIVE_NOTIFICATION_MIN_BUILD recebe FCM data-only; PrimeCrownMessagingService desenha chat com MessagingStyle (avatar circular de iniciais, stack com timestamps, Reply + Mark as read, shortcut de Conversations) e só silencia o tray quando aquela conversa está aberta (primecrown_active_channel_id via @capacitor/preferences). A seleção continua imediata em memória e as escritas nativas são serializadas com coalescência do estado ainda enfileirado, impedindo que um set lento vença a saída/troca de conversa e silencie notificações futuras. iOS recebe alerta APNs visível, com som, badge e agrupamento por thread-id; functions/lib/apns.ts autentica com a chave Apple .p8 e o AppDelegate encaminha o device token ao plugin. A PWA espelha o que a Web Notifications API permite: avatar SVG, stack, Reply que permanece e Mark as read. Tokens nativos são persistidos em native_push_tokens pela rota autenticada /api/native-push-tokens; nunca são misturados às chaves criptográficas de push_subscriptions. Credenciais FCM/APNs permanecem no Bitwarden e nos secrets do Cloudflare.
O estado de autorização e a lista de dispositivos registrados são reconciliados ao retornar das Configurações do sistema, mantendo o Profile alinhado com alterações feitas fora do aplicativo. Recargas sobrepostas da lista compartilham a leitura atual e guardam somente uma repetição final; assim mudanças sucessivas de endpoint/saúde não geram uma cascata de abort/restart, mas um token registrado durante a primeira leitura ainda aparece no passe final. Check native usa lock síncrono e ticket da sessão, revalidado após cada await; toques repetidos não abrem diagnósticos paralelos e logout/troca de conta não recebe resultado ou toast tardio. O lifecycle também aborta o transporte e invalida commits da lista.
A gestão de dispositivos representa tokens nativos pelo identificador opaco native:<plataforma>:<token> e ainda aceita o antigo prefixo fcm: durante a transição, distinguindo Android/FCM de iOS/APNs na mesma interface.
Token push e ID estável da instalação ficam em @capacitor/preferences, separados do localStorage reservado à experiência web. A leitura realiza migração única dos valores gravados por shells anteriores e apaga a cópia legada sem interromper o registro FCM/APNs.
A fila de mensagens offline usa IndexedDB no PWA e nas WebViews. Builds novos migram uma eventual chat_offline_queue_v1 do localStorage somente se cada registro já declarar o mesmo ownerUserId; registros sem proprietário verificável são removidos, em vez de serem atribuídos à primeira conta posterior. Cada escrita e a migração carregam o epoch corrente do armazenamento; logout incrementa-o antes de limpar, logo uma transação iniciada pela conta anterior não pode repovoar o IndexedDB ao terminar. Cada registro é identificado pelo externalId e só é excluído depois do ack do servidor, evitando perda quando a conectividade cai novamente durante o reenvio.
Cada registro da fila também guarda ownerUserId. O flush lê somente itens pertencentes ao usuário autenticado atual, impedindo que uma troca de conta em aparelho compartilhado reenvie conteúdo criado pela sessão anterior.
Alertas operacionais criados localmente usam outro cache IndexedDB particionado por usuário. A hidratação preserva eventos que chegam enquanto o boot ainda lê o cache e migra/remove notif_history_v1_<userId>; preferências de som, posição e categorias continuam no localStorage por serem estado exclusivamente visual. Essas preferências agora usam notif_prefs_v2_<marker> com opaqueStorageMarker(userId, 'notification-preferences'), portanto a chave não revela o ID da conta. Na primeira leitura, o valor de notif_prefs_v1_<userId> é copiado e a chave legível removida, inclusive quando o conteúdo legado está inválido. O marcador serve somente para particionar UI local e não protege segredos.
Preferências visuais que precisam distinguir uma entidade não gravam seu identificador operacional em texto claro. src/shared/storageMarker.ts produz marcadores estáveis e separados por namespace, sem pretensão criptográfica e nunca usados para segredos. Dicas de passkey reutilizam o mesmo algoritmo compatível; canais fixados usam chat_pinned_channels_v3_<account-marker> e marcadores de canal, isolando cada conta no mesmo navegador. As listas legadas v1 e a antiga lista global v2 são descartadas — não são atribuídas à próxima sessão, pois não trazem proprietário verificável. O dismiss do banner WhatsApp converte e apaga a antiga chave que continha client.id. A indisponibilidade do storage degrada apenas a persistência da preferência, nunca o dashboard ou o chat.
O orçamento público não cria uma sessão de chat que a tela não usa. StepQuoteResult envia issueGuestToken: false, portanto /api/leads/chat-initiate cria/atualiza lead, canal e lead_quote aberta, sem gerar ou devolver JWT; nenhuma credencial ou channelId é persistida no sessionStorage. Cliente e atendimento não existem até a confirmação administrativa. Quote e Contact Us no widget gravam a mensagem no app e, no telemóvel, abrem sempre o WhatsApp do visitante (widgetQuoteHandoffPhone / mensagem); widgetQuoteHandoffEnabled / widgetContactHandoffEnabled só ligam a confirmação Evolution com o texto de widgetQuoteAutoReplyMessage / widgetContactAutoReplyMessage. O endpoint mantém issueGuestToken: true como padrão compatível para widgets externos que realmente abrem /api/leads/chat-messages, limitando a mudança ao consumidor que comprovadamente precisa da sessão.
Telefone não é identidade. O widget identifica o visitante pelo número digitado, e o canal de um cliente existente é a conversa privada dele.
- O token de chat de convidado só é emitido quando pedido.
/api/leads/chat-messagesmostra apenas as mensagens desta visita, sem notas internas.- O formulário não renomeia cliente com nome confirmado nem retira o consentimento de WhatsApp.
Outras correções nesta área:
- A confirmação de orçamento reserva a cotação antes de gravar, então duas confirmações simultâneas criam um cliente só.
- A proposta de horário usa a hora de Londres e recusa link antigo e visita em andamento.
- O extrato público não mostra rascunhos.
Os links de extrato, avaliação e proposta de horário são gerados pela gerência em /api/client-links e enviados na conversa do cliente, pelo WhatsApp. Os botões ficam no cadastro do cliente e nos detalhes da visita, e a resposta do cliente à proposta vira nota interna na conversa. O link de avaliação no Google vem de uma constante só, GOOGLE_REVIEW_URL (src/shared/googleReview.ts), que é o perfil real da Prime Crown no Maps.
O endpoint público de captura (chat-initiate) não expõe mais CORS curinga. Uma política compartilhada reflete somente origens Prime Crown, previews HTTPS controlados do Cloudflare Pages, desenvolvimento local e origins padrão do Capacitor; chamadas servidor-a-servidor sem Origin continuam compatíveis. Preflights e POSTs vindos de sites não autorizados recebem 403 antes de qualquer leitura ou mutação no D1, e todas as decisões variáveis publicam Vary: Origin.
Clientes HTTP diretos também são protegidos por um rate limiter persistente em D1, aplicado antes de analisar o payload ou executar efeitos externos. chat-initiate admite 5 tentativas por 15 minutos por cliente do edge. O limite é isolado por endpoint, responde 429 com Retry-After e elimina registros expirados somente da janela correspondente. public_api_attempts guarda o IP recebido do Cloudflare apenas como marcador SHA-256 de 64 caracteres, nunca em claro; isso reduz exposição acidental sem tratar o marcador como anonimização criptográfica forte.
O gate de requisitos móveis consulta e solicita a permissão pelo mesmo provider do runtime: FCM no Android, APNs no iOS e Notification/Web Push no PWA. notificationDeliveryProvider mantém autorização do sistema separada da prontidão para entrega. Assim, conceder a permissão no gate também dispara o registro nativo, mas a etapa só termina depois que a assinatura Web Push foi persistida com sucesso ou o token nativo persistido confirma um destino utilizável pelo backend. O listener é instalado antes da leitura do token já salvo, eliminando a corrida entre os dois caminhos; falha ou timeout produz registration_failed, explica que a autorização já está ativa e oferece nova tentativa sem fingir uma recusa do usuário. GPS, câmera e notificações mantêm coordenadores latest wins: resposta antiga, precisão atrasada ou segunda espera pelo token só faz commit se ainda for atual; solicitações explícitas publicam o resultado final e a saída do gate invalida pendências sem impedir uso futuro. O Perfil aplica o mesmo contrato ao snapshot conjunto de health/permissão/assinatura: refresh, heal e resume usam tickets, enquanto subscribe/unsubscribe invalidam checks pendentes antes da mutação e publicam o resultado final. Assim uma leitura iniciada antes de desativar não consegue restaurar visualmente ou logicamente o dispositivo. O perfil nativo comunica o mesmo timeout e sempre encerra seu loading. Na restauração, a checagem somente leitura exige inscrição ainda desejada e ativa ou token persistido, e o evento de registro atualiza o gate sem reinício. Textos de teste, falha e recuperação são selecionados pelo runtime e não atribuem respostas do APNs ao Firebase.
A lista e os diagnósticos de dispositivos no Perfil também pertencem ao user.id. GETs de dispositivos e ACK aceitam AbortSignal; uma nova leitura substitui a anterior, e teardown/troca de identidade interrompem polling. Remoção, teste SW e teste push usam locks síncronos por ação, revalidam o epoch depois de cada await e liberam somente o próprio lock, portanto toque duplicado, loading, lista e toast nunca atravessam para outra sessão ou tela. O teste nativo envia imediatamente e não consulta livePushEndpoint: aguardar timer em background ou uma leitura desnecessária do token pela ponte Capacitor podia impedir o POST e manter o botão em loading, embora a entrega real funcionasse. A comparação de endpoint permanece exclusiva do PWA. O POST possui limite de 15 segundos e cada salto externo FCM, APNs ou Web Push possui limite de 10 segundos, garantindo conclusão visível mesmo se um provedor ou endpoint antigo não responder.
O boundary de descoberta do Vitest preserva os excludes padrão e remove **/.claude/worktrees/**. Checkouts auxiliares criados por agentes desktop podem conter uma cópia completa de src, tests e node_modules, mas nunca duplicam a suíte do checkout ativo nem esgotam o pool de forks.
Quando GPS, câmera ou notificações são negados, o gate diferencia o runtime nas instruções de recuperação: Android e iOS instalados orientam pelos caminhos próprios das permissões do aplicativo Prime Crown e usam nativeSettingsProvider para abrir diretamente a tela correspondente nas configurações do sistema, enquanto o PWA mantém o caminho de permissões do site no navegador. O modal de recuperação do rastreamento operacional oferece essa ação direta nos dois shells nativos; a detecção de iOS/Android web reutiliza DeviceService em vez de manter expressões de user-agent locais.
Antes de gerar um bundle Android, npm run android:sync deve ser a última sincronização web. Tanto o aplicativo quanto a documentação escrevem em dist/; sincronizar o Capacitor imediatamente após npm run docs:build empacotaria a documentação em vez da SPA.
Bundles de produção são gerados por npm run android:bundle:release. O Gradle exige PRIME_CROWN_UPLOAD_STORE_FILE, PRIME_CROWN_UPLOAD_STORE_PASSWORD, PRIME_CROWN_UPLOAD_KEY_ALIAS e PRIME_CROWN_UPLOAD_KEY_PASSWORD, todos externos ao Git. PRIME_CROWN_VERSION_CODE e PRIME_CROWN_VERSION_NAME controlam a versão da Play Store; o código deve crescer a cada upload.
O fluxo npm run android:bundle:release:bw reconstrói temporariamente o PKCS12 a partir dos quatro itens prime-crown:ANDROID_UPLOAD_* no Bitwarden, delega ao mesmo pipeline e elimina o arquivo e a sessão ao sair. O JDK 21 do Homebrew é detectado automaticamente; outros ambientes podem usar PRIME_CROWN_JAVA_HOME.
As páginas públicas /home, /privacy, /terms e /account-deletion formam a base legal usada pela Google Play. Usuários autenticados encontram “Request account deletion” no rodapé do Profile, apontando para o mesmo fluxo público; a solicitação é verificada e processada manualmente, preservando apenas registros sujeitos a obrigações legais, fiscais, antifraude, de disputa ou auditoria.
Os recursos editoriais da ficha Google Play ficam em public/store-assets/. O feature graphic oficial usa 1024×500 px e deriva da mesma identidade azul e coroa branca dos ícones PWA/Android. As capturas reais e revisadas ficam em public/store-assets/screenshots/: telefone em 1080×1920, tablet de 7 polegadas em 1280×720 e tablet de 10 polegadas em 1920×1080. Não publique capturas que exponham nomes, endereços ou outros dados operacionais de clientes e funcionários.
A captura de imagens passa por src/shared/platform/cameraProvider.ts: Android usa @capacitor/camera, enquanto navegador/PWA preservam inputs web com capture="environment". Evidências antes/depois, checklist e chat convergem para o mesmo contrato File e continuam usando os uploads R2 existentes. Antes de abrir a Activity externa, o provider persiste em Preferences um marcador opaco e determinístico do destino, vinculado ao usuário e sem clientId, itemId ou channelId legível; trocar de conta produz outro marcador e impede entrega cruzada. Logout/troca também apaga o marcador e arquivos recuperados em memória, além de invalidar o resultado que esteja em leitura. Se o Android encerrar a WebView por pressão de memória, NativeBridge recebe appRestoredResult, reconstrói o File, mantém o resultado pendente até a tela restaurada assinar o contexto e o entrega somente à evidência, item ou conversa de origem; o contexto é removido após sucesso, cancelamento ou recuperação. A captura nativa usa câmera traseira, orientação corrigida, largura máxima de 1920 px, qualidade 85 e saveToGallery: false; somente a permissão Android CAMERA é declarada.
Notas de voz usam Ogg/Opus mono 16 kHz (PTT do WhatsApp) via src/shared/voiceRecorder.ts. O encode corre num Worker — não no AudioWorklet da thread de áudio — para evitar silêncios digitais (picote). O Android declara RECORD_AUDIO (+ MODIFY_AUDIO_SETTINGS) para a captura iniciada pelo botão do microfone no WebView; não há gravação em background. O hardware de microfone é opcional; o PWA mantém a solicitação web sob gesto do usuário. A velocidade 1x/1.5x/2x é compartilhada entre players e prévia pelo voicePlaybackRate; sua persistência passa por uiPreferenceStorage, portanto novos players na mesma sessão preservam a escolha mesmo quando o runtime bloqueia localStorage.
Localização passa por src/shared/platform/locationProvider.ts. Android usa obrigatoriamente @capacitor/geolocation com permissões precisa/aproximada, fallback para o LocationManager e intervalos de rastreamento controlados; PWA continua usando navigator.geolocation. requestCurrentLocation centraliza solicitação de acesso e primeira posição, e observeLocationPermission isola a Permissions API e seu cleanup. watchLocation recebe AbortSignal: o cancelamento bloqueia posição/erro sincronamente, e um ID que resolva depois da desmontagem é limpo uma única vez assim que chega; o fallback web usa o mesmo contrato. useRealTimeTracker aborta antes de aguardar o disposer e ignora também uma consulta inicial de permissão que termine após a troca de papel. No useGeoPermission, câmera e localização instalam observadores em paralelo; createLatestAsyncCommit invalida leituras anteriores quando chega uma consulta/evento mais novo e bloqueia todo commit após teardown. O gate móvel combina câmera, localização e notificações em singleFlight e coalesce separadamente a leitura de precisão; sinais sobrepostos de focus/resume/visibilidade/FCM não repetem chamadas ao bridge. O perfil usa a mesma trava para câmera/localização e contém falhas como unknown. Assim mount, resume e Permissions API não conseguem regredir a UI, duplicar trabalho nativo ou produzir rejeição global. Gate, perfil, check-in por raio e telemetria periódica consomem o provider sem consultar APIs do navegador diretamente; os shells nativos revalidam no resume e o PWA reage também a mudanças da permissão enquanto a tela está aberta.
useRealTimeTracker também é estritamente foreground: pausa encerra o watch e retomada cria uma leitura nova; não existe coleta nem anúncio de localização em segundo plano. O filtro de deslocamento/tempo é limpo ao mudar o usuário ou funcionário vinculado, portanto a primeira posição da nova identidade não herda o intervalo de cinco minutos nem as coordenadas da sessão anterior.
Atualizações da Play Store/App Store também reconciliam lifecycle. nativeUpdateReconciler serializa consultas de mount e retomada, compartilha o voo ativo e conserva no máximo uma leitura final quando novos sinais chegam; o valor intermediário já superado não altera o aviso, e teardown invalida respostas ainda em voo. Esse canal permanece independente da atualização do service worker, que entrega o bundle compartilhado a web, PWA e shells nativos.
O início da atualização é igualmente serializado: auto-apply e toque manual compartilham um singleFlight, enquanto o banner trava sincronamente antes do próximo render e associa loading/falha à fonte vista pelo usuário. “Later” e dismiss ficam indisponíveis durante a aplicação. No Play Flexible Update, cancelamento/falha recebidos antes de addListener() resolver deixam uma remoção pendente, executada quando o handle chega, sem listener nativo órfão.
A recuperação de câmera serializa escrita, leitura e remoção do marcador único em Preferences. Um resultado restaurado só apaga seu próprio contexto; se outra captura já gravou marcador novo, a Activity antiga não pode invalidar o recovery da superfície atual.
As projeções de notificações e canais são isoladas por identidade mesmo quando o WebView permanece vivo. Ao sair, trocar de conta ou impersonar, useNotificationLogic e useChannels limpam o estado visível e invalidam todas as leituras da sessão anterior; entre mount, foco e resume, somente a resposta mais recente pode publicar. A reconciliação de canais posterga também a remoção dos marcadores locais de “já lido” até o commit vencedor, evitando que uma resposta obsoleta altere badges da nova conta.
O boot central aplica o mesmo isolamento antes de tocar qualquer store ou o cache TanStack Query. Mount, retry, foco, recuperação de rede e resume passam por leitura abortável; eventos sobrepostos da mesma identidade compartilham uma única operação keyed singleFlight, em vez de abrir e abortar vários /api/boot, enquanto troca de conta continua isolada e pode invalidar o trabalho anterior. A reconciliação de canais aplica a mesma coalescência por usuário entre mount, visibilidade, rede e resume. O AbortSignal atravessa DataService e CloudClient, cancela fetch, timeout e espera entre retries. Assim payload ou 401 de uma sessão antiga não hidrata a seguinte nem força reload na tela de login.
O próprio CloudClient fecha a lacuna dos consumidores que não declaravam prazo: GET e o refresh compartilhado de cookie usam 8 segundos, mutações JSON PUT/POST/PATCH/DELETE usam 15 segundos e multipart usa 60 segundos para arquivos em rede móvel. Cada método combina o controller interno com o AbortSignal da tela, inclusive no segundo fetch após refresh e no backoff. Timeout e cancelamento não são repetidos como mutação; respostas funcionais 4xx continuam resolvidas para assertMutationOk, preservando compatibilidade nos 82 caminhos atuais de web, PWA, desktop, Android e iOS.
O reconciliador nativo aceita a leitura inicial do estado e eventos subsequentes do Capacitor, mas publica somente uma transição efetiva. Pauses ou resumes duplicados não reabrem realtime, não refazem queries nem reexecutam sincronizações de privacidade, teclado ou permissão; o primeiro estado continua alcançando consumidores já montados quando o shell inicia em background.
O realtime do chat invalida trabalho ainda mais cedo, por um epoch atualizado durante o render da identidade. Loads, paginação, polling, catch-up e cada evento WebSocket exigem o ticket atual; o flush offline confere o proprietário antes de cada envio. A migração da fila legada preserva cada registro que já traz um ownerUserId válido antes de apagar o array antigo, e a leitura segue filtrada por esse owner; assim a primeira conta a abrir o app não descarta os rascunhos privados de outra conta do mesmo aparelho. Na troca de conta ou desmontagem, useMessages encerra sockets, intervals, reconnects e timers de digitação e limpa mensagens/presença/loading. Uma alteração de alocação fecha todos os sockets do JOB no Durable Object; cada membro autorizado reconecta pelo gate Pages, enquanto a pessoa removida não recebe broadcasts no intervalo até o próximo reload. A mesma rotina fecha os canais de um funcionário em logout/bloqueio remoto ou desativação, e a exclusão captura essa audiência antes de remover as linhas participantes, eliminando também participantes órfãos. No background, o mesmo hook fecha o transporte do canal visível e bloqueia reconnects, mas conserva somente sua inscrição local; ao retornar ao foreground aguarda o histórico antes de reabrir o realtime. O catch-up do socket cobre o intervalo seguinte, de modo que a resposta do histórico não pode sobrescrever uma transmissão já recebida. Além disso, o snapshot preserva exclusivamente os rascunhos locais sending/queued/failed que ainda não apareçam por externalId, evitando que uma rede lenta apague uma mensagem recém-criada sem manter linhas persistidas removidas ou transferidas. A fila offline também ignora mount e eventos de rede no background, disparando somente quando o lifecycle confirma o foreground; uma mensagem escrita pelo usuário não sai durante uma reconexão silenciosa do rádio. A janela Meta também conserva a proveniência do número comercial: uma resposta recebida só promove itens HELD do mesmo par número-cliente; linhas antigas sem essa coluna continuam liberáveis para não ficar presas após o upgrade. Handlers de close/error comparam também a instância exata, impedindo um socket velho de apagar ou recriar o transporte novo do mesmo canal.
A admissão de sessão aplica o mesmo is_active a senha, refresh, Google, Apple, magic link e WebAuthn. Assim uma pessoa desativada não pode reconectar em web, PWA, desktop, Android ou iOS; a impersonação administrativa verifica a sessão do administrador no gate normal e não pode selecionar uma funcionária inativa.
Pushes carregam prova explícita do destinatário. sendPushToUser sobrescreve recipientUserId com o usuário realmente consultado e o propaga pelo Web Push criptografado, FCM e APNs; service worker e provider nativo mantêm o campo nos eventos. useNotificationLogic exige igualdade com a sessão atual antes de alterar histórico, som ou toast, enquanto a navegação PWA recusa outro proprietário. Preferências, banner e auto-dismiss também usam epoch/cleanup, então respostas ou timers da conta anterior não reaparecem após logout ou impersonação.
Arquivos gerados passam por src/shared/platform/fileDeliveryProvider.ts. No Android e iOS, PDFs, CSVs e anexos autenticados do chat são gravados temporariamente em Directory.Cache pelo @capacitor/filesystem e entregues ao share sheet do sistema pelo @capacitor/share. No PWA ou navegador com Web Share de arquivos, o mesmo Blob é entregue à folha de compartilhamento do sistema; ambientes sem esse recurso, ou onde a folha não possa abrir, preservam o arquivo por download. O fetch autenticado de anexos remotos possui teto de 12 segundos e combina o prazo com o AbortSignal do consumidor; o lightbox e os cartões de documento/áudio incompatível do chat mantêm locks síncronos contra toque duplo, loading/nomes acessíveis e abortam ao fechar, trocar URL ou desmontar. Cancelamento não gera alerta, enquanto falha real mantém o cartão disponível e publica feedback recuperável para retry. O retorno tipado distingue shared, downloaded e cancelled, enquanto PDF acrescenta failed: AbortError no navegador e as rejeições Share canceled/Share cancelled do plugin nativo são normalizados como escolha explícita, não disparam download indesejado, háptico de sucesso ou toast positivo falso. Falhas reais continuam propagadas depois que o arquivo temporário é removido e geram feedback recuperável; todo acionador mantém loading/aria-busy para bloquear toque concorrente. O payslip captura o documento que já está montado no cartão expandido, sem atraso de render; uma trava síncrona bloqueia dois exports no mesmo frame, impede recolher e desmontar o alvo durante a captura e descarta resultado pertencente a outro cartão/lifecycle. A fatura aplica o mesmo contrato a PDF e WhatsApp com uma trava compartilhada: não fecha o modal enquanto captura o documento, não usa timer decorativo, valida HTTP e corpo do envio autenticado e descarta toast/háptico de uma fatura substituída. O POST do WhatsApp encerra em 15 segundos e recebe um controller pertencente à fatura; teardown ou troca de documento aborta a rede antes que uma conclusão antiga alcance a interface. O export de gráficos fica sempre visível em dispositivos sem hover e possui alvo de 44 px; mouse desktop conserva a revelação por hover. Invoices, payslips, relatórios, gráficos, históricos, exports de usuários e templates usam esse contrato. Não há permissão de armazenamento compartilhado, e a exportação base64 usada pelo envio server-side de invoices no WhatsApp permanece inalterada.
Despachar uma fatura também é uma operação confirmada pelo backend. O fluxo persiste somente os atendimentos pertencentes ao documento e a própria fatura, rejeita corpos de erro resolvidos pelo cliente HTTP e apenas depois publica estado, auditoria, notificação e sucesso. O modal possui lock síncrono separado, impede captura/WhatsApp e fechamento durante o despacho, usa háptico de seleção no início e háptico de sucesso somente depois da persistência; falha mantém o documento aberto para retry e teardown invalida feedback tardio.
Void e remoção de tarefa compartilham com dispatch um ownership interno por invoice. Cada ação deriva invoice/requests do snapshot síncrono do requestsStore, aplica estado concreto fora de updaters e envia uma intenção a /api/billing/invoice-operation. O Worker repete guards de status/vínculos em cada statement e usa um único D1Database.batch transacional para atendimento, invoice e itens; concorrência faz zero alterações e retorna 409, nunca estado parcial. O rollback cliente recompõe os dois domínios somente se a tentativa ainda for proprietária; teardown limpa owners e bloqueia store, auditoria e toast tardios. O gate global de pureza não possui mais exceções conhecidas.
No envio por e-mail, a confirmação de entrega e a reconciliação do status são resultados distintos. Respostas 4xx/5xx resolvidas pelo CloudClient passam por assertMutationOk; falha de entrega mantém o composer e o rascunho abertos para retry. Depois que o Resend confirmou a mensagem, uma falha ao marcar a invoice como enviada produz Email Sent — Sync Pending, nunca Email Failed, evitando reenvio duplicado. O composer usa AdaptiveBottomSheet, CFInput, Button e IconBadge; possui lock síncrono, exige destinatário com formato de e-mail e assunto/corpo não vazios, normaliza os três valores, bloqueia fechamento enquanto envia e descarta conclusão após teardown. O link usa a origem atual e, fora do browser, o domínio oficial https://app.primecrowncleaning.co.uk.
O editor de contato aberto a partir do inbox particiona seu rascunho por userId + tipo. Trocar entre cliente e funcionário redefine nome/e-mail/telefone antes de qualquer save, invalida a operação e o indicador Saved anteriores e cancela o timer no teardown. A gravação captura a entidade original, trava no mesmo frame, usa háptico de seleção ao iniciar e somente emite sucesso depois que saveClient/saveEmployee confirma o backend; rollback/falha recebe háptico de erro e uma conclusão antiga nunca altera o próximo contato.
Em Team & Clients, administradores possuem importação e exportação CSV como ações icon-only nomeadas. A exportação usa exatamente a coleção visível após busca, categoria e filtros de cliente/equipe, recusa conjuntos vazios, bloqueia ativações concorrentes e entrega o arquivo pelo provider compartilhado; portanto Android/iOS abrem a share sheet, PWA capaz usa Web Share e desktop mantém download. Na importação, escolher outro arquivo, fechar o modal ou desmontar a tela cancela a leitura anterior; somente o FileReader pertencente ao epoch atual pode preencher a prévia. Arquivos maiores que 5 MB são recusados antes da leitura, .CSV é aceito sem diferenciar maiúsculas e falhas limpam resultados antigos com feedback recuperável. A confirmação possui lock síncrono além do estado React, removeu o atraso artificial, aceita persistência assíncrona e mantém o modal closeDisabled até resolver; completion de um lifecycle antigo não fecha nem altera a tela atual. As gravações rodam sequencialmente e cada store action faz rollback somente do objeto otimista ainda pertencente à tentativa; falha antiga não apaga item posterior nem outra edição concorrente. Sucesso aparece somente após todo o lote; falha para a sequência, informa a contagem confirmada, invalida a query correta e mantém retry idempotente disponível. Button preserva o aria-label de ações sem texto também durante loading, anunciando a operação real em vez do genérico “Action”.
O mesmo rollback condicional cobre clientes, equipe, adiantamentos, serviços, entidades fiscais, leads e adicionais. Saves supersedidos não tocam o objeto mais novo; deletes recusados restauram somente a linha ainda ausente. A lista inteira nunca é substituída por um snapshot antigo após uma falha de rede ou conflito, preservando trabalho paralelo em desktop, PWA, Android e iOS.
Feedback tátil é centralizado em HapticsService. Android e iOS usam @capacitor/haptics, com impactos leves/médios para interação e notificações semânticas para sucesso, aviso e erro. PWA mantém navigator.vibrate; a preferência pc_haptics_enabled desativa ambos os runtimes. O listener delegado de cliques só é instalado quando o runtime nativo ou a API de vibração podem produzir feedback, evitando observar todos os cliques em desktops sem essa capacidade. O desbloqueio de Web Audio também é condicionado à presença de AudioContext e usa apenas pointerdown (mouse, caneta e toque) mais teclado; ambos são removidos no primeiro gesto.
Escritas na área de transferência passam por src/shared/platform/clipboardProvider.ts. Android/iOS usam obrigatoriamente @capacitor/clipboard; o PWA tenta primeiro a Clipboard API e, quando ela está ausente ou bloqueada, usa uma seleção temporária removida imediatamente como fallback para Safari/WebView. O fallback preserva e restaura o foco de teclado e a seleção anterior com preventScroll, portanto copiar não abandona o controle acionador nem desloca a tela. Componentes não acessam navigator.clipboard diretamente e só apresentam sucesso depois que a Promise confirma a cópia; Perfil, convites de marketing, pairing do WhatsApp e logs de erro exibem falha recuperável.
Links externos iniciados pela interface passam por src/shared/platform/externalBrowserProvider.ts. Android e iOS usam obrigatoriamente @capacitor/browser para abrir conteúdo HTTPS fora da WebView principal e @capacitor/app-launcher para entregar schemes do sistema, incluindo assinaturas webcal://, ao aplicativo nativo correspondente; o PWA preserva o comportamento do link ou uma nova janela protegida com noopener,noreferrer. WhatsApp, Google Reviews, mapas, calendário, páginas legais, evidências externas e o retorno do orçamento público ao site institucional compartilham esse contrato. A fronteira aceita apenas HTTP(S), webcal:, mailto:, tel: e sms:, resolve mídia relativa contra a origem oficial e rejeita protocolos executáveis ou desconhecidos.
No fluxo de avaliação cinco estrelas, cada regeneração da sugestão cancela a anterior e somente a execução ativa pode publicar texto ou fallback. O botão Google Reviews permanece desabilitado/loading até existir texto utilizável e durante a persistência; falha de clipboard exibe feedback e interrompe o fluxo, sem registrar a avaliação nem abrir uma página vazia. Após cópia confirmada, a persistência é iniciada e a abertura externa ocorre ainda na mesma ativação para preservar o gesto confiável no navegador e usar o provider nativo nos shells. O registro aguarda a resposta atômica real, rejeita erros de aplicação, possui lock síncrono contra toque duplo e só confirma sucesso se a tela ainda pertencer ao mesmo atendimento; falha mantém a avaliação disponível para nova tentativa. O seletor de estrelas publica nome e estado pressionado para teclado, TalkBack e VoiceOver, mantém alvos mínimos de 44 px e o formulário autenticado usa Button, CFInput e IconBadge como a avaliação pública.
O otimizador de rotas cancela as duas etapas de IA (ordenação e análise logística) ao reiniciar ou fechar a folha. Apenas o controller ativo pode publicar resultado ou fallback. A ordenação retornada precisa conter todos os IDs solicitados exatamente uma vez e métricas finitas não negativas; respostas cercadas por fences JSON são aceitas, enquanto rotas incompletas, duplicadas ou inventadas convergem para a sequência cronológica segura.
Análises de incidentes têm uma única autoridade em IncidentItem: o antigo estado duplicado de IA em useIncidentReporting foi removido. A chamada recebe AbortSignal, é cancelada ao desmontar o item e só publica o insight se o controller ainda for o ativo, evitando trabalho e atualização tardia ao fechar ou trocar a ficha.
O protocolo de recuperação de avaliações baixas protege também a escrita persistente no chat. ServiceReviewSection bloqueia ativações repetidas de forma síncrona, cancela a geração quando o atendimento muda ou a tela desmonta e confirma que a operação ainda é a ativa antes de enviar o rascunho e exibir o toast. Se a navegação ocorrer depois que o envio já começou, o id capturado mantém a mensagem vinculada ao atendimento original.
O diagnóstico de risco de continuidade em ConflictIssueCard também possui uma única operação ativa: mudanças de conflito, cliente, funcionária atual ou recomendada cancelam a requisição anterior e limpam o insight correspondente. O contexto enviado à IA usa evidência agregada do histórico real do cliente — visitas concluídas, média das avaliações e experiência com cada funcionária — e exige separar evidência de inferência. O antigo useFleetOptimizer e seu banner foram removidos do quadro operacional porque não existia acionamento nem dado persistente compartilhado — o componente sempre renderizava vazio e apenas carregava código de IA sem entregar funcionalidade.
O radar de sentimento das avaliações foi removido. Ele chamava a IA toda vez que um gerente abria a seção de avaliação, sem guardar o resultado, e exibia um índice de 0–100 estipulado pela IA. Com ele saíram cinco métodos de AIService que nada chamava: analyzeGlobalBrandHealth, generateExecutiveCommentary, generateStrategicReviewReply, parseClientIntent e suggestLoadBalancing.
Alertas LTV_STAGNATION carregam clientId explícito; a interface nunca tenta reconstruir identificadores dividindo o id composto do alerta. A mensagem de retenção cancela gerações anteriores, usa contagem de visitas e média de avaliações reais e primeiro mostra um rascunho. A cópia exige um segundo toque no botão, preservando a ativação transitória requerida pelo clipboard no Safari/PWA e mantendo o mesmo comportamento previsível nos providers Android, iOS e desktop.
O resgate de escala por IA é uma proposta revisável, não uma mutação automática. A elegibilidade exclui profissional inativa, ausente, originalmente indisponível ou com sobreposição no horário; uma nova geração aborta a anterior. validateRescuePlan exige exatamente a tarefa solicitada e uma profissional do conjunto elegível. O bottom sheet mostra visita, substituta e justificativa, e confirmRescuePlan revalida versão/status da tarefa e disponibilidade atual antes da alocação. O contrato não permite que a IA altere horários; rescheduling permanece uma ação manual separada.
O painel de assinatura ICS mantém carregamento e falha visíveis mesmo antes de existir subscription data, tornando o retry alcançável quando a primeira consulta falha. Apple Calendar e Google Calendar têm ações nomeadas separadamente; o disclosure publica aria-expanded/aria-controls, o carregamento usa status e a falha usa alert, mantendo o mesmo feedback em toque, teclado, TalkBack e VoiceOver.
Cada atualização da assinatura ICS pessoal ou dos status de calendário da equipe cancela a consulta anterior com AbortController; somente o controller ainda ativo pode publicar dados, erro ou encerrar o loading. Sair da tela ou desabilitar o hook aborta a operação em voo. Assim retries e trocas rápidas de tela em redes móveis não permitem que uma resposta antiga reverta o estado mais recente. Os estados de carregamento e erro dos dois painéis usam status e alert.
Chamadas e e-mails iniciados nos cartões de clientes ou contatos do chat também passam por essa fronteira. No Android/iOS o App Launcher entrega tel:/mailto: ao aplicativo do sistema; na PWA o anchor permanece sob controle do navegador. Os handlers interrompem a seleção do cartão para que tocar no telefone não abra simultaneamente o detalhe do cliente.
Conectividade passa por src/shared/platform/networkProvider.ts. Android e iOS usam @capacitor/network e mantêm um estado nativo compartilhado; shell, atualização e chat dividem um único listener e uma única leitura inicial, com referência por assinantes e descarte protegido contra respostas tardias após teardown. Uma falha transitória antes de registrar o listener recebe no máximo duas novas tentativas (1 s e 3 s), compartilhadas por todos os consumidores e canceladas quando o último sai; não existe polling permanente. Se somente o snapshot inicial falha, o listener já ativo permanece como fonte autoritativa sem duplicação. Antes da resposta do plugin, o sinal inicial do WebView impede um estado artificialmente online. O PWA lê navigator.onLine e eventos online/offline. Fila de chat, boot, sincronização, notificações e polling consultam esse contrato em vez de acessar diretamente o navegador.
O gate de localização separa permissão negada, baixa precisão e GPS global desligado. locationProvider reconhece OS-PLUG-GLOC-0007, OS-PLUG-GLOC-0017 e as mensagens equivalentes sem confundi-los com negação do aplicativo. Android recebe uma ação para AndroidSettings.Location; iOS mostra o percurso manual por Privacy & Security, evitando schemes de Settings não recomendados para App Review. Ao retornar, permissão e precisão são verificadas novamente.
A aparência das barras de sistema passa por src/shared/platform/statusBarProvider.ts. No Android nativo (API 36 edge-to-edge), a faixa superior da status bar é pintada com a cor da marca através de CSS (html[data-native='true'] com --status-chrome / #2563eb + padding no body com background-clip: content-box). No PWA, a status bar fica acima da WebView e é pintada pelo navegador/sistema via <meta name="theme-color"> (estático e adaptativo), <meta name="color-scheme" content="light dark"> e manifest.json (theme_color e background_color: #2563eb), mantendo background-color: #f8fafc no html e body web para eliminar qualquer linha fina de transição subpixel e evitar que o navegador force a barra para branco. O conteúdo usa --content-safe-top: 0 para não empilhar insets; a barra inferior é coberta pelo BottomNav branco (--content-safe-bottom); overlays full-screen continuam com .pt-safe / --safe-top e --safe-bottom.
Quando existe cor primária explícita, o contraste dos ícones da status bar é derivado da luminância dessa cor realmente pintada; o modo LIGHT/DARK só serve de fallback se nenhuma cor foi fornecida. Assim uma marca clara em tema escuro recebe glifos escuros, sem o modo do conteúdo anular o contraste do chrome no Android/iOS.
O teclado Android usa obrigatoriamente @capacitor/keyboard, adjustResize na Activity e o workaround resizeOnFullScreen do Capacitor. src/shared/platform/keyboardProvider.ts expõe visibilidade e altura nas propriedades do elemento raiz e remove temporariamente o inset inferior já coberto pelo viewport redimensionado. O evento de hide e o disposer compartilham a mesma restauração de altura, --safe-bottom, --content-safe-bottom e --native-bottom-lift; desmontar o shell enquanto as teclas estão visíveis não deixa o layout seguinte preso ao inset temporário. O PWA mantém integralmente o redimensionamento do navegador.
Breakpoints reativos passam por useMediaQuery e pelo registro compartilhado de mediaQueryStore. Cada consulta mantém uma única assinatura nativa de matchMedia, distribuída a todos os consumidores e removida quando o último desmonta. Chat, sidebar, navegação inferior, fatura e folhas adaptativas atualizam somente quando o breakpoint muda de valor; não escutam cada frame de window.resize. A navegação inferior nem sequer é montada acima de lg, portanto desktop não mantém sua assinatura de canais ou observador de tamanho por trás de display: none. Isso evita renders contínuos e trabalho invisível durante rotação, split-screen, abertura do teclado e redimensionamento no desktop.
Polling sensível a bateria usa startForegroundInterval. O scheduler remove o timer no visibilitychange oculto e no evento nativo primecrown:app-pause, recria-o ao retornar e executa uma leitura imediata. Todas as instâncias recebem lifecycle por foregroundLifecycle, que multiplexa uma única assinatura global de visibilidade, pause e resume, ignora estados consecutivos duplicados e a remove quando o último consumidor desmonta. Auth, boot, canais, updates, permissões, saúde do push e histórico de notificações também assinam essa fonte diretamente, portanto uma retomada web/nativa não requer listeners próprios em cada contexto. A checagem de proximidade operacional aplica esse contrato ao GPS de alta precisão de 20 segundos: um gate por epoch serializa pedidos no mesmo foreground; cada pedido captura também o ID explícito da visita, portanto pause, troca de visita ou teardown invalida o voo mesmo quando o próximo atendimento tem as mesmas coordenadas. Distância, erro e confirmação automática são zerados na troca; coordenada/erro tardio não altera a nova interface nem dispara auto-start, e um fix novo fica livre na retomada. Clock-in e encerramento adquirem ainda um lock síncrono por visita antes de preparar evidências ou pedir o ponto manual; a captura imediata possui gate próprio, descarta permissão/coordenada/erro resolvido após pause, aba oculta ou troca de alvo e libera o busy para retry sem converter cancelamento de lifecycle em override de coordenada zero. A preflight bloqueia dismiss, fecha a si mesma após GPS/override sem depender do host, dois toques não duplicam GPS/sync/log, e teardown cancela silenciosamente a continuação do wizard. Polling de páginas, fila operacional do chat, conexão/saúde do WhatsApp e o relógio compartilhado de textos relativos, SLA, agenda e centro operacional seguem a mesma política; relógios locais duplicados foram removidos. Conectividade também é multiplexada: Auth, boot, canais, updates e fila offline assinam diretamente networkProvider, que mantém um único par online/offline na web ou um único listener do plugin Capacitor. O NativeBridge não retransmite mais mudanças como eventos customizados, eliminando refreshes paralelos na reconexão.
A fila offline do chat persiste externalId, conteúdo, mídia, reply e horário original no IndexedDB. Ao reabrir o app sem rede, esses registros recompõem balões Queued offline sob a identidade proprietária; nenhuma mensagem aceita desaparece visualmente. Reconexão web e evento do plugin nativo compartilham uma drenagem serial, e troca de conta espera a anterior encerrar antes de ler sua própria partição. Falha online vira Failed e expõe Retry touch/teclado; a nova tentativa reutiliza a chave idempotente original e o registro só é removido após aceite do servidor. A chave é única globalmente: conflito no mesmo canal recupera a mensagem original sem side effects; conflito em outro canal retorna 409 neutro, sem revelar o canal ou o conteúdo proprietário.
O painel operacional do inbox usa locks síncronos particionados por item para reabertura, retry/dismiss de falha e send-now/cancel da fila WhatsApp. Isso bloqueia toque duplo no mesmo registro sem perder o loading de outra ação concorrente; aria-busy, fechamento bloqueado e rótulos Retrying/Sending mantêm feedback equivalente em desktop, PWA, Android e iOS, e o háptico ocorre somente após aceite. Alertas No ACK não oferecem reenvio automático, pois a ausência de confirmação não prova ausência de recebimento; o estado vazio não declara falsamente que todos os clientes receberam.
O hook compartilhado de push exige usuário autenticado e ausência de impersonação: montagem ou retomada na tela de login não consulta permissões nem registra o dispositivo, e Subscribe sem sessão retorna indisponibilidade explícita. Cada operação captura a identidade e a geração do lifecycle: logout, troca de conta e desmontagem descartam permissões, resultados de registro e feedback tardios. O Web Push propaga cancelamento às leituras/escritas HTTP e revalida após esperas do navegador, impedindo que uma assinatura obtida pela sessão anterior seja salva pela próxima. Além disso, todo POST inclui o proprietário que iniciou a assinatura; o endpoint compara esse valor ao reference_id autenticado no próprio POST e recusa a divergência com 409. Isso fecha a janela restante em que o cookie muda depois da checagem local, mas antes da gravação. Cancelar HTTP não desfaz uma gravação já aceita pelo servidor. A desativação explícita também pertence à sessão: callbacks retidos após logout são ignorados; conclusão nativa tardia não sobrescreve a permissão da conta seguinte, e uma busca web antiga não consulta nem remove a assinatura do novo usuário.
O banner de roteamento WhatsApp propaga AbortSignal nas leituras e mudanças de destino, mantém controllers separados e invalida ambos por epoch ao trocar cliente/canal. O save possui lock síncrono e assertMutationOk; recusa 4xx, teardown ou resposta obsoleta não produzem falso sucesso, loading nem toast na conversa seguinte. Após aceite, a releitura também pertence ao lifecycle corrente. Sem sessão vigente, o seletor mostra modo automático por contexto, sem afirmar privacidade confirmada; Management pode ser escolhido explicitamente. A retomada web/nativa busca a rota atual e suspende opções antigas durante a leitura, usando a releitura pós-save quando há gravação em curso.
Mutações da fila WhatsApp respeitam a fronteira de claim do runner: somente PENDING aceita send now ou cancelamento. PROCESSING é exibido como In flight, sem ação; predicates condicionais devolvem 409 se o runner ganhar a corrida antes da mutação, evitando recolocar um envio ativo ou apagar sua mensagem. Os endpoints de fila e falhas usam onError sanitizado, e erro D1 na listagem retorna 500 estável; a interface preserva o último snapshot em vez de transformar indisponibilidade em “nenhum alerta”.
O endpoint de falhas transmite reconciliação pelo Durable Object depois de cada mutação aceita. Retry publica deliveryStatus=pending; dismiss de uma mensagem mantida limpa o estado; acknowledge publica deliveryAlertDismissedAt. O campo é entregue pelo mapper de histórico, preservado no merge, aplicado em eventos deliveries e consultado pela regra compartilhada de No ACK, de modo que conversa aberta e reload convergem para o mesmo resultado sem falso alerta recorrente.
O painel operacional mantém loadError separado de listas e loading. Falha parcial preserva seções atualizadas e sinaliza que o restante pode estar antigo; falha total conserva o snapshot anterior. O acionador fechado recebe marcador/nome de dado desatualizado, o sheet publica alerta com retry manual e os estados vazios são suprimidos até uma leitura completa. Polling não emite toast repetitivo, enquanto retry solicitado pelo usuário mostra spinner e reutiliza o mesmo lock de leitura.
O mesmo painel protege sua fronteira de sessão com lifecycleEpochRef. Cleanup de logout/troca de identidade/desmontagem invalida leitura e ações pendentes, limpa locks e impede que respostas antigas escrevam estado, toast, háptico ou callbacks no inbox seguinte. A leitura ativa é identificada por token (loadRequestRef), permitindo uma nova leitura após a remontagem do React Strict Mode sem que o finally antigo limpe o loading novo.
ArchivedChannelNotice trata o request de reabertura como mutação autoritativa: requestLockRef bloqueia dois toques no mesmo frame, o estado waiting só nasce de success=true e um lifecycle epoch contém estado/toast/háptico/callback após troca de conversa ou sessão. ownerKey=channelId força uma fronteira de montagem por conversa, portanto askedNow não migra para o próximo canal. O callback de rede retorna o resultado bruto; somente o notice ativo confirma e pede refresh dos canais.
O composer de template exibido fora da janela de 24 horas também pertence ao canal atual. Uma troca limpa template, variáveis e erros, invalida o catálogo que terminar tarde e aborta o envio em voo. O lock é adquirido antes de qualquer atualização React, portanto dois toques no mesmo frame não criam duas mensagens nem duas cobranças; somente o owner ainda ativo pode publicar erro, limpar o editor ou disparar o refresh do chat.
ChatSettingsPanel não edita configuração nenhuma: mostra as preferências deste aparelho (vibração, silenciar avisos), a saúde do WhatsApp e, no chat standalone, perfil e saída. Bot, limites anti-ban, respostas rápidas, horário comercial e a vida útil do chat se editam só em Settings → Communication Hub; o painel tinha uma segunda cópia desses editores e agora leva até lá pelo botão Edit WhatsApp settings (e pela linha Communication Hub do menu). Sem gravação, o inbox não precisa mais travar navegação durante um save.
O ecrã de falha do boot usa o mesmo SystemScreen do splash Connecting Engine (tela cheia idêntica) e diz o motivo: sem conexão, servidor lento, sessão não confirmada (com Sign in again) ou erro do servidor, com um código (BOOT-401, BOOT-503, BOOT-NETWORK). Cada falha grava CLIENT_BOOT_ERROR em system_logs com o tipo e o status — antes o ecrã culpava a internet em qualquer caso e nada ficava registrado.
Trocar de seção não cobre mais o app com o Loading Engine. Cada página é um chunk carregado sob demanda e todo deploy renomeia todos, então a primeira visita a cada seção depois de um deploy esperava o download atrás do loader de tela cheia, e uma seção já em cache piscava o loader por um instante. Agora: a navegação usa startTransition (a tela atual fica até a próxima estar pronta); prefetchPages baixa em segundo plano, com o app ocioso, as páginas que o papel pode abrir (as 16 para ADMIN/MANAGER, 8 para equipe e cliente; nada com economia de dados); e .splash-reveal só desenha Loading Engine e Connecting Engine depois de 300 ms, então um carregamento mais rápido que isso não mostra splash nenhum. Updating App e o ecrã de falha aparecem na hora. O outro caminho lento depois de um deploy é a própria atualização: a versão nova é aplicada na próxima troca de tela, o que recarrega o app e refaz o boot.
O painel do admin mostra uma seção só quando ela tem algo. Saíram o menu Board Layout (dez interruptores de seção, modo cartão/lista e “mostrar seções vazias”), o modo lista (DashboardTable/DashboardListRow) e os horizontes por seção; Upcoming roster e Settled archives, que já nasciam desligadas, saíram do painel — Full Schedule e Service History são as páginas delas. Helpers repetidos viraram um só: roundPence (src/shared/money.ts), functions/lib/escapeHtml.ts, parseJsonColumn, functions/lib/parseDbDate.ts, formatPreviewTime do chat e normalizeUkPostcode do ukAddress; a fachada FinancialService e o CFStatCard foram removidos, e hashToken substitui hashRefreshToken/hashLinkToken.
Settings → Maintenance é só o Data check (DataSanityView). System Purge e Factory Reset saíram: o primeiro só mostrava um toast ou limpava fotos da memória do navegador até o próximo refresh, e o segundo apagava o localStorage, que guarda só preferências de interface.
A leitura de WhatsApp Health usa uma única função para entrada da seção e refresh manual, serializada por healthRequestRef e limitada por lifecycle epoch/token. Falha conserva o último snapshot e publica alerta persistente; sem snapshot, cards usam Checking/Unknown e snippets ficam ocultos, de modo que ausência de evidência jamais apareça como risco LOW, fila/falhas zero ou ausência confirmada de tráfego. O retry usa Button canônico com loading acessível e háptico compartilhado.
A gravação de voz assina o mesmo foregroundLifecycle e encerra o stream ao entrar em background. Isso preserva o take e libera o microfone uma única vez mesmo quando WebView e Capacitor reportam a transição juntos; nenhum componente de produto mantém listeners globais próprios de visibilidade/pause/resume.
O reconcile lento da lista de canais e o fallback de polling de mensagens usam startForegroundInterval com início adiado. Eles mantêm a cadência anterior no primeiro foreground, removem o timer por completo em background e fazem uma leitura fresca na retomada; não há wakeup periódico que apenas acorde para consultar document.visibilityState.
Listeners globais de gesto que não cancelam o comportamento do navegador são passivos: desbloqueio de áudio, fechamento externo de popover e fim/cancelamento do pull-to-refresh não bloqueiam a thread de scroll. Somente o touchmove do pull-to-refresh permanece explicitamente não passivo, pois chama preventDefault depois que o controlador confirma o gesto vertical no topo.
Feedback temporário de cópia, retry, save e seleção atrasada usa useReplaceableTimeout. Um novo gesto cancela o callback anterior e o teardown cancela o timer ativo, impedindo que telas desmontadas recebam atualizações tardias ou que um feedback antigo encurte a confirmação mais recente.
Menus ancorados usam usePopoverMenu: foco entra no primeiro item, setas circulam por menuitem, menuitemradio e menuitemcheckbox, Escape fecha e restaura o gatilho, e pointer fora fecha sem roubar o foco do destino tocado. Configurações e o seletor desktop de conversas seguem o mesmo contrato; no mobile, conversas continuam como bottom sheet nativo.
Regiões declaradas com overflow-y-auto, overflow-x-auto ou overflow-auto contêm o overscroll no eixo correspondente, impedindo que o fim de uma lista, tabela, rail ou sheet mova a superfície atrás. No iOS, as três recebem momentum com -webkit-overflow-scrolling: touch; nenhum touch-action fixa o eixo, portanto uma tabela horizontal ainda permite que o gesto vertical role a página.
O coordenador foregroundLifecycle combina visibilidade do documento com pause/resume nativo: o app só é considerado ativo quando ambos concordam. Eventos atrasados da WebView não podem reativar polling, validação de sessão, permissões ou captura de mídia enquanto Android/iOS está pausado; da mesma forma, um resume nativo aguarda o documento ficar visível. Ao sair de um intervalo sem assinantes, o coordenador relê data-app-state, evitando conservar um pause antigo quando o resume aconteceu sem listeners montados.
Decisões funcionais por família de dispositivo passam por DeviceService, que prioriza o runtime Capacitor e centraliza os fallbacks web. Cotação/WhatsApp, instruções de calendário e rótulos de passkey compartilham essa classificação, incluindo iPadOS com user agent de desktop; user agent bruto permanece apenas como metadado diagnóstico ou fallback de rótulo.
Capacidades de entrada ficam em inputCapabilities; suporte touch (gestos) e ponteiro primário coarse (teclado virtual) são contratos distintos. No chat, ChatInbox é a fonte única do breakpoint md (768 px) e entrega o estado reativo ao controlador de seleção, impedindo que tablets abram simultaneamente a coluna desktop e o bottom sheet móvel. Conversa, perfil de cliente/equipe e painel contextual da tarefa são montados somente na árvore correspondente; CSS não mantém dashboards ou efeitos desktop invisíveis no celular. Ao cruzar para desktop por rotação, resize ou dobra, a visibilidade móvel é bloqueada no próprio render e seu estado é limpo, portanto o overlay não reaparece ao voltar para uma largura estreita.
Shells de tela inteira usam viewport dinâmica (100dvh) como autoridade de altura. O token visual UI_TOKENS.layout.main não impõe 100vh, evitando que um min-height estático vença quando chrome móvel ou teclado reduz a área visível; a cotação pública segue o mesmo contrato.
A abertura usa @capacitor/splash-screen: o Android mantém a splash de marca até o primeiro commit do React e então a oculta pelo splashScreenProvider. O auto-hide nativo de três segundos permanece como proteção caso a origem HTTPS não consiga executar o JavaScript. O PWA não chama o plugin e conserva seu carregamento normal.
O contador de mensagens não lidas no ícone passa por src/shared/platform/appBadgeProvider.ts. Android e iOS usam @capawesome/capacitor-badge e mantêm o número no ícone quando o sistema oferece suporte; PWA preserva a App Badge API do navegador. Home screens/launchers sem suporte são tratados como ausência do recurso, sem bloquear notificações ou a inicialização.
Escritas de badge são serializadas para que uma chamada lenta antiga nunca termine depois da contagem mais recente. Valores negativos/não finitos convergem para zero; o service worker aplica a mesma normalização. Ao desmontar o layout autenticado (logout ou troca de conta), o hook enfileira uma limpeza explícita, evitando expor a contagem do usuário anterior no launcher Android/iOS ou no ícone da PWA.
Atualizações mantêm dois mecanismos: os assets web são renovados pelo service worker, enquanto os shells consultam Google Play no Android e App Store no iOS por appUpdateProvider ao abrir e ao retomar o aplicativo. Quando há um novo binário, AppUpdateBanner mostra a loja e a ação corretas; Android pode usar atualização imediata/flexível, enquanto iOS abre a ficha oficial da App Store. O adiamento pertence à origem exibida, portanto postergar o reload web não esconde um update da loja (nem o inverso), e a ação aplica exatamente o canal selecionado. Cancelamento ou falha sempre libera novamente a ação compartilhada e permite tentar de novo.
2. Arquitetura de Alto Nível (Diagramas Mermaid)
Section titled “2. Arquitetura de Alto Nível (Diagramas Mermaid)”graph TD
subgraph ClientLayer ["Client Layer"]
UI["React 19 SPA (Vite)"]
PWA["Browser / Installed PWA"]
Android["Android / Capacitor 8"]
Platform["Platform Capability Layer"]
Zustand["Zustand Stores (State)"]
Query["TanStack Query (Cache)"]
PWA --> UI
Android --> UI
UI --> Platform
UI --> Zustand
UI --> Query
end
subgraph EdgeLayer ["Edge Backend (Cloudflare Pages Functions)"]
Hono["Hono Router & Zod Validation"]
Auth["JWT & Role Authorization"]
Hono --> Auth
end
subgraph StorageLayer ["Persistence & External Services"]
D1[("Cloudflare D1 (SQLite)")]
R2["Cloudflare R2 (Media/Audio)"]
EvoAPI["WhatsApp Evolution API"]
Gemini["Google Gemini API (AI Engine)"]
end
Query <-->|/api/boot & Atomic REST| Hono
Hono <--> D1
Hono <--> R2
Hono <--> EvoAPI
Hono <--> Gemini
3. Modelo de Dados e Esquema ER D1 (SQLite)
Section titled “3. Modelo de Dados e Esquema ER D1 (SQLite)”erDiagram
auth_accounts ||--o{ auth_providers : "possui"
auth_accounts ||--o{ refresh_tokens : "gera"
clients ||--o{ service_requests : "solicita"
clients ||--o{ invoices : "recebe"
employees ||--o{ service_requests : "executa"
service_requests ||--o{ invoices : "gera"
leads ||--o{ chat_channels : "inicia"
chat_channels ||--o{ chat_messages : "contém"
auth_accounts {
string id PK
string email UK
string phone UK
string role
string referenceId
}
clients {
string id PK
string name
string email UK
float walletBalance
string addressesJson
}
employees {
string id PK
string name
string email UK
float hourlyRate
}
service_requests {
string id PK
string clientId FK
string employeeId FK
string status
float totalAmount
string scheduledDate
}
invoices {
string id PK
string requestId FK
string status
float amount
}
leads {
string id PK
string name
string email
string whatsapp
string status
}
4. Gestão de Estado Frontend (Zustand + TanStack Query)
Section titled “4. Gestão de Estado Frontend (Zustand + TanStack Query)”sequenceDiagram
autonumber
participant App as React App
participant Query as TanStack Query Cache
participant Store as Zustand Stores
participant API as Edge API (/api/atomic/*)
participant D1 as Cloudflare D1
Note over App, D1: 1. Hydration Inicial
App->>API: GET /api/boot
API->>D1: SELECT * ALL TABLES
D1-->>API: Full State JSON
API-->>Query: Seed Query Cache
Query->>Store: Project to Zustand Stores (useStoreQuerySync)
Note over App, D1: 2. Mutação Otimista & Sync
App->>Store: Action Call (ex: updateRequest)
Store->>App: Update UI Instantly (Optimistic)
Store->>API: POST /api/atomic/requests
alt Sucesso no Servidor
API->>D1: UPDATE D1 DB
D1-->>API: OK
API-->>Query: Refresh Entity Cache
else Erro no Servidor
API-->>Store: Fail Signal
Store->>App: Rollback State + Toast "Sync Failed"
end
5. Fluxos Principais da Aplicação (Diagramas de Sequência)
Section titled “5. Fluxos Principais da Aplicação (Diagramas de Sequência)”A. Fluxo de Cotação Pública, Captura de Lead e WhatsApp Chat
Section titled “A. Fluxo de Cotação Pública, Captura de Lead e WhatsApp Chat”sequenceDiagram
autonumber
actor User as Cliente Web
participant Form as PublicQuote Form
participant API as Functions API
participant D1 as Cloudflare D1 DB
participant WA as Evolution API (WhatsApp)
participant Admin as Inbox do Manager
User->>Form: Preenche residência e clica em "Falar com Agente"
Form->>API: POST /api/leads/chat-initiate (dados da quote)
API->>D1: UPSERT lead + canal + lead_quote OPEN
Note over API,D1: Sem client e sem service_request
API->>WA: Send initial WhatsApp template
WA-->>User: Recebe WhatsApp de confirmação
API-->>Admin: Notifica novo Chat/Lead e fila Quotes
Admin->>API: Confirma preço + entidade fiscal
API->>D1: Cria/reutiliza client + cria service_request
B. Ciclo de Vida de um Atendimento (Service Request)
Section titled “B. Ciclo de Vida de um Atendimento (Service Request)”stateDiagram-v2
[*] --> REQUESTED: Gestor confirma lead_quote
REQUESTED --> PENDING: Manager analisa disponibilidade
PENDING --> CONFIRMED: Funcionária alocada
CONFIRMED --> IN_PROGRESS: Check-in por telemetria GPS
IN_PROGRESS --> COMPLETED: Check-out por telemetria GPS
COMPLETED --> INVOICED: Fatura gerada (InvoiceStateLogic)
INVOICED --> PAID: Pagamento processado
CONFIRMED --> CANCELLED: Cancelamento (Alica CancellationRules)
PENDING --> CANCELLED: Cancelamento
6. Análise Detalhada dos 7 Módulos de Domínio
Section titled “6. Análise Detalhada dos 7 Módulos de Domínio”🏢 Módulo 1: Vendas & Orçamento Público (PublicQuote / leads)
Section titled “🏢 Módulo 1: Vendas & Orçamento Público (PublicQuote / leads)”- Arquitetura:
src/pages/PublicQuote/ - Capacidades:
- Cálculo de preço em tempo real com base em quartos, banheiros, metragem e frequência.
- Seleção de serviços adicionais (addons).
- Captura imediata de lead e cotação via
/api/leads/chat-initiate. - Transição contínua para o Chat de Atendimento ao clicar em “Falar com Agente” (
/api/leads/chat-initiate).
💬 Módulo 2: Comunicação & Atendimento Omnichannel (communication)
Section titled “💬 Módulo 2: Comunicação & Atendimento Omnichannel (communication)”- Arquitetura:
src/features/communication/,src/components/chat/ - Capacidades:
- Inbox unificado para mensagens internas e WhatsApp.
- Suporte a SLA de Resposta com sinalização de atrasos via
ResponseSlaBadge.tsx. - Envio de mídias, áudios e localização geográfica.
📅 Módulo 3: Motor de Agendamento & Recorrência (scheduling)
Section titled “📅 Módulo 3: Motor de Agendamento & Recorrência (scheduling)”- Gravações em lote contam as recusas:
countRefusedSavesconta as visitas que o servidor recusou, e não só os erros de rede, nas séries a partir de cotação, na extensão e na retomada de série. - Arquitetura:
src/features/scheduling/services/ - Serviços Especializados:
AvailabilityService: Identifica janelas de horário disponíveis considerando o endereço do cliente e buffers de trânsito.ConflictService: Impede agendamento duplo de funcionárias ou choque de horários.RecurrenceService: Calcula a projeção de visitas futuras conforme a frequência contratada.
🚜 Módulo 4: Operações de Campo & Telemetria (field-operations)
Section titled “🚜 Módulo 4: Operações de Campo & Telemetria (field-operations)”- Arquitetura:
src/features/field-operations/services/ - Serviços Especializados:
StaffMatchingService: Calcula o score de compatibilidade entre a funcionária e o cliente com base no histórico de afinidade e na proximidade de transporte.ServiceGeoAction: Registra o ponto de entrada (check-in) e saída (check-out) da funcionária no imóvel via coordenadas GPS.checkInDistance(servidor): no clock-in, mede a distância até as coordenadas da visita contraallocationRules.geofenceRadiusMeters, descontando a precisão do GPS; gravaserverDistanceMeters/outOfRadiusnocheckIne registraCHECK_IN_OUT_OF_RADIUS, sem bloquear. O Activity Log e o histórico mostram Off-site.
💰 Módulo 5: Faturamento & Inteligência Financeira (billing)
Section titled “💰 Módulo 5: Faturamento & Inteligência Financeira (billing)”- Arquitetura:
src/features/billing/services/ - Serviços Especializados:
ProfitLogic: Apura o lucro líquido da empresa por serviço descontando o pagamento da funcionária e custos operacionais.- Relatórios contam só trabalho realizado (
isRealisedJob: visita concluída ou cancelamento com taxa):- o que falta receber inclui visitas concluídas ainda sem fatura;
- o HMRC declara só visitas pagas por método rastreável, com as taxas de cancelamento e sem o custo delas;
- a divisão por entidade fiscal usa só as faturas das visitas em tela;
- BI e margem descontam reembolsos;
- a carga da equipe mede a semana atual de Londres contra 48 h;
- clientes com visita marcada não aparecem como em risco.
InvoiceStateLogic: Controla a emissão, envio por e-mail/WhatsApp e quitação de faturas.- Reparos de integridade: visita sem check-in pede confirmação manual (não grava mais GPS fictício); reparo de IVA e compressão do dia só anunciam sucesso após salvar.
- Simplificação: sem sync do banco inteiro (
/api/syncremovido), sem simulador de WhatsApp, sem estratégia de crescimento por IA, sem “raciocínio” de IA na rota e sem números fixos como métricas (Marketing 98%/Elite, Leads 85%, rota 15%); o chat do cliente não grava urgência de IA. - Menu enxuto: Daily Desk, Sales, Finance, Team, Insights. Staff Availability e Supplies viraram abas do Operations; Revenue, Quality e Marketing viraram abas do Reports (clientes em risco em Risk); o Accounting Hub (que nenhum menu alcançava) virou as abas Cash check e Integrity do Billing, mais o botão QuickBooks. As rotas antigas continuam abrindo a aba certa.
- Configurações sem leitor removidas: aba AI Engine, Auto-Quote Bot, Review Sentiments, modos de cancelamento/remarcação e palavras de incidente (só o simulador lia); Supplies sem auditoria por IA; “Active accounts” = clientes com visita concluída em 6 meses. Também: taxa fixa por tarefa, chat direto cliente–equipe, retenção de dados do chat e fuso UTC do horário comercial. E: e-mail de suporte e site.
- Mudanças grátis por ano: limite anual (padrão 2) calculado a partir das marcas
allowanceUsenas visitas dos últimos 12 meses. Só gasta quando a política cobraria taxa. Cancelamento recusado ou desfeito devolve a mudança. Não há mais saldo por cliente. - Padrões e IA: padrões de configuração num único módulo (
settingsDefaults.ts); nome padrão “Prime Crown”; sem alertaLTV_STAGNATIONnem rascunho de retenção por IA na integridade financeira; card de continuidade mostra a divisão real de visitas em vez de texto de IA. - Fidelidade removida: sem nível nem pontos no app (colunas ficam no banco;
LEADsegue só como marcador legado do servidor); VIP continua; rótulos de jargão trocados por linguagem simples. - Deploy: push em
mainnão publica. O app vai ao ar só pornpm run deploy:web(upload direto, com travas: árvore limpa, HEAD = origin/main, backend em dia, sem valores do.env.localno build, e conferência do domínio);npm run shipfaz push + deploy. O build pela integração Git falhava com “unable to submit build job”. - Fotos de evidência: o arquivo só é apagado depois de a visita deixar de referenciá-lo (aba de relatório espera o save; wizard só apaga fotos tiradas nele).
- Repreçar em fatura de rascunho: acha a linha pelo
requestId(e não pela posição, que a taxa de remarcação deslocava) e não põe IVA em cliente que absorve IVA. - Confirmações de dinheiro esperam o salvamento: aprovar ou rejeitar pagamento, conferir o dinheiro da equipe e gerar fatura só mostram sucesso, e só avisam o cliente, depois que o servidor grava; se ele recusar, a tela volta ao estado anterior.
- E-mails de cobrança: escapam os dados de cadastro no HTML, não enviam fatura anulada, e o recibo leva a data em que o pagamento entrou.
- Entidade fiscal em uso não é excluída: a rota responde 409 enquanto houver fatura, visita ou cliente ligado a ela.
- Participação nos lucros:
calculateProfitSharesó conta lucro que nenhum holerite compartilhou, e o aviso de pagamento mostra os adiantamentos que o holerite de fato descontou. - Fechamento da folha: confere visitas abertas entre as meias-noites de Londres do período, e não mais pela data em UTC, que deixava o último dia de fora no verão.
- Pagamentos online (2026-09-11): só o webhook assinado do gateway marca fatura como paga.
POST /api/payments/checkout(Stripe Checkout / GoCardless Instant Bank Pay ou mandato),/api/payments/wallet(débito no livrowallet_transactionse liquidação na mesma transação) e/api/payments/transfer-claim(fatura emPENDING_REVIEW). Webhooks por entidade em/api/webhooks/{stripe,gocardless}?entity=<id>, com o segredo da entidade;settleCheckoutliquida tudo numa transação D1 com token. Tabelapayment_checkouts(0135). Detalhes emdocs_src/content/docs/modules/billing.md§6. - Fronteira do CLIENT: endpoints atômicos de fatura/cliente e atualização de visita são só da equipe; ações de dinheiro do cliente passam por
/api/payments/*. Reserva criada pelo cliente é precificada no servidor (clientBookingFields) com campos de pagamento zerados. - Segredos de gateway (
gatewaySecrets.ts) nunca vão ao navegador e o upsert da entidade fiscal os preserva; Remove, ao lado de cada chave salva em Settings, envia a chave comonull, único valor que o upsert trata como apagar (antes só dava para substituir; a rotafiscalEntitySecrets, sem chamador, saiu). A store guarda a entidade sem os segredos e com os indicadores…Setjá atualizados (withoutGatewaySecrets), então a chave digitada não fica na memória do app e Ready aparece sem recarregar; todo e-mail sai de@primecrowncleaning.co.uk.
💵 Módulo 6: Folha de Pagamento & Retenções (payroll)
Section titled “💵 Módulo 6: Folha de Pagamento & Retenções (payroll)”- Arquitetura:
src/features/payroll/services/ - Serviços Especializados:
PayrollPeriodService: Agrupa horas e serviços finalizados dentro da quinzena/mês operacional.
PayrollSettlementLogic: Processa o cálculo de honorários, bônus e retenções de reservas de emergência. A geração em lote indexa serviços, lançamentos já pagos e lucro do período uma única vez, evitando repetir cruzamentos completos para cada profissional sem alterar regras de Cash in Hand, adiantamentos, cancelamentos compensados, participação ou deduplicação.
A criação usa a fronteira transacional /api/atomic/payrollGenerate: ciclo, todos os holerites DRAFT e depósito automático da reserva pertencem ao mesmo D1Database.batch. Um UUID de ownership temporário no ciclo condiciona cada INSERT dependente à decisão vencedora; o perdedor não pode anexar novos IDs. Colisões do vencedor falham e revertem o batch. O servidor valida contagem/vínculo e, após a transação, compara ciclo, holerites e reserva persistidos: retry exatamente equivalente recupera a resposta com idempotent: true, enquanto divergência recebe 409. Saldo, autor e horário são derivados no D1/sessão; horários devolvidos diretamente ao cliente são ISO 8601 UTC com Z, sem ambiguidade entre Safari/iOS e Chromium/Android/desktop. A interface adquire lock antes do primeiro await, usa loading semântico do botão, publica os campos de auditoria retornados e reconcilia IDs para que uma resposta perdida não duplique stores. Auditoria e sucesso só avançam após o conjunto integral ser aceito. O antigo sucesso parcial entre entries, run e reserve foi removido nas quatro plataformas.
O mapper comum do /api/boot reconhece somente campos de instante com a forma exata de CURRENT_TIMESTAMP e acrescenta a zona UTC antes de serializar. Isso cobre createdAt, updatedAt, settledAt, timestamp, startDateTime e equivalentes sem reinterpretar datas civis como periodStart ou dateOfBirth. Os enriquecimentos que não passam pelo mapper aplicam o mesmo contrato explicitamente a incidentes, check-in/out, horário original de edição, carteira, pagamentos, adiantamentos liquidados e último sync de calendário; valores YYYY-MM-DD continuam datas civis. No ledger da reserva, leituras de saldo e a janela inicial ordenam por datetime(created_at) para tolerar dados históricos mistos; novas gravações permanecem no formato SQLite e a fronteira HTTP entrega ISO UTC. Assim, parsing visual e ordenação financeira são iguais em PWA, iOS, Android e desktop.
Respostas incrementais passam por src/shared/api/apiJson.ts. CloudClient usa esse parser em GET/POST/form/PUT/PATCH/DELETE, cobrindo sua superfície compartilhada, e chamadas diretas às APIs próprias fazem o mesmo: identidade/sessão, provedores de login, passkeys, recuperação, Perfil, portais públicos, uploads, IA, WhatsApp, QuickBooks, conciliação, custódia, férias, calendários, telemetria, gestão de usuários e ações operacionais. A caminhada é feita no grafo recém-criado por response.json() sem cópia adicional e reconhece campos de instante em camelCase e snake_case; somente strings no formato exato do SQLite recebem T/Z. Um teste de contrato varre o frontend e permite parsing direto apenas dentro dessa fronteira e em APIs externas declaradas. Isso mantém stores coerentes imediatamente após mutações, inclusive diante de Workers antigos, sem converter datas civis nem texto parecido com data.
Retirada manual da reserva é mostrada somente a ADMIN e envia ao Worker apenas a intenção, nunca saldo, autor ou horário calculado no dispositivo. O INSERT ... SELECT autoritativo deriva o último saldo, impede overdraft no próprio statement e fixa created_by pela sessão e created_at pelo D1. Retry com ID e intenção idênticos devolve o lançamento existente; colisão divergente recebe 409. A store adiciona exclusivamente a linha retornada pelo servidor. O formulário permanece aberto quando há recusa, bloqueia fechar/editar/toque concorrente durante o save e usa CFInput, Button, loading e alerta compartilhados em desktop, PWA, Android e iOS.
O payload inicial seleciona primeiro os 200 lançamentos mais recentes da reserva (created_at, id descendentes) e então inverte essa janela para a ordem cronológica esperada pela store. O limite deixa de truncar justamente o saldo corrente quando o histórico ultrapassa 200 linhas.
O read model da folha separa obrigação corrente de histórico: uma passagem em calculateOutstandingStats ignora PAID, agrega bruto, dinheiro com equipe, contas a pagar/receber e arredonda cada total a centavos. A geração confirmada prepende os novos lançamentos, concordando com o boot descendente, e formatCurrency fixa mínimo e máximo de duas casas. Assim desktop, PWA, Android e iOS não exibem totais vitalícios sob o rótulo de ciclo ativo nem mudam a posição de um holerite após reload.
O diálogo de fechamento de folha tem lock síncrono comum a confirmar, gerar suplementar e sair. closePayrollRun devolve sucesso autoritativo: somente true desmonta o diálogo; recusa/erro mantém verificação e ações para retry. No Worker, um compare-and-set fecha somente ciclo OPEN sem tarefas abertas no intervalo; concorrência recebe 409 e nunca reescreve a assinatura vencedora. Nome e horário são derivados da sessão/D1 e a resposta alimenta store e auditoria, eliminando confiança em closedBy ou relógio do dispositivo. O POST individual também é creation-only: colisões não alteram totais, período ou ciclo fechado, e autoria/horário são servidores. A trava e o loading são liberados em finally, cobrindo toque duplo no mesmo frame e exceção em web, PWA, Android, iOS e desktop.
A transição individual de holerite para APPROVED ou PAID segue o mesmo contrato autoritativo e mantém ownership por ID antes do primeiro await. A criação individual aceita somente DRAFT e colisão de ID é recusada sem overwrite. A rota de transição implementa compare-and-set para a máquina DRAFT → APPROVED → PAID: salto, regressão ou decisão concorrente recebe 409 com o snapshot persistido, que reconcilia a tela. O botão publica estado ocupado, bloqueia nova ativação e o store/log/sucesso só avançam após aceitação do Worker. Para PAID, um token de ownership gerado com Web Crypto restringe um único D1Database.batch à decisão vencedora; o batch muda o status, liquida adiantamentos pendentes e reconcilia o valor efetivamente descontado antes da resposta. O cache de profissionais é então revalidado, inclusive quando outro dispositivo já concluiu o pagamento. includedRequestIds já constitui o vínculo selado dos serviços, portanto a antiga gravação lateral de version: 9999 foi removida.
🛡️ Módulo 7: Governança do Sistema & Estabilidade (system)
Section titled “🛡️ Módulo 7: Governança do Sistema & Estabilidade (system)”- Auditoria de estabilidade: o risco de atraso usa a primeira visita seguinte da funcionária, e o alerta de funcionária sem tarefas vale só para a equipe de campo, contando visitas aguardando confirmação.
- Arquitetura:
src/features/system/services/ - Serviços Especializados:
StabilityService: Executa varreduras de integridade buscando inconsistências no sistema (ex: tempos de trânsito fisicamente impossíveis, faturas órfãs ou lacunas financeiras).
7. Integração de Comunicação Omnichannel & WhatsApp
Section titled “7. Integração de Comunicação Omnichannel & WhatsApp”O sistema usa a Meta WhatsApp Cloud API como provider principal de conversas e notificações. A fronteira WhatsAppProvider mantém a Evolution como provider secundário/rollback para um número separado e oferece transportMode = META | CHATWOOT para inserir uma instalação self-hosted do Chatwoot sem trocar a interface do produto. O painel só ativa Chatwoot com URL HTTPS, account/inbox IDs e token completos; o token é mascarado no boot. Saída usa a Application API e entrada autenticada converge por /api/whatsapp/chatwoot-webhook; retornar o seletor a Meta restaura o caminho direto. messages.direction (INBOUND/OUTBOUND/INTERNAL) e messages.provider (META/EVOLUTION) identificam a rede; messages.transport (META_DIRECT/CHATWOOT) distingue o caminho usado na Meta, enquanto source permanece apenas como origem visual. Uma resposta manual Chatwoot guarda o source_id Meta (wamid) como chave de recibo quando disponível e conserva chatwoot-out:<id> como chave externa; assim atualizações contendo somente um dos dois IDs convergem sem retry infinito. Se a criação original só trouxe chatwoot:<id>, tanto o primeiro status que contém também o WAMID quanto uma redelivery idempotente de message_created promovem a chave provisória ao identificador Meta canônico, para que um recibo seguinte com somente WAMID continue encontrando a mesma linha. O webhook Meta valida modo/desafio de subscrição, limita o corpo a 1 MiB, compara o HMAC do corpo cru em tempo constante e rejeita JSON inválido. Mensagens, reações, respostas interativas, recibos e smb_message_echoes convergem no pipeline compartilhado. Índices únicos parciais em messages.external_id e messages.wa_message_id fecham a corrida entre reentregas concorrentes; depois do conflito, somente a entrega vencedora prossegue para push, roteamento, liberação de fila e automação, nunca uma reentrega simultânea.
POST /api/whatsapp/chatwoot-control é a única fronteira autorizada a trocar o modo: testa a conta/inbox ao vivo, assegura os custom attributes necessários no Chatwoot (prime_crown_audience, prime_crown_channel_id, prime_crown_request_id, prime_crown_sender), impede ativação com fila pendente e deixa o modo anterior intacto em qualquer falha; USE_META continua disponível mesmo com o NAS offline. A migração 0124 cria chatwoot_conversation_links, chaveada por telefone normalizado + inbox, para persistir contact/conversation IDs e eliminar buscas repetidas (com criação de contact_inbox sob demanda para contatos sem vínculo prévio). A migração 0134 acrescenta uma concessão recuperável por telefone+inbox antes da primeira resolução: Workers simultâneos aguardam o vínculo persistido em vez de criarem contatos/conversas Chatwoot em paralelo; expiração cobre a queda do detentor. Um 404/410 invalida esse cache, resolve novamente a conversa e repete o envio uma única vez. O webhook Chatwoot é fechado quando o modo não está ativo, autentica pelo verify token, limita JSON a 1 MiB e mídia a 16 MiB da mesma origem HTTPS do NAS. Quando Chatwoot entrega um sender/contact superficial sem telefone, o Worker procura o primeiro telefone válido também em conversation.meta.sender e conversation.contact_inbox.contact; assim uma entrada ou resposta humana não recebe 200 e desaparece apenas por variação de payload. Textos outbound e templates manuais carregam prime_crown_context e custom attributes com canal, tarefa, audiência e autor, inclusive quando a fila entrega depois e quando o template reabre a janela de 24 horas; prime_crown_origin distingue o eco de um envio Prime Crown de uma resposta humana escrita no Chatwoot. O template manual recebe uma chave idempotente criada pelo composer e é reservado em messages.external_id antes do provider; a chave só persiste durante a mesma folha aberta no mesmo canal, para que um novo canal ou reopen seja uma nova intenção, enquanto request concorrente/retry da mesma intenção devolve o WAMID/ID Chatwoot original depois da confirmação. Como a conversa física é uma por número/inbox, seus custom attributes são somente um resumo mutável da última saída e não têm poder de encaminhar uma resposta humana para JOB; sem citação validada ou contexto explícito da própria mensagem, o webhook a mantém no DIRECT privado. Mensagens inbound, respostas de agentes (incluindo anexo outbound), citações e recibos usam persistência/idempotência/broadcast já compartilhados pelo chat.
O teste de ativação Chatwoot aceita a resposta 422 idempotente para atributo já existente; rede, token ou permissão insuficiente ao criar qualquer atributo obrigatório rejeitam a ativação, pois não há garantia de proveniência DIRECT/JOB. Com Chatwoot ativo, URL, account, inbox, access token e verify token não podem ser trocados pelo save genérico de Settings: somente o controle verificado pode alterar a conexão, preservando teste ao vivo, preflight autenticado e o gate da fila. Uma resposta manual que cita uma bolha de JOB só volta à equipe se o canal ainda estiver aberto: citação de tarefa bloqueada degrada para DIRECT, exatamente como a entrada Meta, sem ressuscitar uma audiência histórica.
A criação sob demanda de um canal JOB devolve imediatamente a mesma projeção enriquecida do GET /api/channels, inclusive requestLabel calculado de service_requests.start_date_time. Assim a data programada aparece na inserção local sem refresh. O endpoint valida que a tarefa existe, pertence ao cliente informado e já representa um serviço confirmado antes de criar o canal. A lista de participantes enviada nessa abertura é aplicada também ao canal canônico já existente, com insert idempotente; dessa forma um canal antecipado por automação/webhook não fica invisível à equipe alocada quando ela chega aos detalhes. A abertura nunca remove participantes: a reconciliação de atribuição da tarefa continua sendo a única fonte de remoções.
Para canais DIRECT, POST /api/channels delega a resolução a ensureDirectChannel, assegurando unicidade por entidade real: se o identificador informado pertence a um lead que foi mesclado (merged_into_id), o canal do lead canônico sobrevivente é reutilizado em vez de criar uma conversa vazia paralela; se pertence a um cliente com grupo de contatos, o canal compartilhado do grupo é retornado. Além disso, ensureDirectChannel agrega todos os leads irmãos que compartilham o mesmo número de telefone (liveLeadIdsByPhone) e leads mesclados na árvore do contato, reusando qualquer canal existente e impedindo a criação de canais em branco duplicados. Quando um lead é convertido ou atendido como cliente, ensureDirectChannel adota o canal do lead para a entidade cliente, unificando a conversa. No painel de cotações (QuoteConfirmationPanel), a visualização do orçamento é estritamente de leitura (não dispara chamadas de criação prematura de canais em useEffect); a janela de 24h é calculada sobre os canais existentes e, no envio da mensagem de confirmação, qualquer canal direto já existente para o lead, lead canônico ou cliente com mesmo telefone é reutilizado diretamente. Na listagem geral (GET /api/channels), canais pertencentes a leads mesclados são filtrados para evitar duplicatas em branco na caixa de entrada. Da mesma forma, orçamentos (lead_quotes, createLeadQuote) e /api/boot resolvem identidades de leads mesclados e clientes convertidos, garantindo que o nome do contato nunca degrade para “Unknown contact”.
Quando Chatwoot é o transporte, a proveniência imutável de cada saída Prime Crown inclui também o ID da linha local. O webhook autenticado do eco message_created usa esse ID para registrar sent/SERVER_ACK e atualizar a conversa aberta mesmo se a resposta HTTP original tiver expirado depois do aceite remoto. Esse eco remove a fila PENDING/PROCESSING da mesma mensagem; o enfileiramento e o runner também revalidam aceitação imediatamente antes de uma nova chamada externa. Se o eco com WAMID Meta chegar enquanto o POST ainda retorna o ID provisório chatwoot:<id>, a gravação condicional conserva o WAMID: nenhum retorno tardio pode rebaixar a chave usada pelos recibos source-only. A corrida entre timeout HTTP e eco, portanto, não pode transformar um envio já aceito em duplicata ou perder os recibos posteriores. O webhook não confia em atributos de conversa mutáveis para essa associação.
O roteamento WhatsApp preserva a separação que a conversa física única não oferece. DIRECT é privado para Manager/Admin e JOB exige participação do funcionário. Uma resposta continua o último diálogo humano por até 60 minutos; pedido explícito de gerente sempre vence. Quando não há contexto, o sistema pergunta o destino e mantém a mensagem em DIRECT até uma resposta válida. Com várias tarefas abertas, listOpenTeamChannels ordena as opções pela agenda e apresenta cada data/hora separadamente. A migração 0125 acrescenta whatsapp_routing_sessions, que congela por 60 minutos exatamente as opções mostradas, e whatsapp_routing_audit, que registra escolhas do cliente e overrides do Manager. GET/POST /api/whatsapp/routing, restrito a Admin/Manager, alimenta o seletor de destino no chat, suportando tanto overrides manuais (MANAGEMENT, TEAM) quanto retorno imediato a AUTOMATIC, que limpa a sessão. A confirmação de tarefa repete sua data/hora. Entrada ambígua, opção inválida, expiração ou tarefa encerrada retorna ao caminho privado. Uma resposta citada só segue para JOB quando a mensagem original resolve de forma única para uma tarefa aberta do mesmo cliente; citação desconhecida, ambígua, de outro cliente ou de tarefa encerrada vai diretamente para DIRECT, sem recorrer ao contexto ou override de outro JOB. O banner de tarefa explicita o escopo de visibilidade; Chatwoot continua sendo transporte administrativo e nunca substitui o RBAC do Prime Crown.
Texto e mídia livres sempre passam pela janela local de 24 horas na Meta e no Chatwoot. No Evolution, o painel controla enforceSessionWindow: ligado reproduz a retenção da Meta; desligado usa o envio livre oferecido pelo gateway. Consentimento e opt-out permanecem obrigatórios nos três modos. A janela é por número/cliente, não por canal: uma mensagem inbound em DIRECT ou JOB — incluindo cadastros ligados pelo mesmo grupo de contato — libera para PENDING todas as linhas HELD daquela pessoa, sem tocar a fila de outro cliente. Toda saída guarda a linha comercial no próprio messages.business_phone_id, inclusive quando entra como PENDING por atraso anti-ban; o runner reutiliza esse valor para o provider e para ambas as verificações da janela, em vez de herdar a linha atual do painel. Essa promoção transmite para cada chat DIRECT/JOB aberto exatamente a bolha liberada; se o Durable Object falhar, a persistência inbound não falha e a próxima leitura autoritativa reconcilia a UI. O catch-up pós-reconexão seleciona mensagens novas, filas cuja updated_at mudou e timestamps de envio/recibo posteriores ao cursor; assim HELD → PENDING, envio, falha e ticks de uma bolha antiga também se recuperam sem exigir outra mensagem ou reload completo. Se a janela vencer enquanto um atraso anti-ban aguarda, a linha já nasce HELD, sem uma execução inútil do runner; ao drenar uma linha antiga, o runner também confere a janela antes de aplicar novo backoff e transmite held ao chat aberto. HELD não concorre pela entrega, mas uma varredura limitada do runner visita as retenções mais antigas para aplicar o teto global de 24 horas e prazos menores por categoria. A linha vencida vira FAILED por update condicional, atualiza a bolha via Durable Object e alerta a operação; portanto uma resposta do cliente semanas depois não ressuscita uma comunicação obsoleta. O chat a identifica como janela fechada, não como envio agendado. A lista expõe somente um sessionWindowScope de apresentação, nunca aceito como autorização pelo Worker; ele atualiza imediatamente todos os canais DIRECT/JOB e cadastros do grupo, sem transferir mensagem, prévia, ordem ou não lidos. A projeção da conversa interna do funcionário preserva ownerType=EMPLOYEE e omite a janela, para que a trava Meta não afete o canal de gestão. O Hub oferece templates aprovados compatíveis, e o endpoint reconsulta o catálogo Meta para validar identidade, estado, corpo e variáveis sem confiar no fallback do browser. OTP continua a usar verification_code. No inbound Meta/Chatwoot, a deduplicação e a persistência precedem os follow-ups em executionCtx.waitUntil, evitando bloquear a resposta 200. A transição de recibo failed também é um claim condicional: se um ACK concorrente já foi gravado, o erro tardio não retracta a mensagem nem cria uma fila FAILED falsa. Exclusão remota só é oferecida para mensagens outbound Evolution; a ausência dessa capacidade na Meta/Chatwoot nunca vira exclusão local enganosa.
- Fila Anti-Ban (
antiBanPolicy.ts): Aplica delays aleatórios calculados e pequenas variações no texto para prevenir marcação do número como SPAM pela Meta. - Processamento de Webhook (
evolution-webhook.ts): Recebe eventos assíncronos de mensagem enviada, entregue, lida e novas respostas de clientes, inserindo-os diretamente no D1. O destino registado na Evolution éAPP_BASE_URL, nunca a origem do request (localhost empages:devnão pode receber entregas e apagaria o webhook de produção). - Destinatário outbound: o envio resolve o telefone pelo dono do canal (cliente ou lead). Um chat de lead não tem linha em
clients; procurar só lá fazia a resposta da equipe falhar comoMissing WhatsApp number/To unknown. - Killswitch do bot:
whatsAppConfig.enableAiAutomation— único toggle; valor ausente conta como desligado. - Engajamento:
engagementMode=MENU_ONLY(lista de opções) |KEYWORDS(só comengageKeywords) |ALWAYS(IA livre; default se o campo faltar). Menu:menuGreeting+menuItems(até 3 botões). - Failover:
backupInstanceNameno Hub (fallback:EVOLUTION_BACKUP_INSTANCE) no envio de texto. - Hub diagnostics: health (métricas outbound-only + silêncio inbound), test-send, opt-outs, probe E2E dry-run.
- Confirmação de saída:
messages.sent_atregistra a aceitação HTTP pela Evolution;server_ack_até escrito exclusivamente a partir doSERVER_ACKdo WhatsApp. Ausência desse ACK por 5 minutos aparece no painel de falhas como alerta não reenviável, evitando duplicados quando a entrega original está apenas atrasada. - Saúde do gateway (
health.outbound): taxa deSERVER_ACKdas últimas 24 h classificada emOK/DEGRADED/BROKEN. Distingue sessão quebrada de destinatários offline, o quedeliverabilityRate24h(baseada emdelivered_at) não faz. Suspensa quando o inbound estáBROKEN, já que os recibos usam o mesmo webhook. A versão do Baileys não é verificável — a Evolution não a expõe. - Notificação do chat: mensagens de clientes no aplicativo notificam os participantes pelo pipeline canônico de push do endpoint de canais. Não existe relay paralelo para número fixo nem um segundo cliente Meta no frontend; conteúdo do chat permanece nos destinatários autorizados e todo WhatsApp de saída atravessa
WhatsAppProvider. - Lifecycle do painel Evolution: status/QR usam leitura limitada a 12 segundos e reconexão usa mutação limitada a 15 segundos. Leituras seguem latest wins, enquanto o poll periódico cede prioridade ao POST de reconexão e nunca o cancela. Cada conclusão confere seu request ID antes de publicar e o teardown encerra o controller ativo. Rede degradada ou uma resposta tardia não congela loading nem sobrescreve um QR posterior em web, PWA, desktop, Android ou iOS.
- Smart replies: chips no composer via
/api/ai/suggest-repliesquandoenableSmartRepliesestá ativo. - Confirmação e Remarcação Automática de Visitas (
bookingConfirmation.ts): Respostas de clientes (seja via botões Quick Reply da Meta/Evolution com normalização NFD de acentos ou via texto livre conciso como “Confirm”, “Confirmado”, “Reschedule”, “Remarcar”, “Aceitar novo horário”) atualizam atomicamente o status da tarefa no D1 (SCHEDULEDao confirmar,PENDING_REVIEWao solicitar reagendamento). A ação gera log emsystem_logs, emite notificação push para gestores e envia réplica automática em inglês ou português pelo WhatsApp. Visitas emPENDING_REVIEWrecebem destaque visual na grade da agenda (ScheduleEventCard) com card âmbar e badgeReviewpara rápida ação do despacho. - Exibição Contextual de Templates pelo Momento da Tarefa (
templateMoments.ts): O seletor de templates e as ações rápidas filtram e priorizam estritamente os modelos adequados à fase da tarefa (PENDING_BOOKING→booking_confirmation;SCHEDULE_CHANGE→schedule_change;CONFIRMED_UPCOMING→booking_reminder+ campo;IN_PROGRESS→ campo). Modelos de alteração de horário são estritamente ocultados para tarefas já confirmadas sem reagendamento pendente. Gestores contam com alternador para visualizar o catálogo completo sob demanda. Quando a janela de 24h está aberta, chips contextuais na barra de digitação (QuickActionChips) dão acesso em 1 toque ao template correspondente. Ao criar uma nova visita (BookingModal) ou reagendar uma tarefa pelo modal rápido (QuickEditTaskModal), a opção de notificar o cliente via WhatsApp abre a prévia do template correspondente (booking_confirmationouschedule_change) pré-preenchido logo após o salvamento. Além disso, a visão geral de logística da tarefa (ServiceLogistics/ServiceDetailsOverviewTab) disponibiliza botão direto de WhatsApp integrado à folha de templates para os momentos da visita. - Integração Operacional Cotações, Leads e Conversas: Conexão direta entre cotações abertas, lista de leads e o chat. Cards de cotação e o modal
QuoteConfirmationPaneloferecem botão de acesso direto à conversa com o lead. Cotações abertas há mais de 14 dias exibem alerta visual (+14d Expired) e cotações confirmadas no painel “Decided” conectam-se à tarefa gerada no Planner (View Booking). Nos leads, o card exibe cotação ativa com valor monetário e atalho para a nova ferramenta de unificação de leads duplicados (MergeLeadsModal/PATCH /api/atomic/leads?action=merge), que migra mensagens, cotações e canais canônicos. No Chat (ChatInbox), conversas com leads/clientes que possuem cotação aberta exibem o banner contextualQuoteContextBannercom botão de revisão/precificação e, em telas desktop, um painel lateral retrátil (CompactQuoteDetailPanel) com detalhamento completo de itens e preferências.
Cada geração de smart replies usa lock síncrono, token de request e epoch do sheet. Apenas a execução ativa pode publicar sugestões/loading; teardown por fechamento, canal ou sessão invalida a anterior. Falha, resposta vazia e conversa sem histórico usam respostas prontas explicitamente rotuladas em uma região de status, em vez de apresentar conteúdo estático como resultado da IA. A preferência de idioma permanece no request de geração; o fallback fixo conserva a política de cópia inglesa do produto.
8. Camada de Inteligência Artificial (Cloudflare Workers AI & Google Gemini API)
Section titled “8. Camada de Inteligência Artificial (Cloudflare Workers AI & Google Gemini API)”Uso limitado por conta: /api/ai atende todos os perfis e agora tem orçamento por conta: 200 chamadas a cada 10 minutos para administração e gerência, 60 para os demais. O texto enviado tem teto de 50.000 caracteres, e os erros do Gemini não voltam ao usuário.
A inteligência artificial adota uma estratégia híbrida com prioridade estrita ao tier gratuito:
- Política de Execução (Cost-First Routing): Todas as operações, inclusive
stream: truede/api/ai, tentam primeiramente o Cloudflare Workers AI (@cf/meta/llama-3.2-1b-instruct) aproveitando a cota gratuita diária da Cloudflare com custo zero de tokens. Somente em caso de indisponibilidade, esgotamento de cota, resposta vazia ou falha do Workers AI é acionado o fallback automático para o Google Gemini 2.0 Flash (gemini-2.0-flash), protegendo o consumo de tokens faturáveis. - Streaming em Tempo Real (Server-Sent Events): Endpoint
/api/aisuportastream: true; uma resposta Workers AI é adaptada a um evento SSE completo e o fallback Gemini transmite tokens incrementalmente, mantendotext/event-streampara os consumidores. - Polimento e Tradução Automática Bidirecional:
- Equipe/Gestor → Cliente: Mensagens de equipe/gestor redigidas em português são automaticamente polidas e traduzidas para inglês britânico requintado (
en-GB) no backend sem necessidade de clique em botões. O texto original é mantido emcontent, a tradução emtranslations_jsone o WhatsApp do cliente recebe a versão em inglês polida. - Cliente → Equipe/Tarefas: Quando o cliente responde em inglês (via WhatsApp ou portal), o backend traduz automaticamente a mensagem para português brasileiro (
pt-BR) e armazena emtranslations_jsondo canal/grupo da tarefa. Assim, o funcionário ou equipe de campo já lê a instrução diretamente em português ao abrir o aplicativo. - Transcrição e Tradução Automática de Áudios de WhatsApp (
Voice Notes): Áudios recebidos de clientes via WhatsApp são automaticamente transcritos usando Cloudflare Workers AI Whisper (@cf/openai/whisper) com custo zero de tokens e traduzidos parapt-BR. O app exibe a transcrição e a tradução diretamente abaixo do player. - Destaque Visual para Instruções Críticas no Chat: Detecção automática de palavras-chave de acesso e instruções de serviço (chaves, códigos de alarme, portão, animais de estimação, alergias), com badge visual em destaque para a equipe.
- Resumo Operacional da Tarefa (Job Briefing -
/api/channels/summary/:id): Síntese inteligente dos pontos combinados com o cliente em português, exibida em banner expansível no topo do chat da tarefa. Falhas de IA ou provider retornam um contrato genérico ao chat e são registradas de forma sanitizada emsystem_logs, sem expor tokens ou detalhes internos. - Endpoint dedicado (
/api/ai/polish-message): Refinamento sob demanda com padrão luxo (en-GB / pt-BR).
- Equipe/Gestor → Cliente: Mensagens de equipe/gestor redigidas em português são automaticamente polidas e traduzidas para inglês britânico requintado (
- Sugestões Inteligentes de Atendimento (
/api/ai/suggest-replies): Geração de 3 respostas rápidas (chips) contextuais multilíngues (en-GB / pt-BR). - Análise de Incidentes: Diagnóstico imediato de atritos com recomendações de compensação e ação.
- Roteamento de Crise: Sugestões inteligentes para resolução de conflitos de alocação de equipes.
O transporte não-streaming central do AIService limita cada POST autenticado a 30 segundos e combina o cancelamento do consumidor, cobrindo as mesmas funções em desktop, PWA e shells nativos. A estratégia geográfica em Leads possui lock síncrono, controller e epoch por identidade: toques no mesmo frame não duplicam geração, troca de conta/desmontagem aborta o pedido e uma resposta antiga não restaura estratégia, toast ou loading. Uma nova análise limpa o resultado anterior para não apresentar inteligência desatualizada como se fosse atual.
9. Segurança, Autenticação, Modo Offline e Telemetria
Section titled “9. Segurança, Autenticação, Modo Offline e Telemetria”- JWT Tokens: Autenticação stateless via tokens JWT emitidos no login com expiração configurada.
- Restauração sem waterfall anônimo:
/api/auth/mesinaliza somente a disponibilidade do cookie HttpOnly de refresh. Ausência confirmada abre a superfície de login sem um POST adicional destinado a401; presença ou Worker antigo preserva validação e rotação normais. O valor da credencial nunca é exposto, e o chunk de login continua sendo carregado em paralelo. - Telefone E.164: Identificador de login padronizado em formato E.164 (
+44...). - Links de acesso só como hash: redefinição de senha, magic link e link de acesso gravam o SHA-256 do token em
password_reset_tokens; a limpeza delogin_attemptsfeita pelo login preserva a janela de uma hora dos limites de magic link e redefinição. - Feeds de agenda seguem o acesso: cada atualização do feed ICS confere se quem assinou ainda tem acesso e, para a agenda de outra pessoa, se ainda é gerente.
- Fim do acesso encerra as notificações: logout remoto, bloqueio, pedido de exclusão e exclusão do cadastro removem todos os aparelhos da pessoa (
forgetPushDevices), e o registro de aparelho exige sessão válida (getSessionUser). - Segredo das rotinas: o Worker
chat-doautentica as chamadas agendadas comCRON_SECRET(isCronCaller), comJWT_SECRETaceito só até o novo segredo estar configurado. - Suporte a Impersonation: Administradores e Gerentes podem alternar para a visão do Cliente ou da Funcionária de forma isolada e segura.
- Contrato offline honesto: somente mensagens de chat possuem fila persistente e reconciliável em IndexedDB. Fotos/evidências exigem conexão e só entram no pedido depois que o R2 devolve a URL; em falha, a interface preserva a tela e pede nova seleção, sem guardar payload/base64 de negócio em
localStorage, criar objeto R2 órfão ou anunciar sucesso antecipado. Mutações de tarefa também não usam fila local sem confirmação autoritativa. - Telemetria de Core Web Vitals (
webVitals.ts): Medição passiva e sanitizada de LCP, CLS e INP enviada ao log do sistema para monitoramento contínuo da performance em campo.
10. Guia de Manutenção, Testes e Protocolo de Deploy
Section titled “10. Guia de Manutenção, Testes e Protocolo de Deploy”⚠️ Regra de Ouro da Alteração de Banco de Dados:
Section titled “⚠️ Regra de Ouro da Alteração de Banco de Dados:”Sempre que o esquema do banco for alterado, você DEVE atualizar 3 arquivos obrigatoriamente:
db/migrations/NNNN_*.sql(Script delta de produção).db/schema.sql(Baseline para ambiente local/desenvolvimento).functions/api/db/schema.ts(Definição de tipos no Drizzle ORM).
Comando de Validação de Código e Integridade:
Section titled “Comando de Validação de Código e Integridade:”npm run typecheck # Valida tipos no src e nas funções Cloudflarenpm run lint # Executa o Biome Linter com auditoria de a11ynpm run deadcode # Scanner de código morto e exports não utilizados (knip)npm run security:audit # Auditoria de segurança tolerante a ambiente offline/sandboxnpm run budget # Valida o orçamento de bundle gzip do first-loadnpm run check # Executa a suíte de integridade completanpm test # Roda toda a suíte de testes do VitestOtimizações de Performance, Boot e Paginação (v5.7):
Section titled “Otimizações de Performance, Boot e Paginação (v5.7):”- Boot Payloads Enxutos (
/api/boot): Consultas de histórico cumulativo (payrollRuns,cashReserveLedger,systemLogs) possuem limites protetivos e ordenação decrescente para garantir tempos de inicialização inferiores a 200ms em redes móveis. - Paginação Cliente e Renderização Progressiva: Tabelas do módulo de histórico (
HistoryTable,InvoiceHistoryTable,PaymentHistoryTable,AuditFlaggedTable) utilizam paginação estruturada (50 itens por página). Feeds de telemetria (GlobalActivityLog,SystemErrorsLog) utilizam renderização progressiva com carregamento sob demanda para prevenir engasgos no DOM móvel.
Processo de Deploy:
Section titled “Processo de Deploy:”Push para a branch main ativa o GitHub Actions de deploy ou o deploy pode ser feito via terminal:
npx wrangler pages deploy dist --project-name prime-crownDurante logout, user=null é publicado com o carregador global desativado; a tela de login substitui o conteúdo autenticado no próximo commit. Na mesma fronteira síncrona, entidades, tarefas, faturas, folha, drafts de configuração e intenções de navegação dos stores Zustand são zerados; um bridge nativo persistente ou uma navegação que falhe não pode expor a memória da conta anterior à próxima sessão. No runtime nativo, a leitura do token local tem limite de 300 ms e a revogação server-side começa sem aguardar unregister/Firebase, que continua em paralelo; uma ponte travada não pode mais fazer a saída depender de fechar o aplicativo. A cópia HttpOnly do token, emitida apenas após registro autenticado e apagada no mesmo logout, preserva a remoção por dispositivo mesmo quando esse limite vence. A limpeza preserva o escopo por dispositivo.
Uma barreira local booleana e sem identidade é persistida antes de user=null. Se o cookie HttpOnly não puder ser revogado por falta de rede, o próximo boot verifica essa barreira antes de /api/auth/me, repete o logout e mantém o aplicativo desautenticado enquanto estiver offline. Revogação confirmada ou qualquer novo login confirmado remove a barreira. Cada instalação recebe também uma família opaca de refresh token, estável entre rotações: logout e impersonação revogam essa família inteira, alcançando o token novo de um refresh que começou antes do logout, mas nunca os outros dispositivos da mesma conta. A migração usa a hash dos tokens legados como família para preservar essa garantia já na primeira rotação. Assim force-close, reload e reinício não restauram uma sessão que o usuário já decidiu encerrar.
Na restauração comum, uma resposta 401 de /api/auth/me inicia o chunk da tela de login e a leitura cacheável de /api/public/config em paralelo à tentativa de refresh. AuthContext e React.lazy compartilham o mesmo loader; quando o refresh é recusado, o formulário já pode substituir o splash sem uma segunda cascata de rede. Somente o chunk é aguardado: configuração pública lenta ou indisponível não segura a interface, e o controller tenta novamente pelo fluxo normal. Refresh válido conserva o fluxo autenticado, e uma falha especulativa limpa sua promise para o recovery normal poder tentar novamente. O ganho vale para navegador, PWA e WebViews Android/iOS sem incluir a tela desconectada no bundle inicial de sessões válidas.
O provider social nativo usa um inicializador serial por chave de configuração. Login/Cadastro reutilizam a mesma promise; mudanças de Web Client ID ou runtime aguardam a inicialização anterior, falhas permitem retry e cada toque Google/Apple aguarda explicitamente a configuração atual. Em uma instalação sem cache, a ação do primeiro toque compartilha a leitura deduplicada de /api/public/config e passa o Web Client ID resolvido diretamente à inicialização, sem esperar outro render. Isso impede inicializações globais fora de ordem e elimina a dependência de um efeito eager já ter terminado no primeiro toque.
Uploads operacionais aceitam AbortSignal e ficam vinculados a usuário, cliente, escopo e job. Evidence zones e checklist abortam requests ao trocar proprietário/desmontar, recusam callbacks de epochs antigas e, no checklist, projetam o resultado sobre items/onUpdate atuais. Uma câmera, picker ou rede lenta não consegue anexar a foto à sessão ou tarefa seguinte.
O mesmo contrato cobre anexos do chat. CloudClient.postForm propaga cancelamento externo por refresh/retry/fetch; ServiceChat vincula upload e listagem agendada a usuário+canal, aborta no teardown e recusa callback de câmera, envio, agendamento, toast ou loading de outro proprietário. Fotos, documentos e voz não atravessam uma troca rápida de conversa ou conta.
O histórico da Inbox expõe prontidão combinada do cache IndexedDB por usuário e da fonte push do servidor. A interface não anuncia vazio enquanto alguma fonte ainda carrega nem depois de uma falha; mantém o snapshot existente, apresenta alerta persistente e retry. Estado offline é encerrado como indisponibilidade explícita, e owner + sequência da tentativa protegem dados e status contra respostas tardias de outra sessão em todos os runtimes.
As ações de leitura individual e em lote são otimistas, mas promovem recusas HTTP de aplicação e aguardam confirmação do Worker. Locks no mesmo frame bloqueiam toques repetidos e alimentam disabled/aria-busy/loading dos componentes compartilhados. O rollback usa snapshot por fonte, owner da mutação e epoch da sessão; por isso uma falha antiga não desfaz uma leitura posterior nem interfere após logout ou troca de conta.
Abrir um pedido ou canal também resolve suas notificações pelo mesmo contrato. IDs push correspondentes reutilizam markAsRead; itens apenas locais atualizam o IndexedDB sem chamada remota. Refs mantêm snapshots atuais sem tornar o callback instável, evitando ciclos em efeitos de detalhes/chat e eliminando o antigo catch silencioso desse caminho automático.
O service worker trata leitura pela bandeja como duas confirmações independentes: canal e linhas de notification_history. A mensagem CHANNEL_READ contém channelRead, somente notificationIds confirmados e failedNotificationIds; hooks zeram apenas o estado aceito e reconciliam falhas. A ação explícita recria um banner persistente com Mark as read quando houver recusa parcial/total, mantendo badge e retry honestos no Android/PWA e convergência ao abrir iOS/web/desktop.
O caminho FCM Android aplica a mesma regra fora da WebView. NativeNotificationActions centraliza cookie, timeouts, status HTTP e confirmação JSON; MarkReadReceiver limpa a thread somente após sucesso integral e ReplyReceiver não confunde envio confirmado com leitura confirmada. Falha mantém o stack e oferece retry no notification shade. Antes de desenhar um payload, PrimeCrownMessagingService compara seu recipientUserId ao dono ativo serializado em Preferences; ausência ou divergência falha fechada, mesmo se a WebView ainda não iniciou. O dono viaja também nas ações Reply, Mark as read e dismiss, sendo conferido antes da rede e depois de sua resposta para que broadcast ou HTTP antigo não redesenhe a bandeja da conta seguinte. Cada toque — corpo da conversa, resumo agrupado e alerta operacional — acrescenta a prova somente ao App Link da origem oficial; o bridge e a camada React recusam a URL antes de guardá-la ou navegar se o usuário não coincidir. No service worker, as mesmas ações consultam /api/auth/me (com refresh único se necessário) e exigem que a sessão do cookie ainda pertença ao recipientUserId do banner antes de mutar ou abrir a conversa. Respostas diretas carregam uma chave externalId imutável pela ação: redelivery/replay do mesmo gesto no Android ou Chrome devolve a mensagem original sem criar segundo registro, push ou entrega WhatsApp. Cada banner redesenhado recebe uma chave nova para a próxima intenção, e o Android persiste as chaves já mostradas para que o próprio MessagingStyle não repita “You” após uma restauração. Logout, revogação remota e logout offline limpam todos os banners/badge do service worker, cancelam o tray + removem a pilha persistida no Android e removem alertas APNs já entregues no iOS antes da navegação; remover o token remoto segue sem bloquear essa fronteira de privacidade. Intenções de App Link pendentes também são removidas durante a limpeza de sessão, impedindo que um link recebido antes da autenticação seja reaplicado para a conta seguinte. A compilação Java real continua incluída no gate de alteração nativa.
No Android, a mesma limpeza remove atalhos dinâmicos de Conversations para as threads persistidas, além do tray e da pilha: nome, avatar e deep link de uma conta anterior não permanecem visíveis no launcher.
O banner global possui contrato de leitura separado do valor: ready, loading, error, owner e request sequence. O shell nunca interpreta falha/offline como comunicado inativo; exibe status inicial ou alerta persistente com retry, preservando eventual snapshot ativo. Troca de identidade publica o default antes de buscar, e foreground reconciliado impede tanto vazamento entre contas quanto aviso crítico obsoleto nos quatro runtimes.
O estado do compositor é particionado por identidade+canal. conversationDrafts preserva texto em memória por conversa; reply, menus, sugestões e prévia de voz são descartados na troca. IA, câmera e recorder usam epoch do compositor. O start de voz valida propriedade depois da permissão e fecha apenas sua própria instância quando fica obsoleto, sem interferir numa gravação mais nova.
Saltos para citação registram e cancelam ambos os animation frames, revalidando o epoch antes de prepend, scroll e destaque. Cancelamento de agendado e exclusão também capturam usuário+canal; rollback e toast tardios não atingem a conversa seguinte.
O simulador administrativo do bot WhatsApp foi removido; o teste de envio real (Send test) permanece.
Teste, ativação e retorno para Meta no painel Chatwoot propagam AbortSignal pelo cliente compartilhado e ficam vinculados ao epoch da superfície. Desmontagem cancela request e retries; conclusão antiga não altera configuração, resultado ou loading da próxima tela. Copiar a URL possui lock síncrono, alvo de 44 px e revalida o lifecycle depois do provider nativo/web; falha apresenta orientação manual, e o feedback usa timeout substituível com cleanup. Isso evita toque duplo, callbacks e timers acumulados em desktop, PWA e WebViews.
No painel de confirmação de orçamento (QuoteConfirmationPanel), a composição rápida de mensagem WhatsApp respeita a janela de 24 horas da Meta para o canal direto do lead (widestSessionWindow). Quando a janela estiver fechada (!isWindowOpen), a opção de texto livre (“Clear & write my own”) é ocultada, a mensagem é obrigatoriamente vinculada ao template aprovado pela Meta, o campo de texto passa a ser somente leitura (readOnly) e um selo informativo (“24h window closed · Template required”) é apresentado. Quando a janela estiver aberta, o botão “Clear & write my own” fica disponível juntamente com o indicador de tempo restante da sessão, permitindo edições manuais sem violar as políticas de envio da Meta.