Skip to content

Módulo 4 - Operações em Campo & Telemetria GPS (field-operations)

Módulo 4: Operações em Campo & Telemetria (field-operations)

Section titled “Módulo 4: Operações em Campo & Telemetria (field-operations)”

Estado actual — recebimento acumulado e crédito. Na finalização e no recebimento da visita, funcionário e gerente veem saldo anterior, visita atual, crédito aplicado e valor a receber agora. Para o funcionário, as visitas anteriores em aberto entram automaticamente, sem opção de incluir ou excluir; a gerência mantém a seleção de visitas; a consulta vem do servidor e inclui saldos antigos fora da lista da equipe, mostrando apenas data, referência e valor. Um único valor recebido quita as visitas selecionadas da mais antiga para a mais recente; pagamento parcial mantém o restante em aberto. O excedente confirmado entra na carteira do cliente, uma vez por recibo, para abater da próxima visita; crédito suficiente permite Usar crédito do cliente, sem novo dinheiro. Se o valor informado diferir do total da visita — inclusive quando o crédito já reduziu o dinheiro a receber agora — nenhuma baixa nem crédito é confirmado até a decisão do gerente. A tela mostra o desconto previsto da visita inteira, o crédito do cliente e o dinheiro a receber; a gerência vê o efeito de confirmar: manter saldo em aberto, aplicar o crédito ou guardar o excedente. Divergência de horas também continua aguardando aprovação. Dinheiro e conta do funcionário entram no acerto pelo valor inteiro da visita, mesmo quando o recibo confirmado é menor: a diferença continua prevista porque o cliente ainda a paga. O recebimento seguinte abate primeiro essa diferença já descontada e só aumenta o acerto no que passar dela, para o acumulado não contar o mesmo valor duas vezes. Crédito do cliente usado na visita seguinte não é descontado de novo de quem a fizer. Transferência para a empresa conserva o excedente no extrato como entrada de crédito, sem aumentar a receita da visita. Visitas, faturas, folha e carteira são gravadas no mesmo lote protegido contra mudanças concorrentes; repetir o recibo não duplica dinheiro ou crédito.

Estado actual — execução pela gerência. Check-in, check-out e finalização registrados pelo gerente aparecem como Manager override (Registro pela gerência), com horário e autor, sem coordenadas, precisão, distância ou mapa GPS para esse registro. Registros originais da equipe preservados na finalização continuam com sua prova de localização.

Estado actual — revisão da conclusão. Ao sair da visita, o funcionário pode confirmar o tempo previsto ou informar o tempo real. Uma divergência registra a saída e envia a visita para Aguardando aprovação, sem concluir o faturamento ou lançar horas na folha. A gerência confere as horas em Issues ou no detalhe da visita, por Revisar e aprovar horas. Propostas legadas de recebimento e valores apresentados durante uma divergência de horas aguardam Aprovar valor recebido no detalhe da visita; recebimentos acumulados confirmados seguem a regra de saldo e crédito acima. Issues identifica como Divergência de valores tanto o valor diferente quanto os relatos Não recebi e Não confirmado, com acesso à decisão financeira da gerência. A pendência permanece até a confirmação do recebimento ou regularização do pagamento. Quando há as duas divergências, as horas são aprovadas primeiro.

Estado actual — avisos da equipe. Os avisos de atraso e de produtos em falta são publicados no Team da visita e entregues ao cliente no app. O aviso de produtos também atualiza a lista de compras na mesma gravação. Ao concluir uma visita com fotos de antes e de depois, o Team publica um convite assinado pelo funcionário que concluiu a visita, ou pelo primeiro funcionário escalado se a gerência concluir. O link abre diretamente a aba de fotos e registros da visita. A gerência pode usar Enviar link do app pelo WhatsApp para adiantar o assunto e convidar o cliente a abrir a mensagem. Com a janela de 24 horas fechada, o app abre o WhatsApp Business com o convite pronto para envio.

Estado actual — horas no Finish visit. O gerente ajusta as horas de cada pessoa e as horas cobradas do cliente em passos de 15 minutos. As horas da equipe pagam a folha; as do cliente podem passar da soma trabalhada e, na cobrança por hora, definem o preço. Preço travado, comissão ou preço fixo não mudam o valor por essas horas.

Estado actual — edição do próprio perfil. Idioma, foto e endereço são salvos diretamente; somente conta bancária depende de aprovação de manager/admin. Trocar só o idioma confirma o salvamento, sem gerar pedido nem aviso ao gerente. O formulário mostra o homeAddress salvo mesmo quando a lista addresses vem vazia, e compara o endereço com a fonte canônica antes de enviá-lo; trocar só o idioma preserva a casa cadastrada.

Estado actual — endereço nos detalhes da funcionária. Com um só endereço cadastrado, a tarefa mostra somente o endereço completo, sem “Main” nem outro rótulo. O endereço abre o Google Maps com texto neutro, sem sublinhado, e o ícone discreto de abertura externa no padrão do app; quando o cliente tem vários endereços, o nome do endereço da visita aparece numa etiqueta âmbar acima dele. A visita fora do principal mantém o aviso explícito existente, e o endereço usado continua sendo o da tarefa (resolveTaskAddress), não outro do cadastro.

Estado actual — colegas na tarefa. Com mais de uma pessoa na equipe, o nome de cada colega permanece como texto; um botão WhatsApp separado após o nome abre o WhatsApp Business para o telefone cadastrado. O botão não aparece para a própria pessoa nem para um colega sem telefone.

Estado actual — recebimento ao finalizar pela gestão. Na confirmação de pagamento do Finish visit, manager/admin escolhe apenas Received ou No payment received. Não há Unconfirmed nem os atalhos Client says payment was made e Payment received by another person; valor, recebedor e saldo pendente seguem as regras existentes.

Estado actual — resumo do perfil da equipe. O Overview mostra os dados bancários em linhas legíveis sob Dados bancários, usando o formatador compartilhado para registros estruturados e antigos.

