Ciclo de Vida da Limpeza & Telemetria GPS
Ciclo de Vida da Limpeza & Telemetria em Campo
Section titled “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.
O check-in só fica disponível a partir do dia agendado, pelo horário de Londres. O gerente ainda pode registrar uma finalização completa pelo fluxo Finish visit. Para um início por engano, Admin → Desfazer check-in permite revisar e confirmar a volta de Em andamento para Agendada. As marcações ativas da visita e da equipe são limpas na mesma gravação, e a mudança fica na auditoria. Vínculos financeiros protegidos bloqueiam a reversão.
Reagendamento, cancelamento, reversão, aprovação e recusa publicam primeiro um snapshot otimista e persistem fora do atualizador de estado. Tanto a visita principal quanto cada visita futura de uma série recebem sua própria tentativa; uma falha só reverte a versão otimista que ela originou, sem desfazer uma edição mais recente. Isso evita duplicação de gravação/auditoria quando React ou Zustand reexecutam um updater.
🔄 1. Diagrama de Estado da Limpeza
Section titled “🔄 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
Estado actual — fechamento pelo escritório. Finish visit salva equipe, horas e registros de execução em uma única gravação DONE, inclusive quando a visita ainda está PENDING ou SCHEDULED e o trabalho ocorreu sem registrar alocação ou clock-in (src/shared/validTransitions.ts). Só admin/manager faz esse salto; a funcionária continua concluindo apenas a partir de IN_PROGRESS (trava por papel em POST /atomic/requests). Se o servidor recusar, o toast mostra o motivo que ele devolveu.
📍 2. Telemetria GPS & Validação Geográfica
Section titled “📍 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.
O mesmo critério vale para o estado de autorização: ao voltar das configurações nativas ou concluir um pedido explícito, a resposta mais recente vence. Uma consulta anterior ainda pendente na bridge não pode reexibir uma permissão já alterada pela pessoa usuária.
O rastreamento de equipe envia somente o fix validado (coordenadas, precisão e timestamp do GPS), sem alterar o cadastro da profissional. O servidor conserva a posição com timestamp mais recente, portanto uma solicitação atrasada por rede não faz o mapa voltar a um ponto anterior.
O servidor faz a segunda medição. A validação no aparelho pode ser enganada por uma localização falsa, então POST /atomic/requests, no clock-in da funcionária (SCHEDULED → IN_PROGRESS), mede a distância entre o ponto recebido e as coordenadas da própria visita — address_snapshot_json, senão o endereço salvo em selected_address_id — contra allocationRules.geofenceRadiusMeters (padrão 200 m), descontando a precisão informada pelo GPS (no máximo 500 m) (functions/api/field/checkInDistance.ts). O resultado fica gravado no próprio checkIn como serverDistanceMeters e outOfRadius. Fora do raio não bloqueia o check-in (GPS dentro de casa costuma errar uma rua): grava CHECK_IN_OUT_OF_RADIUS em system_logs, o evento de check-in no Activity Log aparece em âmbar como Off-site com a distância, e o histórico mostra Off-site em vez de Verified. Sem coordenadas da visita não há veredito.
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.
Aviso de atraso ao cliente. Uma visita de hoje, SCHEDULED e sem check-in 15 minutos depois do início dispara o push “Not clocked in” ao escritório e à equipe (alertLateArrivals); o da equipe abre a própria visita, onde o bloco de check-in (ServiceGeoAction) é o primeiro dos detalhes: fazer o clock-in esquecido ou avisar o cliente. Quando uma colega da mesma visita já fez o check-in, as outras continuam a receber o push para fazer o check-in, sem a ação de avisar o cliente, e o servidor recusa o aviso delas. O aviso do escritório abre a visita com a última localização do telefone de quem não fez o check-in (lastKnownLocation, só o gerente, fora do texto do push): avisar o cliente ou falar com essa funcionária. No alerta Running late dos detalhes da visita (IntelligenceSummary, só escritório) o botão Remind to clock in manda um push a cada cleaner da visita que ainda não fez o check-in (POST /api/field/checkin-reminder, ADMIN/MANAGER; Clock in · Running late, este só enquanto ninguém entrou); o link é próprio (checkinReminderUrl), então o alerta automático de 15 min continua saindo uma vez; nada vai ao cliente. Do mesmo jeito, numa visita IN_PROGRESS em que alguém continua com entrada registrada depois das horas acordadas mais a folga do lembrete (checkoutReminderAt, contado do check-in da visita), o cartão mostra Over its hours com Remind to clock out: push a cada cleaner ainda dentro (ownClockState = ON_SITE; POST /api/field/checkout-reminder, ADMIN/MANAGER; Clock out · Need more time), num link próprio (officeCheckoutReminderUrl) para o lembrete automático de check-out ainda sair uma vez; não muda pagamento nem fala com o cliente. Se a localização já estiver permitida, o telefone grava onde estava quando o aviso de check-in ou de check-out chegou (notice_locations); é esse ponto que o escritório lê. O PWA não consulta o GPS sem uma janela pedindo. O ponto gravado é o do aviso de check-in ou de check-out (notice_locations) e o do check-in e do check-out de verdade (crew_clocks). A janela de entrada/saída e a do aviso de atraso continuam a ler a posição enquanto estão abertas. A entrada e a saída de cada funcionária ficam em crew_clocks, a primeira vez, com o ponto dela; o check-in da visita continua a ser o da primeira a chegar. A folha continua a pagar as horas acordadas (staffWorkHours); esses horários não mudam o que se paga e ficam para comparar depois com as horas pagas. Quinze minutos depois do check-in dessa funcionária mais as horas acordadas dela, se ela ainda não fez o check-out, um push pergunta se ela esqueceu (alertForgottenCheckouts). Avisar o escritório que o tempo não bastou não fala com o cliente; o escritório é quem pode oferecer mais horas. O aviso de atraso fica liberado no dia em qualquer horário antes do check-in tanto para a funcionária quanto para o gerente (isLateArrival, src/shared/lateArrival.ts) e o botão Notify client aparece ao lado do Clock in no cartão da próxima visita (NextVisitCard) e nos detalhes da visita (ServiceGeoAction, VisitHeaderActions e PlannerContextMenu). As opções na janela de atraso são 15 min, 30 min ou personalizado (com ajuste de minutos), com o horário de chegada previsto (lateNoticeArrivalMs); chegar dentro da janela é estar no horário e não gasta mensagem paga da Meta. O servidor recusa o mesmo caso (409 em /api/channels/transitNotice, antes de qualquer envio) e bloqueia o aviso após o check-in. O envio da cleaner (POST /api/channels/transitNotice como EMPLOYEE) verifica a janela de 24 h do WhatsApp: se a janela estiver aberta, a mensagem sai direto para o cliente no WhatsApp assinada pela cleaner (_Team_ — Nome:); se a janela estiver fechada, a mesma mensagem fica retida (HELD) como nota interna para o envio do manager (via template aprovado visit_on_the_way ou WhatsApp Business). O texto (lateNoticeClientText) é escrito de acordo com a assinatura inicial e é exibido na prévia com a linha de assinatura, sem permitir edição do texto, mantendo a personalização no tempo de atraso. O aviso nunca abre uma janela sobre outra: dentro da folha Start shift ou dos detalhes, o painel (TransitNoticePanel) toma o lugar do cartão de check-in, com Voltar; sozinho (cartão do dashboard, Live Board) é um AdaptiveBottomSheet compacto.
Tempo que não bastou. Quinze minutos depois do check-in da faxineira mais as horas combinadas para ela, sem check-out, um push pergunta se esqueceu (alertForgottenCheckouts). Na visita, Tell the office (MoreTimeOffer) abre uma janela com a mensagem já escrita na língua dela — cliente, referência e serviço, morada, hora do check-in, link /task/ e o pedido de mais horas — que ela edita antes de enviar. O envio (POST /api/field/more-time, só depois das horas + 15 min) grava a mensagem como dela no próprio DIRECT com o escritório (Manager), uma vez por visita (id fixo MORE-TIME-<visita>-<faxineira>), e o escritório recebe o push normal dessa conversa; antes era só um push ao escritório. Nunca chega ao cliente nem muda as horas pagas.
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
Section titled “📋 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.
A avaliação dentro do app segue a regra da página /rate: abaixo de 5 estrelas, um campo “What could we do better?” e Send rating; com 5, até três destaques (RATING_HIGHLIGHTS) e uma avaliação escrita a partir deles com o primeiro nome de quem limpou (POST /api/visits/:id/rating-draft → draftFiveStarReview, o mesmo rascunho da página pública), refeito quando os destaques mudam até o cliente editar o texto; Copy & post on Google copia, abre o Google dentro do toque e grava, e Just send the rating só grava. O cliente grava por POST /api/visits/:id/rating (só o dono, só visita DONE, uma vez, destaques anexados como [Highlights: …] por combineRatingFeedback, last_actor_json do cliente): /atomic/requests recusa toda atualização de CLIENT, e até 2026-10-21 o formulário do app gravava por ali e falhava sempre. No Dashboard do cliente, a linha de avaliação de Needs your attention (“How was your clean with Ana?”) nomeia a equipe da última visita concluída sem nota (assignedEmployeeNames, primeiro nome) e cada estrela abre a visita com o formulário já nessa nota (startRatingAt, ratingIntent.ts), rolando até ele.
Needs your attention (2026-10-21). Tudo que espera pelo cliente no Dashboard fica num cartão só, acima dos números (ClientAttention), na ordem: valor a pagar (faturas emitidas não pagas; Pay abre Financials), produtos que a equipe pediu (shoppingList; See abre a lista com “Mark purchased”), a avaliação, visitas pedidas ainda com o escritório (orçamentos OPEN; See abre a lista) e o convite de avisos no WhatsApp (useWhatsAppOptIn: Turn on / Not now). Mostra três linhas e o resto atrás de “Show N more”; sem nada pendente, o cartão some. Antes eram quatro blocos soltos empilhados; os produtos em estoque, sem nada a comprar, deixaram de aparecer no Dashboard.
Janela da visita do cliente (2026-10-21). O cliente vê a própria visita no padrão do Home (ClientVisitOverview): no topo o serviço, “Sun 25 Oct · 09:00” e a mesma pílula da linha do Home; When & where (o dia, a chegada, cerca de quantas horas e quando termina — só antes da visita; concluída diz “Finished”, sem janela nem previsão, e o cliente nunca recebe os horários de entrada e saída), o endereço com link para o mapa e Reschedule/Cancel enquanto as regras deixam; Your team (avatar e nome, sem o aviso “managed by N professionals” que repetia a lista); Price (o valor com VAT, a referência T-…, e Pay para a página /pay quando há fatura a pagar, senão a situação do pagamento); Your requests (o checklist, visível também vazio enquanto ele pode adicionar — antes sumia vazio e o primeiro pedido não tinha onde entrar); e Your review, com “Your comment”. A aba Report (ou Comprovantes) exibe para a gestão um bloco agrupado de presença e telemetria (ManagerPresenceBlock) antes da linha do tempo, com horários exatos de check-in/out, métricas de precisão, distância do endereço e mapa interativo com marcadores de chegada e saída; a linha do tempo (ServiceMissionTimeline) unifica os registros fotográficos de chegada, ocorrências factuais (ampliáveis no lightbox) e conclusão para todos os perfis. A gestão pode editar ocorrências registradas (tipo, descrição, resolução e fotos) inclusive após a conclusão da tarefa (IncidentManager); funcionários apenas adicionam novos relatos sem sobrescrever histórico. Horários exatos e telemetria GPS completa ficam restritos à gestão; o cliente visualiza apenas a linha do tempo de fotos e ocorrências.
Dashboard do cliente, uma coisa uma vez (2026-10-21). A ordem é: saudação → Needs your attention → Next visit (a visita em andamento, com o selo “In progress now”, senão a próxima marcada — a mesma linha ClientVisitList das listas; abre a visita) → as visitas, uma linha compacta por visita em cada estágio (ClientVisitList: dia, serviço; à frente hora, equipe e valor; atrás equipe, valor e o selo do pagamento; sem equipe, “Team being assigned”) — “We’re on it”, Booked visits e Recently finished, traduzidas. A visita em andamento e a próxima ficam só no cartão Next visit (não se repetem na lista), e a seção “Your team is there” saiu. Todo o Home segue um padrão (HomeSection.tsx): título com o ícone num círculo e a contagem numa pílula, cartão branco com sombra suave (HOME_CARD) e linhas separadas; a data das visitas num bloco colorido pelo estágio (azul marcada, âmbar sem equipe, verde concluída), os avatares da equipe nas marcadas, e o ícone de cada pendência num bloco suave do mesmo tamanho. A próxima visita (ou a em andamento, em verde) é um cartão de destaque em tom claro (gradiente suave, borda azul ou verde): “Sun 25 Oct” grande, hora e serviço, equipe, valor e “View visit”. Todo botão do Home tem um só tamanho, qualquer que seja a palavra (HOME_ACTION: Pay, See, Turn on, View visit). Cada linha de visita tem uma pílula de estado à direita — Confirmed, Team being assigned, e nas concluídas o pagamento nas palavras do cliente (To pay, Checking, Paid, Refunded; nunca o AWAITING do sistema; todas da mesma largura, HOME_PILL, e sem a seta — a linha inteira abre a visita) — e a equipe vem antes do valor (“10:00 · Ana · £72.00”). Saíram a grade de quatro botões (Next Visit, Upcoming, Outstanding, Book Visit — repetiam o cartão, o selo da lista e o + da barra) e a seção Pending Invoices: faturas e pagamento ficam só em Bills, e o Pay do cartão leva para lá; os documentos financeiros do cliente (créditos, correções, reembolsos) foram para Bills → Statement. O selo “Unbilled” é do escritório e não aparece mais ao cliente. O boot passa ao cliente as empresas das suas visitas só com a regra de VAT (id, nome, isVatRegistered, vatRate): sem ela, splitVat usava taxa 0 e o cartão de uma empresa com VAT mostrava £60 numa visita faturada em £72.
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. O marcador de câmera combina a superfície opaca com uma identidade por captura: um resultado restaurado antigo, inclusive de build legado, não apaga a recuperação de uma nova foto da mesma tarefa. Logout/troca de conta também invalida a recuperação em voo, remove Preferences e o arquivo pendente antes de ele alcançar uma sessão posterior.
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 grava por /api/visits/:id/rating, 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.
A seção de avaliação não tem mais o “radar de sentimento”. Ele chamava a IA toda vez que um gerente abria a seção, sem guardar o resultado, e devolvia uma nota de 0–100 sem critério por trás, resumindo comentários que já estão na tela. A nota em estrelas, o Recovery protocol (nota abaixo de 4) e o pedido de avaliação ao cliente continuam.
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)
Section titled “🔑 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. Gestor de Férias & Pausa Temporária de Contratos (Holiday Suspension Manager)
Section titled “🏖️ 5. 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
UPDATEcancela somente visitasPENDING,PENDING_REVIEWouSCHEDULEDdo período com motivoCLIENT_HOLIDAY; uma falha reverte o statement inteiro. - Retry Idempotente:
holiday_suspensionsguarda 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:
pricee VAT faturáveis passam a zero, enquantooriginalPriceeoriginalVatAmountpreservam 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,CFInputeButton, 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.
Finalizar a visita só é anunciado depois de salvo. finalizeShift espera o servidor gravar antes de mostrar “Visit Finalized”. Se ele recusar, a funcionária vê que a visita continua aberta, e a tela volta ao estado real, porque todo salvamento recarrega a lista do servidor. Antes, uma recusa deixava a funcionária sair da casa achando que a visita estava fechada.
Fotos de evidência só são apagadas depois que a visita deixa de apontar para elas. Na aba de relatório, o arquivo só é apagado depois que o servidor grava a remoção. No wizard de fechamento, só são apagadas as fotos tiradas no próprio wizard. Antes o arquivo era apagado primeiro, e aí um salvamento recusado ou um wizard fechado deixava a visita apontando para uma foto que já não existia.
Reparos de integridade não inventam registros. O alerta de visita em andamento sem check-in (MISSING_TELEMETRY) agora pede confirmação manual. Antes o “reparo” gravava um check-in no centro de Londres, no horário marcado da visita, ou seja, um registro de presença que ninguém fez. O reparo de IVA e a compressão do dia no painel de conflitos só anunciam sucesso depois de o servidor gravar. A atribuição automática deixa o resultado com a própria alocação.
🗺️ 6. Mapa de Alocações Futuras da Série & Ajuste de Horas
Section titled “🗺️ 6. Mapa de Alocações Futuras da Série & Ajuste de Horas”- Mapa de Alocações da Série (
SeriesAllocationsMapModal): Ao criar uma tarefa recorrente (via aceite de orçamento), editar (viaQuickEditTaskModal), mover (via arrasto no planneruseApplyMove) ou alocar equipe (viaAllocationModal) com a opção de aplicar para as visitas futuras da série, o sistema abre o modal interativo com o mapa completo de todas as ocorrências futuras. O operador pode:- Visualizar o status de cada ocorrência futura e potenciais conflitos de disponibilidade (sobreposição de visitas ou funcionária em férias/licença).
- Forçar a alocação mesmo com conflito de horário, se assim desejar.
- Trocar individualmente as funcionárias por ocorrência.
- Desalocar funcionárias específicas, deixando a visita futura como pendente (
PENDING).
- Passo de Horas em Meia Hora (30 min): Em todos os modais de alocação e rateio de horas (
FinishVisitModal,AllocationModal,QuickEditTaskModal,VisitCostCorrection), os seletores e botões de incremento/decremento (-e+) operam estritamente em intervalos de 30 minutos (stepHalfHoursDownestepHalfHoursUp), eliminando saltos para 15 ou 45 minutos. A divisão igualitária (equalStaffHours) distribui os centésimos residuais de divisão não exata, garantindo que a soma das horas dos funcionários coincida com as horas acordadas sem falsos avisos amarelos de divergência.
🧭 7. Organizar séries (Issues → Séries)
Section titled “🧭 7. Organizar séries (Issues → Séries)”A revisão das séries de um cliente é um fluxo só, Organizar séries (SeriesOrganizer, /recurring-series/organize/preview e /recurring-series/organize, só ADMIN/MANAGER). A visita fora do padrão é um erro de dado anterior, não um pedido do cliente: o padrão é a verdade.
- Prévia de correções. O cabeçalho mostra frequência, dia da semana e hora de Londres das séries atuais, com serviço e endereço. A revisão abre com os vínculos sugeridos e as duplicatas, mostrando qual visita fica e qual seria cancelada. Datas vazias aparecem junto ao padrão da série correspondente. Editar padrão da série abre as opções de frequência e horário. Junto ao botão Aplicar, a tela resume os vínculos e cancelamentos e destaca as séries que seriam encerradas.
- Visitas avulsas e datas vazias. Uma visita avulsa só entra na sugestão se encaixar em uma única série ativa do mesmo serviço e endereço ou se fizer parte de um padrão reconhecível de visitas avulsas. O escritório pode mantê-la avulsa. A decisão deixa de aparecer em Issues enquanto a data e o padrão sugerido forem os mesmos. A prévia lista datas futuras vazias entre reservas da série atual, considerando cancelamentos, remarcações e férias já registradas. Se for preciso preencher uma data vazia, o escritório agenda a visita separadamente.
- Padrão-alvo por plano. Cada plano (cliente + serviço + endereço) abre com os slots sugeridos —
dia da semana · horário de Londres · frequênciada maioria das visitas futuras (“N de M já fazem isto”). Séries ativas com padrões diferentes continuam separadas, mesmo com menos reservas. A prévia identifica as séries que seriam encerradas. O escritório pode mudar um slot ou somar outro (cliente duas vezes por semana = dois slots semanais, duas séries). A recorrência de quatro semanas (MONTHLY) mantém o dia da semana e o horário de Londres, com 28 dias entre ocorrências. No editor, a próxima data define qual das quatro semanas é a referência. Se a última visita concluída estiver fora do padrão e não houver reservas futuras, Issues permite escolher e agendar a próxima visita como referência, preservando a visita concluída. - Classificação de toda visita futura (passado nunca entra): já encaixa, mover (mesma semana/período do slot), entrar na série (visita solta que, no slot, passa a fazer parte), cancelar (duas visitas no mesmo período do slot; fica a que já está no slot, senão a mais antiga; o escritório pode trocar), bloqueada (iniciada, em fatura viva, com depósito, em folha ou com mudança do cliente em análise; mostra o motivo e fica como está) e exceção.
- Duplicata com registro. Se uma duplicata do período precisa de revisão, os cancelamentos daquele período ficam para decisão do escritório.
- Aplicar é um passo só, um
d1.batchguardado pela assinatura da prévia: se os horários ou a disponibilidade da equipe mudaram durante a aplicação, recusa (“The schedules changed. Review them again.”) e recarrega. O resultado aparece ao lado do botão. - Correção, não mudança do cliente: ninguém é avisado, não há taxa nem remarcação formal; cada visita registra no histórico uma correção do escritório com o motivo “Organize series”. Visita tarde demais para mover (dia do slot já passou ou dentro de 1 hora, ou a própria visita começa dentro de 1 hora ou já começou) fica como está: o apply não a move, não a cancela e não reescreve seu vínculo, salvo quando a série dela termina.
- Marcas antigas viram exceções. Uma remarcação que já aponta para uma ocorrência válida mantém essa referência. Visita com
keptException,slot(remarcação avulsa) ougapKeptcomeça como exceção; o escritório pode desmarcar para trazê-la ao padrão (o apply limpa a marca). - Remarcada após cancelamento. Visita ativa fora do slot, no mesmo período de uma visita cancelada no dia do slot, não se move por padrão: aparece como “Rebooked after the cancelled …” e o escritório decide (manter como exceção ou levar ao dia do slot; a cancelada continua como registro).
- Visitas canceladas. A revisão mostra os cancelamentos futuros que ainda correspondem a uma ocorrência da série, inclusive depois da última visita ativa. O escritório pode usar Reativar pelo fluxo existente. Marcar Manter cancelada encerra o alerta daquela visita e mantém o registro visível na revisão. Férias e ocorrências já cobertas por outra visita ficam fora da lista de reativação.
- Visita mantida entra na série do slot com
keptExceptioneslot, sem ser movida. - Choque de equipe. Se mover põe alguém sobre outra visita, o escritório escolhe por visita: aplicar sem essa pessoa (a mão de obra dela sai; as horas dos outros não são redistribuídas; sem ninguém a visita vai para “Needs a team”) ou manter como exceção.
- Séries resultantes. Cada slot mantém o
groupIdda série compatível mais antiga (ou cria um novo); a série reaproveitada guarda a própriaanchorStartenquanto o slot mantém seu padrão (seriesPatternKey: fase e horário de Londres), senão é reancorada na primeira data futura. Visita que já carrega exatamente esse vínculo não é gravada (sem versão nem auditoria), e visita iniciada só é gravada quando precisa sair de uma série que termina; o “Apply N changes” conta exatamente as visitas gravadas (organizeChangeCount, comrelinksda prévia para as mantidas cujo vínculo muda); as outras séries do plano terminam quando todas as suas visitas futuras migraram ou viraram exceção. O preenchimento seguinte é oplanSeriesExtensionde sempre, que copia só{groupId, frequency, anchorStart}para as visitas novas — marcas de exceção nunca se propagam. O preenchimento respeita o dia já ocupado no mesmo plano e revalida o padrão antes de gravar. - Cancelar a série inteira, retomar e unificar continuam nos planos do cliente (
/recurring-series/cancel,/resume,/unify).