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:
- Afinidade Prévia (40%): Histórico de limpezas bem-sucedidas no mesmo cliente.
- Proximidade Geográfica (40%): Distância em km entre a residência da funcionária e o imóvel.
- Preferência de Idioma (20%): Idioma de comunicação em comum entre a equipe e o cliente.
🛠️ 2. Arquivos Principais do Módulo
Section titled “🛠️ 2. Arquivos Principais do Módulo”- 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.tsxeChecklistItemRow.tsxoferecem janela universal (PhotoSourceModal) para escolha entre Tirar foto (câmera) ou Escolher da galeria, enviando ao R2 comAbortSignal, 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, bancoprime-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_tagsguarda o portador (holder_id), a passagem pendente (pending_to_id) e o estado (HELD/LOST/RETURNED, migração 0191); cada mudança gravalast_event_*e os triggers copiam o evento parakey_custody_recordscom 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,expectedVersione 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, ouFOUNDse 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: 409HOLDS_KEYSem/atomic/employeese o mesmo aviso noStaffProfile). Na alocação (Batch/Split route),keyHolderMismatchavisa 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. OMyKeysCardpermite 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/employeestrata o papel EMPLOYEE antes do schema do gerente, só para o próprio id e só peloownUpdateSchema: 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 exigianamee 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 eGET /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 ememployee_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/formatBankDetailsJsonem modoasTyped, 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, idsupply-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, devolveWINDOW_CLOSEDcom 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/incidentsacrescenta 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 usamCFSelect,CFInput,IconBadgeeButton, com seleçõesaria-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 únicoAbortController, é 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.
🔑 5. Instruções de acesso
Section titled “🔑 5. Instruções de acesso”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.
Revisão 2026-09-11
Section titled “Revisão 2026-09-11”-
Concluir não fatura. Ao finalizar a visita,
paymentStatusficaNONE. Antes, a conclusão pela funcionária marcavaDRAFT(“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 deixavaNONE. O dashboard também passou a tratarDRAFTsem 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) eindicatePaymentConfirmation(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 emAppProviders) 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 comoisForcedOverridecom 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/collectaceita o gerente comcollectorIdda equipe) e algo a relatar (incidente, extras do cliente e despesas da equipe peloAdditionalItemsEditor— 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 deuseLiveVisit): 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; gravaisForcedOverridecom 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, viausePersonDay, 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 emdayMapModel.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 eminUk) 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.