Estado actual — Keys no perfil. Ao abrir Keys em uma ficha de cliente ou da equipe, o carregamento permanece dentro da aba, sem fundo escuro nem janela adicional; ações de chave continuam abrindo suas próprias folhas.

Estado actual — coordenação. Check-in/check-out, conclusão simples, incidentes, finalização, recebimento, lembrete, correção de recebedor e materiais usam fluxos de aplicação com efeitos injetados; endpoints, stores, cache e avisos ficam nos adaptadores. Evidências, recibo estável, versão aceita, cooldown, folha e listas do servidor são preservados. Respostas individuais/em lote não repõem visitas removidas nem sobrescrevem uma edição mais recente; a troca de sessão impede publicar resultados e enviar o restante do lote. Custódia reutiliza as regras puras existentes e transporte cancelável; fotos offline separam seleção por usuário/autoridade/alvo do IndexedDB e upload.

Estado actual — início e Home (2026-10-26). O título de início e conclusão da tarefa só aparece junto de conteúdo de entrada ou saída; tarefas sem ação disponível não deixam título nem seção vazia. O box de check-in tem o título «Registre sua entrada»; as orientações para ativar a localização aparecem quando há um problema, sem pedir ativação a quem já a tem ligada. Iniciar a visita pede a localização; Continue anyway só aparece depois de o telefone não a dar, e não bloqueia o início. Uma paragem da rota do Home abre a visita; com o dia todo feito, Done today lista o que ficou pronto. Uma visita sem realDuration (coluna nula) aceita o check-in. Com mais de um endereço e a visita fora do principal (isDefault), a Home, a rota, o Dia, a janela da visita, o início e a lista offline mostram «Não é o endereço principal» (visitNotAtMainAddress).

Localização por aparelho. Quando não vem localização, o motivo (bloqueada para o app, localização do aparelho desligada, sem sinal) e os passos dependem de onde o app roda: app nativo do iPhone/Android (com botão Abrir ajustes), app da tela de início (que herda a permissão do Safari/Chrome), aba do navegador (Safari, Chrome, Samsung Internet, Firefox, Edge) ou computador (Mac/Windows). Uma regra (src/shared/platform/locationHelp.ts) serve o pedido ao abrir o app e o início da visita (LocationHelp). No iPhone, o navegador responde “negado” quando os Serviços de Localização estão desligados, por isso esse passo vem primeiro. Sem checklist, notas de acesso ou resumo, Começar agora inicia direto, sem a janela de revisão; o aviso e o Continuar mesmo assim aparecem no próprio cartão. Durante a visita, as fotos de chegada e do resultado podem ser adicionadas a qualquer momento via câmera ou galeria (PhotoSourceModal), e o fechamento as mantém. Uma funcionária não pode iniciar uma visita se já tiver outra em andamento (IN_PROGRESS); o início fica bloqueado no backend (/api/atomic/requests), no hook de operações e no cartão de início com aviso explicativo.

Ações em um toque (2026-10-26). “Registrar entrada” da Home já inicia a visita (a janela de revisão só aparece com checklist, notas de acesso ou resumo); “Registrar saída” abre direto o fechamento, que é uma tela só: fotos de chegada e do resultado via câmera ou galeria, “Acabou algum produto?”, “Algo deu errado?” (fechado até a funcionária abrir) e a confirmação de pagamento simplificada quando ela recebe (apenas “Recebido” — total ou diferente — ou “Não recebi”, mantendo saldo pendente; a forma dinheiro/conta vem configurada na tarefa e dispensa comprovante anexado), com um botão “Concluir visita” — se o pagamento falta, um aviso acima do botão leva até ele. Antes do fechamento, o cartão de dinheiro diz só quanto receber do cliente. A Home não mostra mais o subtítulo nem as horas da semana (ficam em Pagamentos), e a rota mostra todas as tarefas do dia na sequência, mesmo concluídas ou em destaque no momento, para manter a visão de sequência e distância entre elas. O pedido de localização ao abrir o app espera os passos de instalação, notificação e som. No celular, toda janela de baixo ocupa 90% ou a tela toda, com margens de 20 px.

Primeiro acesso no celular (2026-10-26). O guia do iPhone tem três passos ilustrados com barras e folhas do iOS, uma única orientação de login e ajuda recolhida. Safari 17/18 começa em Compartilhar; 26+ usa ••• como sugestão inicial (Version, não o OS congelado do user agent), com escolha visual entre ••• e Compartilhar porque o layout compacto/barra superior/inferior não é detectável. Não se tenta adivinhar o modelo do iPhone; navegador interno orienta copiar para Safari. Quando disponível, Abrir como App deve ficar ativo. A ordem é sempre a mesma: o link abre o primeiro acesso no navegador (dados → senha → Face ID/digital); depois, a instalação (obrigatória para a equipe, opcional para o cliente), com um cartão “Depois de instalar” que diz o que vem a seguir; dentro do app, notificações → som → localização. No Android o app instalado usa o mesmo login do Chrome e abre já conectado. No iPhone o app da tela de início tem login próprio (separado do Safari) e os links do WhatsApp sempre abrem no Safari: por isso, num iPhone que ainda vai instalar, o Face ID vem primeiro e em destaque no primeiro acesso, e no login do app instalado o Face ID aparece em primeiro, com a linha “use Face ID ou seu e-mail e a senha que você criou”. A chave do Face ID é do aparelho (sem e-mail), então funciona no app instalado. Falta confirmar num iPhone e num Android reais.

