Ciclo de Vida da Limpeza & Telemetria GPS

Ciclo de Vida da Limpeza & Telemetria em Campo

O módulo de Operações de Campo (Field Operations) gerencia a execução em tempo real das limpezas residenciais pela equipe, capturando pontos de check-in/out geolocalizados e acompanhando a realização dos checklists.

---

🔄 1. Diagrama de Estado da Limpeza

stateDiagram-v2
    [*] --> REQUESTED: Solicitação de Orçamento
    REQUESTED --> PENDING: Validação de Disponibilidade
    PENDING --> CONFIRMED: Funcionária Alocada
    
    state CONFIRMED {
        [*] --> READY: Aguardando data/hora
        READY --> IN_TRANSIT: Deslocamento para imóvel
    }
    
    CONFIRMED --> IN_PROGRESS: Check-in por Telemetria GPS (raio de 200m)
    IN_PROGRESS --> COMPLETED: Check-out por Telemetria GPS + Checklist
    
    COMPLETED --> INVOICED: Emissão da Fatura Fiscal (Billing)
    INVOICED --> PAID: Quitação do Pagamento
    
    CONFIRMED --> CANCELLED: Cancelamento (Politica de Cancelamento)
    PENDING --> CANCELLED: Cancelamento sem taxa

---

📍 2. Telemetria GPS & Validação Geográfica

Para evitar fraude de horários ou check-ins fora do local do serviço, a classe ServiceGeoAction.tsx executa a validação por coordenadas:

A leitura periódica de proximidade pertence ao ciclo atual de tela, visita e foreground. O ID da visita é parte explícita de cada leitura: pausa nativa, aba oculta, troca de atendimento ou desmontagem invalida imediatamente o voo; uma coordenada que resolva depois disso não altera distância, erro, permissão nem dispara auto-start. A troca também limpa distância, falha e confirmação automática anteriores antes do novo fix, inclusive quando duas visitas compartilham o mesmo endereço. Ao retornar, uma nova leitura é permitida mesmo que a chamada antiga ainda esteja terminando na bridge. Durante um mesmo ciclo ativo existe no máximo uma consulta, evitando sobreposição de GPS no Android, iOS, PWA e desktop.

As confirmações manuais também possuem locks síncronos. Begin Mission permanece em loading e a folha não pode ser fechada enquanto obtém o ponto; dois toques no mesmo frame não iniciam duas capturas nem dois clock-ins. Quando GPS ou override termina, a própria preflight se fecha antes de publicar o clock-in, sem depender de o modal/painel hospedeiro fornecer um callback de fechamento. Se o app entra em background, a aba é ocultada ou o alvo muda durante a captura imediata, o resultado tardio é descartado sem executar o fallback de coordenada zero; o lock visual é liberado para uma tentativa explícita ao retornar. A conclusão do turno trava antes do preparo assíncrono de evidências, ignora a continuação após teardown e entrega no máximo uma finalização à captura GPS. O lock pertence à visita e é reaberto somente quando ID/check-in/check-out muda.

sequenceDiagram
    autonumber
    actor Staff as Funcionária (App)
    participant UI as Componente ServiceGeoAction
    participant Geo as GPS do Dispositivo (HTML5/Capacitor)
    participant API as Edge API (/api/atomic/requests)
    participant D1 as Cloudflare D1 DB

    Staff->>UI: Clica em "Iniciar Limpeza" (Check-in)
    UI->>Geo: Solicita coordenadas atuais (lat, lng)
    Geo-->>UI: Retorna lat, lng e precisão
    UI->>UI: Calcula distância Haversine em relação ao imóvel
    alt Distância <= 200 metros
        UI->>API: POST /api/atomic/requests/:id (telemetry_json, status: IN_PROGRESS)
        API->>D1: UPDATE service_requests
        D1-->>API: OK
        API-->>UI: Check-in confirmado!
    else Distância > 200 metros
        UI-->>Staff: Alerta: "Você deve estar no imóvel para iniciar a limpeza"
    end

---

📋 3. Checklists Operacionais & Registros de Foto

• Checklists Personalizados: Cada tipo de serviço (ex: Deep Cleaning, Regular Cleaning, End of Tenancy) possui uma lista de tarefas.
• Relatório de Inspeção: A funcionária marca os itens concluídos e pode enviar fotos diretamente para o armazenamento do Cloudflare R2 via /api/upload.