Aviso de atraso. A janela busca a posição atual da funcionária e calcula a distância em linha reta até o endereço da visita (visitPoint); «Estimativa» deriva dessa distância (fator urbano 1,35, média de 20 km/h, 5 min de acesso, mínimo 10 min), sem trânsito ao vivo. Sem localização/coordenadas, mostra distância indisponível e nenhum tempo fictício; falha de GPS permite tentar novamente, sem impedir o aviso manual. Na Home da funcionária, «Avisar cliente» tem formato de pílula e a mesma altura de «Registrar entrada». Dentro da tarefa, o botão fica ao lado do check-in, com opções de atraso de 15 min, 30 min ou personalizado (ajustável). A prévia exibe o texto completo em inglês com a linha de autoria (_Team_ — Nome:) e não permite edição do texto. A entrega (deliverLateNotice): se a janela de 24 h do WhatsApp estiver aberta, a mensagem sai direto para o cliente no WhatsApp (forwardToWhatsApp) assinada pela funcionária; se estiver fechada, a mesma mensagem fica retida (HELD) como nota interna para o envio do manager (via template aprovado ou WhatsApp Business). Quando o aviso chega ao cliente, a visita guarda a chegada prometida (expected_arrival_at, migração 0236): o cliente vê “Atrasada — chega por volta das HH:MM” na Home e na janela da visita, e o escritório vê o mesmo na linha do Dia e no resumo da visita, até o check-in. Na ficha da funcionária, um holerite negativo aparece como valor A receber, com o período legível.

Estado actual — avaliação no app. Na tarefa concluída, escolher cinco estrelas ou mudar os destaques não gera texto. O cliente pode escrever diretamente no Google, ou pedir um texto baseado em até três destaques e usar “Copiar e publicar no Google”; não há campo de escrita duplicado no app. A geração é explícita e mudar os destaques descarta o rascunho anterior. A nota e os destaques são salvos no app; publicar a avaliação continua sendo uma ação do cliente no Google. O portal público /rate mantém o fluxo próprio descrito abaixo.

Estado actual. Distância, precisão ou permissão negada não bloqueiam check-in/out nem o acesso ao app. O pedido de localização ao abrir o app (EmployeeLocationGate) fecha pelo X (sem botão Not now) até o app ser aberto de novo (antes não havia saída e a permissão negada travava o app). O aviso de valor anterior devido (EarlierCashOwedBanner) só mostra à equipe o que ela pode receber (dinheiro ou conta de funcionário), com datas, referências e valores, logo acima do valor a receber pela tarefa atual, com espaço reduzido entre os dois boxes, sem a frase de que o cliente pode entregar hoje e sem formulário de confirmação de pagamento; a baixa permanece na seção de pagamento da visita e nos fluxos de recebimento existentes. Transferência devida é assunto do escritório. A janela da visita da funcionária segue o padrão do cliente (CrewVisitOverview): cabeçalho com cliente, dia, hora e serviço; Start and finish your visit primeiro; When & where com o horário dela, o início exato, mapa, what3words e notas de acesso (copiáveis); Your team (com duas ou mais pessoas, o nome da colega abre o WhatsApp Business dela — crewPhones, só a equipe; o cliente não recebe o número); e o checklist. A funcionária não vê o box de recebimento do cliente; apenas quando o pagamento é indicado em dinheiro ou na conta própria dela é exibido o box verde de acerto (CrewCollectionCard e etapa de cobrança do ShiftClosureWizard), sem Você recolhe, Sua parte e Devolver/A receber da empresa (retirados em 2026-11-07 para não parecer que ela devolve dinheiro; o acerto fica no total da semana e no holerite). Ao reabrir depois de «Não recebi», essa opção já vem marcada e «Dar baixa no pagamento» fica oculto enquanto ela for mantida, pois não há nova confirmação a salvar; ao escolher Recebido, o botão reaparece e pede só o valor. Quem recebeu e se o cliente disse que já pagou ficam com o escritório. O checklist e as instruções só são exibidos caso tenham sido cadastrados, sem caixas vazias na tela pré-operacional de check-in (ClockInPreflightSheet). O funcionário vê apenas os horários de check-in/out; o cliente não recebe horários reais nem localização, e só a gestão recebe a prova GPS completa. A aba de evidências/comprovantes abre após o início da tarefa para o gestor, que pode incluir fotos e ocorrências mesmo com a visita fechada. Cliente e equipe só a veem quando já há foto ou ocorrência (o cliente desde o início, a equipe depois de DONE); um bloco vazio fica oculto, e a aba inteira também quando não há nada. Sem avaliação, a equipe não vê esse espaço. A ocorrência não tem verificação por IA. Comprovantes de pagamento foram removidos dessa aba; apenas a gestão acessa a telemetria GPS e horários de clock-in/out no timeline, enquanto fotos de antes e depois são visíveis para todos. As leituras redigidas da equipe não apagam a prova original ao atualizar checklist ou finalizar. Iniciar aguarda o aceite do servidor; uma finalização recusada restaura o estado anterior antes de permitir outra tentativa. Durante atendimentos em andamento (IN_PROGRESS), a tela do dispositivo da equipe é mantida ativa via Screen Wake Lock (wakeLockProvider) para evitar bloqueios automáticos durante o trabalho e checklist. As fotos de antes podem ser inseridas logo após o check-in (durante o atendimento em ServiceGeoAction) ou no momento da finalização (ShiftClosureWizard), com limite ampliado para até 20 fotos. O check-out concentra 3 etapas padrão (materiais em falta, ocorrências e fotos de antes/depois); a 4ª etapa de confirmação de pagamento e recibo só é apresentada se a tarefa indicar pagamento em dinheiro ou conta da própria equipe (isCrewCollected). Notificações continuam obrigatórias no celular; GPS e câmera não são requisitos de entrada. O pedido de localização do funcionário (EmployeeLocationGate) espera o primeiro acesso terminar e não aparece no navegador do celular antes da instalação; o rastreamento continua montado. No ShiftClosureWizard, Time worked fica logo acima do valor a receber, no mesmo padrão de seção da janela: o tempo previsto para ela em horas (formatHourMinutes) e ajuste com − / + em passos de 15 min (stepQuarterHoursDown/Up). Alterado, avisa que vai para aprovação do gerente e que só se altera com autorização prévia do cliente (com Keep the planned time), e o botão vira Send for approval (COMPLETION_REVIEW). O box verde de recebimento da equipe (ShiftClosureWizard, CrewCollectionCard) é só o título com o valor, o resumo (CollectionBalanceSummary: visitas anteriores, esta visita, crédito aplicado, valor a receber agora — sem linha de desconto previsto nem regra de quitação; a lista das visitas anteriores não repete Esta visita · Anteriores · Total, nem no Finish visit) e a confirmação (Recebido e o valor digitado à mão — sem pílula “Recebi £x”; o Finish visit do escritório segue a mesma regra desde 2026-11-09: sem o botão “Received £x”, o valor começa vazio e só “usar só o crédito” é um toque, quando não há dinheiro a contar); a frase do efeito na fatura só aparece com Recebido. Finish visit da gestão mantém as regras de horas e cobrança já existentes. Ao finalizar (equipe ou gestão), visitas anteriores do mesmo cliente ainda em aberto podem ser incluídas no recebimento em dinheiro ou conta da equipe: a liquidação é cronológica e consolida tarefas ainda sem fatura em uma única fatura com o valor total, enquanto faturas existentes recebem baixa individual. Visitas configuradas para pagar na conta da empresa não apresentam a etapa de cobrança para a equipe de campo. Na gestão (FinishVisitModal), a etapa da equipe exibe inicialmente apenas os funcionários já alocados para a visita, com botão expansor para listar os demais funcionários da empresa quando for necessário incluir ou remover colaboradores. O lembrete de pagamento da funcionária que recebe (/api/field/payment-reminder, uma vez a cada 24 h) não fala com o cliente: reúne todas as tarefas finalizadas com cobrança em aberto do mesmo cliente aguardando a funcionária, detalhando cada uma e o somatório total no texto ao cliente (buildCrewPaymentReminderMessage), grava na conversa da última tarefa em aberto (JOB) uma nota retida, em inglês e no nome dela (incluindo dados bancários se houver cobrança em conta de funcionário), e, se o cliente tem o app com notificações, entrega-a na hora em nome da empresa (autoReleaseHeld, sem avisar o escritório; a funcionária vê “enviado ao cliente”); sem app, fica retida e o escritório é avisado para liberar (HeldMessageRelease). O aviso de atraso (/api/channels/transitNotice) vai direto ao grupo da tarefa e ao cliente, sem liberação. Uma nota escrita em inglês por nós (sourceLanguage: 'en-GB') conta como inglês na liberação automática (heldEnglish) — antes o detector de idioma recusava o texto do lembrete e ele ficava sempre retido.