Avaliações cinco estrelas podem receber uma sugestão curta por IA. Regenerar cancela a geração anterior; Review on Google só é habilitado quando o texto está pronto e permanece bloqueado enquanto geração ou persistência estiverem em curso. O aplicativo primeiro confirma a cópia pelo provider de clipboard do runtime e somente então registra a avaliação e abre o Google Reviews, evitando conteúdo vazio, janelas externas duplicadas ou sucesso falso no Android, iOS, PWA e desktop. O seletor de estrelas expõe nome e estado para TalkBack, VoiceOver e teclado, preserva alvos mínimos de toque e usa os mesmos campos e botões canônicos das demais superfícies.

Uploads de evidência e fotos do checklist pertencem à combinação usuário, cliente, escopo e job ativa. Trocar de conta, serviço ou desmontar a tela invalida a conclusão e aborta o fetch; o checklist aplica a URL somente sobre a lista mais recente e ignora uma linha removida enquanto câmera ou rede estavam abertas. Assim um retorno tardio do picker Android/iOS ou do input PWA/desktop não anexa mídia à tarefa seguinte. Na restauração Android após recriação da WebView, cancelamento/falha apaga o destino persistido e uma foto que não encontra sua superfície expira em cinco minutos, evitando que contexto ou arquivo órfão atravesse uma captura futura.

A análise de um incidente é propriedade de IncidentItem; useIncidentReporting mantém apenas formulário e despacho. Fechar ou trocar a ficha aborta a chamada de IA em voo, e um resultado só aparece enquanto seu item original continua ativo.

O protocolo de recuperação de uma avaliação baixa usa o mesmo ciclo de vida antes de persistir o rascunho no chat. O painel bloqueia ativações repetidas de forma síncrona, cancela a geração ao trocar de atendimento ou fechar a tela e revalida a propriedade da operação antes do envio e do feedback de conclusão. Se a navegação acontecer depois do início da persistência, o id capturado mantém a mensagem no serviço original.

O envio da avaliação do cliente não usa atraso cosmético nem confirma uma mutação fire-and-forget. Ele inicia a gravação atômica com a versão atual, bloqueia um segundo toque no mesmo frame, aguarda a resposta do backend e trata rejeições antes de anunciar sucesso. Trocar de atendimento ou desmontar a tela invalida feedback tardio. No atalho de cinco estrelas, a página do Google ainda é aberta dentro da ativação original para evitar bloqueio de popup, enquanto a promessa de persistência permanece observada e pode informar falha sem produzir sucesso falso.

Diagnósticos de continuidade cancelam a análise anterior e limpam o insight quando muda o conflito, cliente ou equipe comparada. A análise recebe métricas agregadas do histórico real — visitas concluídas, média de avaliações e experiência anterior com cada profissional — e deve distinguir evidência de inferência. O placeholder useFleetOptimizer e seu banner vazio foram removidos: não havia acionamento, compartilhamento de estado ou resultado visível, embora o quadro ainda carregasse o módulo de IA.

O radar de sentimento cancela a operação ao trocar cliente ou histórico, limpa o resultado anterior enquanto recalcula e limita o contexto às 20 avaliações mais recentes, com até 1.000 caracteres cada. Resumo, índice de 0–100 e três palavras-chave são validados antes da renderização; uma resposta inválida ou falha de rede produz alerta acessível e botão de nova tentativa.

Alertas de estagnação transportam o clientId completo, inclusive quando contém hífens ou é UUID. A ação de retenção cancela uma geração anterior, fundamenta o rascunho em métricas agregadas do histórico e o exibe antes de copiar. O botão Copy message produz uma nova ativação do usuário, necessária para clipboard confiável no Safari/PWA e coerente com Android, iOS e desktop.

O AI Rescue de uma ausência somente considera profissionais ativas, fora de licença e sem choque no horário. Respostas anteriores são canceladas e o plano precisa conter exatamente a tarefa original e uma profissional elegível. Uma folha adaptativa apresenta visita, substituta e justificativa para revisão humana; confirmar revalida versão/status do atendimento e disponibilidade atual. A IA não pode alterar o horário nesse fluxo — reschedule continua separado e manual.

---

🔑 4. Custódia & Rastreamento Seguro de Chaves (Key Custody Tracker)

O inventário real vive em key_tags e cada cadastro, retirada e devolução gera um evento imutável em key_custody_records. Triggers D1 escrevem a auditoria no mesmo statement da transição: não existe sucesso de custódia sem histórico correspondente. O endpoint autenticado /api/field/key-custody aceita somente ADMIN/MANAGER, valida cliente e profissional ativa e usa status + version como precondição; uma ação simultânea ou tela desatualizada recebe 409 e precisa reler o estado. Leituras têm teto de 12 segundos e mutações de 15 segundos. Cadastro e transferência compartilham lock síncrono, cancelamento e epoch da identidade; sair da tela ou trocar de conta aborta o transporte, limpa imediatamente inventário/histórico sensíveis e impede resposta ou toast tardio. Enquanto uma mutação está ativa, refresh, cadastro, seleção de responsável e todas as transferências refletem indisponibilidade na interface.

O Supply Hub mantém concorrência por cliente em vez de um loading global: conjuntos independentes acompanham auditoria e notificação, então duas propriedades podem progredir sem esconder o estado uma da outra. Cada auditoria usa transporte autenticado limitado a 30 segundos, AbortSignal e validação estrita de riskLevel, resumo e lembrete. A chave do single-flight inclui usuário + cliente; troca de conta aborta análises, limpa insights e invalida qualquer conclusão de chat/toast/loading da identidade anterior. Falha de IA não cria card vazio e falha de clipboard não vira rejeição não tratada.

KeyCustodyPanel consome esse contrato em navegador, PWA e shells Android/iOS. Leituras usam AbortSignal, mutações possuem lock síncrono e a interface só altera o inventário após resposta autoritativa. Telefones recebem cards com alvos de 44 px; desktop recebe tabela rolável e ambas as apresentações exibem a mesma atividade recente. O breakpoint compartilhado monta somente cards ou tabela, evitando duplicar todo o inventário e suas ações fora da tela. Toolbar, KPIs, campos, estados vazios, badges e botões usam os primitives oficiais do sistema. O responsável pela retirada precisa ser escolhido explicitamente; a interface não preseleciona a primeira pessoa ativa. Nenhuma tag de demonstração ou transferência apenas em memória é permitida.

---

🗺️ 5. Otimizador de Rotas TfL de Londres (London Transit Route Optimizer)

Para maximizar a produtividade e pontualidade em Londres, o LondonRouteOptimizerService.ts calcula o menor tempo de trânsito entre múltiplos agendamentos do dia:

• Heurística de Vizinho Mais Próximo: Agrupa visitas em códigos postais contíguos (ex: W8 -> SW3 -> SW7) reduzindo até 45 minutos diários de metrô/ônibus.
• Estimador de Trânsito TfL: Pondera fator urbano londrino de 1.35x sobre distâncias lineares e tempo de acesso às estações.

---

🏰 6. Manual da Residência & Cuidados com Superfícies Nobres (Luxury Household Handbook)

Em propriedades de luxo, o HouseholdHandbookService.ts centraliza as diretrizes de preservação e conforto da residência:

• Superfícies Sensíveis: Regras estritas para mármore Carrara, granitos e pisos nobres, alertando sobre produtos proibidos (ácidos/vinagre) e técnicas recomendadas.
• Segurança de Pets: Registro de cães e gatos com instruções de manejo e restrições de portas e portões.
• Rouparia & Conforto: Orientações de hotelaria de luxo para troca e dobra de lençóis de algodão egípcio e aromatização de ambientes.

---

🏖️ 7. Gestor de Férias & Pausa Temporária de Contratos (Holiday Suspension Manager)

O preview de HolidaySuspensionService.ts e o endpoint /api/scheduling/holiday-suspension pausam atendimentos de clientes em viagem:

• Janela de Férias: Seleção de datas de início e retorno.
• Suspensão Atômica: Um único UPDATE cancela somente visitas PENDING, PENDING_REVIEW ou SCHEDULED do período com motivo CLIENT_HOLIDAY; uma falha reverte o statement inteiro.
• Retry Idempotente: holiday_suspensions guarda o UUID e o resultado. Se Android/iOS/PWA perderem a resposta, repetir a mesma intenção não incrementa versões nem altera finanças novamente.
• Consistência Financeira: price e VAT faturáveis passam a zero, enquanto originalPrice e originalVatAmount preservam o valor contratado para auditoria e eventual restauração.
• Cálculo de Capacidade: Apura instantaneamente as horas de equipe liberadas para alocação em demandas avulsas e Deep Cleans.
• Padrão Visual Compartilhado: modal claro com IconBadge, CFInput e Button, layout de datas em uma coluna nos telefones e duas no desktop, métricas responsivas, safe areas e lifecycle modal comum às três plataformas.