Estado actual — entrada e saída por pessoa (2026-11-09). Cada funcionária alocada registra a própria entrada e a própria saída. A entrada de cada uma entra em checkedInEmployeeIds no check-in da visita; a saída de quem sai antes, em checkedOutEmployeeIds (lista do servidor) e em crew_clocks. Enquanto houver colega que entrou e não saiu (colleaguesOnSite), a finalização registra só a saída de quem finaliza: a visita continua IN_PROGRESS, sem horário de saída da visita, sem cobrança automática nem aviso ao cliente, e o formulário de saída avisa que só registra a saída dela. A etapa de pagamento é só de quem está configurado para receber (receivesCrewPayment: quem está configurado na tarefa; numa equipe de uma pessoa, ela — nunca a primeira de uma equipe maior, e o Edit task exige a escolha; o Finish visit também, mesmo com o pagamento ainda não recebido, e grava a escolhida na visita), nunca de quem sai por último; as demais não a veem — nem a etapa do formulário de saída, nem o box verde de recebimento da visita (CrewCollectionCard) e o aviso de valor anterior devido acima dele. Se a recebedora sair antes das colegas, ela dá baixa ali mesmo, na própria saída: o /field/collect aceita o valor com a visita em andamento quando quem registra já saiu, marca a visita como paga com ela como recebedora (staffCollectedBy, deduzido no holerite dela) e a fatura paga é emitida quando a última sair. Recebedor fora da equipe (funcionária com conta, gerente) não vê a etapa de ninguém da equipe: ele confirma em Pagamentos (Payments to record, e a linha na tela inicial); a funcionária recebe só essa visita para confirmar (requestScope inclui planned_collector_id), sem agenda, fotos ou trabalho (workedRequestScope; as telas filtram por alocação), e o valor é deduzido do holerite semanal dela. Quem sair por último finaliza a visita. Colega alocada que nunca entrou não segura a visita aberta. Horas informadas diferentes do previsto ficam por pessoa (crewHoursReviews); se houver alguma ao final, a visita vai para COMPLETION_REVIEW, que o quadro do dia mostra como concluída (antes caía em atrasada e a tela inicial oferecia Registrar entrada). O box de aprovação (CrewCompletionReviewCard, crewHoursLines) nomeia cada pessoa da equipe: quem informou outro tempo (previsto e informado, em horas), quem saiu no previsto e quem entrou e não registrou a saída (quem fecha a visita também entra em checkedOutEmployeeIds). O Finish visit do escritório aprova e limpa as linhas. Na aba de evidências, o gerente e o administrador veem a entrada e a saída de cada pessoa (CrewClocksList, lido sob demanda em GET /api/visits/:id/clocks, de crew_clocks): horário de Londres, distância quando ficou fora do raio e “sem localização”; quem da equipe não tem registro aparece como não registrou. Coordenadas não saem; equipe e cliente recebem 403. A tela inicial, os botões da visita e o bloqueio de outra visita em andamento seguem o estado da própria funcionária (ownClockState, holdsCleaner): quem já saiu pode iniciar a próxima visita, e quem ainda não entrou numa visita iniciada por colega vê Registrar entrada. A leitura redigida da equipe passou a trazer as duas listas (sem coordenadas). Caso que motivou a mudança: T26-1558, em que a primeira funcionária finalizou e a segunda ficou sem como registrar a saída.

Em Operações, o cálculo de conflitos carrega sob demanda e roda num Web Worker partilhado com a barra lateral. Na primeira vez, a pílula Clashes de Issues aparece com um spinner no lugar do número (o leitor de ecrã ouve quantas visitas já foram conferidas, issues.scan); quando o cálculo fecha, mostra o total ou some se for zero. As vezes seguintes recalculam sem spinner. Os outros grupos aparecem logo, e os conflitos só quando o cálculo fecha. Tempo de deslocamento curto só é problema quando a chegada passa do fim da janela do cliente (45 min numa visita que segue outra); chegar depois da hora marcada, ainda dentro da janela, não entra. O resultado pertence à conta, papel e sessão atuais: troca de identidade ou dados invalida respostas antigas; sair do último consumidor encerra o trabalho e libera os dados. A atualização por relógio ocorre uma vez por minuto em primeiro plano e na retomada, preservando o último resultado enquanto recalcula; a virada do minuto nunca cancela um cálculo em curso (um cálculo de mais de um minuto recomeçava do zero para sempre), só uma mudança de dados ou de conta o faz; falha do Worker usa fallback cancelável, sem aceitar resposta tardia do Worker anterior. O histórico por cliente e as visitas por funcionária são agrupados uma vez por cálculo, mantendo os critérios de continuidade e trânsito. O board agrupa as visitas da semana numa passagem. A expansão recorrente ignora uma segunda gravação do mesmo grupo no mesmo horário, inclusive na concorrência entre cron e salvamento.

O módulo Field Operations gerencia a atuação presencial da equipe nos imóveis dos clientes, capturando coordenadas GPS no check-in/out e calculando a compatibilidade entre a funcionária e a residência.


📍 1. Algoritmo de Matching de Equipe (StaffMatchingService)

Section titled “📍 1. Algoritmo de Matching de Equipe (StaffMatchingService)”

Na hora de alocar uma funcionária para um cliente, o StaffMatchingService calcula um Score de Compatibilidade (0 a 100) considerando:

  1. Afinidade Prévia (40%): Histórico de limpezas bem-sucedidas no mesmo cliente.
  2. Proximidade Geográfica (40%): Distância em km entre a residência da funcionária e o imóvel.
  3. Preferência de Idioma (20%): Idioma de comunicação em comum entre a equipe e o cliente.

  • Matching de Equipe: src/features/field-operations/services/StaffMatchingService.ts
  • Hook de Operações: src/features/field-operations/hooks/useExecutionOperations.ts
  • Validação GPS & Ações de Campo: src/components/service-detail/ServiceGeoAction.tsx
    • A checagem de proximidade de 20 segundos usa um gate por epoch de foreground/visita: serializa leituras normais, invalida resultados ao pausar/trocar/desmontar e solicita um fix novo na retomada. Uma posição tardia nunca dispara auto-start no atendimento anterior.
    • Clock-in e finalização adquirem locks antes do primeiro await; a preflight mostra busy e não fecha durante a captura. Toque duplo não duplica GPS, persistência ou Activity Log, e o preparo da evidência não conclui depois do teardown.
  • Aviso de Deslocamento/Trânsito (Transporte Público): src/components/service-detail/modals/TransitDelayModal.tsx & functions/api/channels/transitNotice.ts
    • O envio usa timeout de 15 segundos e controller pertencente ao pedido/cliente visível. Fechar, desmontar ou trocar esse owner aborta a operação; respostas antigas não produzem toast, háptico nem fechamento. Presets e ações ficam congelados durante o envio, e falha devolve a mesma superfície ao estado interativo para retry em desktop, PWA, Android e iOS.
  • Upload de Fotos/Evidências: src/components/service-detail/PhotoUploadZone.tsx e ChecklistItemRow.tsx oferecem janela universal (PhotoSourceModal) para escolha entre Tirar foto (câmera) ou Escolher da galeria, enviando ao R2 com AbortSignal, epoch de sessão e confirmação autoritativa antes de anexar a URL ao pedido. Em caso de perda de conectividade, fotos capturadas são salvas com segurança no IndexedDB local (OfflinePhotoStagingService, banco prime-crown-photos) e enviadas pela própria zona de fotos (mesma visita e rótulo) ao abrir e quando a conexão volta. Troca de conta, visita ou desmontagem aborta a sincronização; se o R2 já aceitou o arquivo, a evidência permanece na fila para retry, em vez de ser anexada à nova visita ou apagada sem vínculo.
  • Custódia de chaves (com quem está cada chave): a chave está sempre com uma pessoa ativa — um manager (“com a empresa”) ou uma funcionária —, perdida, ou devolvida ao cliente; não há cofre nem retirada/devolução. key_tags guarda o portador (holder_id), a passagem pendente (pending_to_id) e o estado (HELD/LOST/RETURNED, migração 0191); cada mudança grava last_event_* e os triggers copiam o evento para key_custody_records com de → para (o portador anterior → o novo ou o destinatário), quem registrou e a nota, no mesmo statement. /api/field/key-custody (Hono + Zod, expectedVersion e o estado esperado em todo UPDATE; 409 em conflito): o manager cadastra (com quem começa; padrão ele mesmo), move direto sem confirmação (MOVED, ou FOUND se estava perdida; apaga uma pendência), marca perdida, devolve ao cliente e edita número/descrição/notas; entre a equipe a passagem é em dois passos — quem segura pede (request-handover), quem recebe confirma (confirm-handover), qualquer um dos dois cancela —, e até a confirmação a chave continua com quem entregou. O GET (manager+) traz as chaves e os 200 eventos mais recentes; ?keyId= traz o histórico inteiro de uma chave. Operations → Keys (KeyCustodyPanel, também no perfil do cliente) lista as chaves por portador (managers primeiro), com pílulas Com alguém · Passagem aguardando · Perdidas · Devolvidas e um menu por chave (Mover para…, Perdida, Devolvida ao cliente, Editar, Histórico). Ninguém é desativado enquanto segura chave ou tem uma vindo para si (keysBlockingDeactivation, src/shared/keyCustody.ts: 409 HOLDS_KEYS em /atomic/employees e o mesmo aviso no StaffProfile). Na alocação (Batch/Split route), keyHolderMismatch avisa só se nenhuma cópia do cliente estiver com a pessoa escalada (ou a caminho dela) e diz com quem estão; o card do Dashboard conta passagens aguardando e chaves perdidas (keysAttention).
  • Chaves no Home da funcionária: /api/field/my-keys (só EMPLOYEE, só leitura) devolve as chaves que ela segura, as que estão sendo passadas para ela e as dos clientes das visitas dela hoje e amanhã (Londres, SCHEDULED/IN_PROGRESS) com quem estão; nunca as devolvidas, e uma perdida só se for de cliente que ela vai visitar. O MyKeysCard permite passar uma chave dela para qualquer pessoa ativa (managers inclusive), aceitar ou recusar uma que estão passando para ela, e cancelar a passagem que ela pediu.
  • O que a funcionária grava sobre si (2026-09-24): POST /atomic/employees trata o papel EMPLOYEE antes do schema do gerente, só para o próprio id e só pelo ownUpdateSchema: o ping do rastreador ({ id, lastKnownLocation }, saveOwnEmployeeLocation) ou o próprio perfil do Profile ({ id, ownProfile: { preferredLanguage, bankDetails, homeAddress, version } }, saveOwnEmployeeProfile, mesma trava de versão do gerente; a casa ganha coordenadas pelo CEP). Salário, papel e status ficam com o gerente (400/403). Antes, o schema do gerente exigia name e o ping chegava sem ele — nenhuma posição da equipe era gravada —, e o Profile da funcionária falhava com “Invalid location update” (ou, com uma posição antiga no registro, respondia ok sem gravar nada).
  • O perfil da funcionária (2026-10-19): o Profile não mostra mais o selo “Cleaner” ao lado do nome (gerente e admin mantêm o seu) nem o bloco Perfil profissional. Experiência saiu do sistema (migração 0220: nada a preenchia, todo save gravava MID); tipo de contrato continua no cadastro (a folha lê isSelfEmployed), só não aparece para ela. Nota e especialidades são do escritório: a nota (performanceScore, usada na escala) nem chega a quem não é gerente/admin (boot e GET /atomic/employees); as especialidades seguem no payload porque o app as lê (carpete).
  • Avisos da funcionária (2026-10-19): no Profile ela vê só o que chega de facto — mensagens, visita nova, sem check-in, holerite e a decisão sobre foto, banco ou endereço — e nenhum se desliga. Som, duração do aviso e os interruptores de categoria ficam com o escritório e o cliente. No PWA do Android e do computador o aviso traz o botão da ação: abrir a visita, check-in ou avisar atraso (+15/+30/+45), abrir o holerite, ver a resposta. O check-in não se marca sozinho. Mensagens continuam com Responder e Marcar como lida. O iPhone não mostra esses botões.
  • Somente dados bancários precisam de aprovação: idioma e endereço de casa salvam diretamente pelo ownProfile; a própria foto salva por /api/profile-photos, sem solicitação ao gerente. O idioma sozinho não reenvia o endereço nem mostra mensagem de aprovação. Dados bancários continuam em employee_change_requests (/api/staff-changes): um pedido pendente por pessoa, substituível ou retirável; o gerente aprova ou recusa no cartão de People/perfil, com aviso à funcionária. O retorno do formulário distingue “perfil salvo” de “dados bancários enviados para aprovação”. A migração 0242 cancela os antigos pedidos pendentes de foto/endereço sem aplicá-los nem apagar decisões anteriores; versões concorrentes não permitem sobrescrever um perfil mais novo nem endereços de outra pessoa. Salário, papel e status continuam exclusivos da gestão.
  • Dados bancários enquanto se digita (2026-09-29): os formulários (perfil da funcionária e cadastro no escritório) gravam a cada tecla com parseBankDetails/formatBankDetailsJson em modo asTyped, sem aparar — aparar ali comia o espaço antes do segundo sobrenome. O servidor apara cada campo ao gravar (normalizeBankDetails).
  • Supply Hub & Gestão de Materiais do Cliente: A empresa não fornece nem vende produtos de limpeza próprios — os materiais pertencem ao imóvel do cliente (standardSupplies). A equipe em campo indica produtos em falta no fechamento do atendimento via /api/field/shopping-list, disparando notificação push para o cliente. No dashboard do cliente (ClientSupplyAlert) ou no painel operacional (SupplyHub), ao marcar que comprou (action: 'restock'), o item sai da lista de compras (shoppingList) e é adicionado automaticamente ao estoque do imóvel do cliente (standardSupplies), com concorrência otimista em D1 e espelhamento no cache do TanStack Query. O painel inclui KPIs compactos, barra de ferramentas padronizada (HubToolbar), busca de imóveis/materiais e filtros por urgência.
  • Quem reportou e o Notify (2026-11-05): o servidor carimba cada item reportado com quem estava na sessão (reportedBy = staffName, reportedById, reportedAt) — nunca o que o aparelho mandou —, e o Supply Hub mostra o nome em cada item. O relato cria na hora a mensagem no grupo da tarefa (JOB, id supply-notice-…) com push ao cliente que tem o app; sem app, o gerente usa “enviar ao cliente” nessa mensagem do chat (convite ao app pelo WhatsApp, to-client). O Notify do Supply Hub é outro caminho: action: 'notify' (ADMIN/MANAGER) manda a lista (supplyReplenishmentNotice, src/shared/supplyNotice.ts) na conversa DIRECT pelo WhatsApp com a janela de 24 h aberta; fechada, devolve WINDOW_CLOSED com texto e número e o app abre o WhatsApp Business (o eco grava a mensagem no DIRECT).
  • Incidentes: o aviso de registro e o fechamento do formulário aguardam o aceite do servidor. O formulário mantém ID e instante entre tentativas; /api/field/incidents acrescenta um único relato com auditoria, versão e tabela normalizada na mesma transação, reconhece repetições sem nova gravação e recusa o mesmo ID com conteúdo diferente. O endpoint genérico de visitas também preserva os relatos existentes ao finalizar com um snapshot antigo e recusa alterações/remoções do histórico pela equipe; as tabelas normalizadas permanecem na mesma transação. Uma falha mantém texto/fotos; nenhum relato otimista é anunciado como gravado. A composição preserva a identidade do relatório e invalida feedback após troca de sessão. Formulário avulso e fechamento de turno usam CFSelect, CFInput, IconBadge e Button, com seleções aria-pressed, grids adaptativos e alvos de toque canônicos. A descrição é aparada antes do envio e um lock síncrono impede relatórios duplicados. A análise por IA mantém um único AbortController, é cancelada no teardown e mostra falha com opção real de retry.

Check-in, check-out e finalização calculam a próxima solicitação a partir do snapshot síncrono atual do store e publicam o estado otimista antes de rede, log ou toast. Nenhuma escrita ocorre dentro de um updater React/Zustand, portanto uma reinvocação do render não duplica D1 ou Activity Log. Eventos sequenciais no mesmo frame enxergam o resultado anterior, e uma tarefa removida durante a gravação não produz falso sucesso de finalização, mesmo sem recebimento em web, PWA, Android ou iOS.

Alocação individual/em série, conclusão manual e mudança administrativa de status seguem a mesma fronteira: o próximo estado é calculado fora do updater e cada tarefa aceita somente uma mutação em voo. Rejeição restaura somente campos ainda pertencentes à tentativa, incluindo a projeção da versão feita pelo cache; uma leitura ou recibo realmente confirmado pelo servidor encerra essa propriedade e impede reversão após resposta perdida; desmontagem ou troca de árvore invalida respostas, rollbacks e toasts tardios. Propagação recorrente e notificações verificam o lifecycle antes do feedback, evitando duplicação por toque/Strict Mode e conclusão vazando para outra sessão nas quatro plataformas.


🚇 3. Aviso de Deslocamento & Trânsito via Transporte Público (Londres TfL)

Section titled “🚇 3. Aviso de Deslocamento & Trânsito via Transporte Público (Londres TfL)”

Quando a funcionária se desloca via metrô/ônibus e prevê uma variação no horário de início, o app calcula a estimativa de trânsito em tempo real (estimateLondonPublicTransit) e despacha com 1 clique uma notificação oficial assinada pela própria funcionária no canal da tarefa (JOB) e via WhatsApp para o cliente.


📶 4. Contrato de Conectividade para Fotos de Vistoria

Section titled “📶 4. Contrato de Conectividade para Fotos de Vistoria”

Uma fila anterior guardava base64 em localStorage e enviava o arquivo depois sem reconciliar a URL no pedido, criando objeto órfão e falso sucesso. A fila atual (IndexedDB) só é esvaziada pela zona que anexa a foto, e onAdd só é chamado depois da resposta válida do R2. Se o owner muda enquanto o R2 conclui, a URL não é anexada ao novo contexto e o item continua pendente para uma tentativa segura. O chat continua sendo a única funcionalidade com fila offline persistente, porque possui identidade, owner de sessão e reconciliação completas em IndexedDB.

O portal público /rate compartilha o transporte limitado das demais rotas públicas: contexto encerra em 12 segundos, envio em 15 segundos e teardown aborta a operação. Ao pedir avaliação de uma visita concluída (RATING), o gestor gera o link curto /go/<code> com destino rating:<id> (sem e-mail e sem template da Meta). A página é clara (fundo slate-50, cartão branco) e pede, nesta ordem, os destaques do serviço (RATING_HIGHLIGHTS, src/shared/ratingHighlights.ts: 12, no máximo 3 — o servidor recusa um quarto ou um rótulo fora da lista), a nota e só então a caixa de texto. De 1 a 4 estrelas aparece a caixa “What could we do better?” e o botão Send rating; a nota fica só no app. Com 5 estrelas não há caixa de comentário: POST /api/public/rating-draft (o mesmo token, não grava nada) escreve com a IA (askText, feature reviewSuggestion) uma review curta do Google com o primeiro nome da funcionária (ratedStaffFirstName: alias primeiro, nunca o nome completo) e os destaques escolhidos — ângulo e tamanho sorteados, clichês recusados (acceptReviewDraft), e sem resposta da IA um rascunho por frases variadas (composeFallbackReview). O cliente edita o texto (ou pede Write another); Copy & post on Google copia, abre GOOGLE_REVIEW_URL no próprio toque e grava a nota com o texto que o cliente deixou na caixa (o editado, não o rascunho). O feedback guarda esse texto seguido de [Highlights: …]; splitRatingFeedback separa os dois, e a aba de avaliação da visita (ServiceReviewSection) mostra ao escritório as palavras do cliente e os destaques. Falha de rede mantém retry explícito e não vira falso “Service not found”; o lock síncrono preserva uma única avaliação em voo em web, PWA, Android e iOS.

As observações de acesso do endereço (addresses.access_notes, editadas em ClientAddressManager) aparecem para a equipe e os gestores no cartão de logística do detalhe da visita (ServiceLogistics), lidas do endereço atual por resolveTaskAddress — não da cópia gravada no agendamento, porque o escritório troca o código do cofre depois. Sem endereço selecionado não se mostra o de outro endereço. O cliente não as vê ali; o feed de calendário da equipe já as incluía.

  • Concluir não fatura. Ao finalizar a visita, paymentStatus fica NONE. Antes, a conclusão pela funcionária marcava DRAFT (“em fatura rascunho”) sem existir fatura: o botão de gerar fatura não fazia nada e a auditoria acusava fatura fantasma; o admin concluindo o mesmo trabalho deixava NONE. O dashboard também passou a tratar DRAFT sem fatura como não faturado.

  • Suprimentos informados pela equipe vão para POST /api/field/shopping-list (funcionária escalada na visita, ou gerente), mesclados na lista do cliente por nome do item, com gravação condicional à versão do cliente. Antes iam para /atomic/clients, que só aceita gerente, e a recusa era engolida.

  • Ocorrências podem ser registradas pela funcionária escalada também antes do check-in e depois de concluir: nesses casos o servidor grava só as ocorrências, e só acrescentando (remover uma é recusado).

  • Adicionar alguém à visita a partir de uma ocorrência recalcula a logística para a nova equipe (ProfitLogic.calculateLogistics); antes reaproveitava os custos antigos e a folha pagava a primeira pessoa inteira e a segunda por cima.

  • Editar o preço de uma série não altera ocorrências pagas, reembolsadas ou já em fatura enviada.

  • Removidos: POST /api/field/supplies-alert (sem autenticação, sem nenhuma tela usando; devolvia nome e telefone do cliente e disparava e-mail do nosso domínio) e indicatePaymentConfirmation (sem chamadas; o cliente informa pagamento por /api/payments/transfer-claim).

  • Finish visit — o escritório fecha pela equipe (2026-09-29). o menu da visita no Full Schedule (Finish visit) e Issues (Mark as done) abrem FinishVisitModal (openFinishVisit, host em AppProviders) em vez de só mudar o status. Confirma em etapas (StepCard): quem trabalhou e as horas de cada um (passos de 15 minutos; as horas cobradas do cliente são outro controle, também de 15 minutos, e podem ser maiores que a soma da equipe — o preço por hora acompanha essas horas, a folha acompanha as horas de cada pessoa; carpete só escolhe quem, é comissão; visitas com preço travado mantêm o valor), início e fim (o check-in/out da equipe fica se o horário não mudou; senão grava como isForcedOverride com o nome do gerente), pago à equipe (só em visita de dinheiro/conta de funcionário não paga: recebido ou ainda não, quem recebeu e como — /api/field/collect aceita o gerente com collectorId da equipe) e algo a relatar (incidente, extras do cliente e despesas da equipe pelo AdditionalItemsEditor — travados se faturada/paga — e a nota). Uma gravação só leva a visita a DONE (finishVisitPatch, managerFinish.ts), porque DONE é final; o pagamento vem depois pelo seu endpoint, e nada é anunciado antes do servidor aceitar. Quando o saldo do cliente não pode ser lido (GET /api/field/collect: fatura em rascunho/revisão, dados de cobrança ou créditos a revisar — nesta visita ou numa anterior não paga do mesmo cliente), a resposta diz o motivo e a visita que o causou (T26-0042: Review pending invoices…, CollectionBalanceError), e o Finish visit e a revisão da equipe mostram isso abaixo de “Could not check the client balance”; erro inesperado continua genérico e vai para o log. O saldo só trava o botão quando a finalização vai registrar um pagamento (dinheiro/conta com a escolha feita, ou “recebido”); uma visita por transferência sem pagamento a registrar fecha mesmo sem saldo.

  • O dia operacional no Full Schedule → Day (2026-10-08; antes, a aba Live Board). Um menu de botão direito só para a visita, na semana, no dia e na janela do dia de uma pessoa (PlannerContextMenu): Open visit; sem equipe, a sugestão do ranking (StaffMatchingService.getRankedMatches, não num dia passado) que abre o Team selection com a pessoa marcada; o que o estado pede (liveActionsFor, ações de useLiveVisit): visita ainda não começada (por vir ou atrasada, hoje ou deixada aberta num dia passado) → Check in now (pelo mesmo caminho do app da equipe, recordGeoPoint, com confirmação; grava isForcedOverride com o nome do gerente e o ponto da visita; só SCHEDULED, nunca num dia futuro) e Finish visit, e, atrasada hoje, Tell the client (o aviso de atraso, TransitDelayModal); no local → Check out, que é o Finish visit (o único fechamento do escritório); depois Edit task, Change team, Duplicate, Chat e Cancel. Na pessoa (nome): Open day — a janela do dia (PersonDaySheet, via usePersonDay, com mapa, rota, troca de pessoa e de dia) —, Add task, Open profile (People). O botão de mapa no canto da linha do tempo do Day abre o dia em página cheia ao lado do sidebar (ScheduleDayMap → DayMapSheet, regras em dayMapModel.ts). No topo, as pílulas de estado com a contagem — tocar numa mostra só aquele estado — e a rota de alguém sobre o dia (as outras visitas ficam apagadas e o mapa enquadra a rota; também ao tocar na pessoa no mapa ou na lista). Botão direito num pino ou numa pessoa abre os mesmos menus. Ao lado: o card da visita escolhida com quem está mais perto e livre (o ranking do Team selection, três nomes, Assign); Precisa de ação (atrasada; pode atrasar — posição ao vivo + deslocamento estimado até a próxima visita nas próximas 90 min passa do início; check-in longe do endereço; passa do turno; sem equipe), cada linha centraliza a visita no mapa; Equipe (visto há X min, cinza com posição de 15 min ou mais, onde está e até quando, próxima visita com a distância e o atraso previsto em vermelho); Fora do mapa (visitas sem coordenadas, com Corrigir endereço → o cadastro do cliente). Quem tem a última posição fora do Reino Unido (caixa do UK em inUk) não é colocado no mapa, aparece como Fora da área e nunca é sugerido como o mais perto. Hoje, a equipe ao vivo: a lista de staff é relida a cada minuto enquanto a aba está visível (a posição chega com o ping do rastreador: 50 m ou 5 min); a rota de uma pessoa passou para a janela do dia.