Skip to content

Módulo 1 - Orçamento Público & Captura de Leads (PublicQuote)

Módulo 1: Orçamento Público & Captura de Leads (PublicQuote)

Section titled “Módulo 1: Orçamento Público & Captura de Leads (PublicQuote)”

Estado actual — horário do gestor. When would you like it? tem três semanas, no orçamento público e no do gestor: As soon as possible é a semana corrente, sem data; Next week e The week after mostram o from da segunda. Na opção Quote de New task, o mesmo seletor inclui “Specific day and time” (também no carpete). Essa escolha esconde manhã, tarde e flexível e mostra o dia e a hora em Londres; voltar a uma semana mostra o período e larga o horário. Esse horário acompanha os detalhes e inicia a confirmação; Book now conserva-o. Sem ele, a semana e o período bastam. O orçamento público continua só com semana e período. Na janela do escritório (New visit), Book now e Quote seguem a mesma sequência e o mesmo visual: When would you like it? → How often? → o que define tamanho e preço (cômodos no Quote; equipe e Billing model no Book now) → Anything else we should know? → Invoice through → o banner azul Live estimate (LiveEstimateBanner, com “Net … + VAT (20%) … · Client pays …” ou “No VAT · Client pays …”) → o botão no fim da página, não fixo no rodapé. Todo título de seção é SheetSectionTitle (ícone azul + nome em negrito, como “Day, team and price”); no Quote os números das etapas viram ícones e os cartões somem (OfficeQuoteLayout), sem caixa dentro de caixa. How often? é a mesma lista (FrequencyRadioList) nas duas. No Quote a empresa começa na Prime Cleaners com VAT (na falta dela, a primeira na ordem fiscal), podendo ser trocada; o estimate espera o resto das respostas (com dia específico, a hora). No computador, New task mantém a altura da janela estável, com rolagem interna ao abrir extras; expandir carpete não recentraliza a janela para cima. Ao expandir o extra de carpete, nomes longos e atalhos quebram linha e os controles de quantidade ficam dentro da largura da janela, inclusive no celular. Os extras Add property cleaning e carpet usam título de seção e CFCheckbox, sem cartão externo ou interruptor próprio; a empresa grava em lead_quotes.fiscal_entity_id (0240) e a confirmação abre nela. No Book now, Anything else we should know? substitui o Quote summary e vai para a tarefa como quoteSummary; na confirmação de um quote existente, após Agendamento, o grupo financeiro reúne Billing model (horas e tarifa ou preço fixo), Invoice through e forma de pagamento. No fim, Quote summary (ou os comentários no Book now) precede o banner azul Live estimate com horas, preço líquido, VAT e total do cliente; a mensagem de confirmação fica recolhida dentro de Agendamento. O painel não tem caixa externa envolvendo os blocos; os grupos de pedido, agendamento e cobrança conservam seus cartões e títulos dos campos, sem os cabeçalhos repetidos Request details, Scheduling e Billing; escolher um horário recolhe as sugestões de dia. O banner final destaca o total e confere data, frequência e equipe, antes de Approve & book (Book now mantém Confirm booking). O orçamento público e o do cliente não mudam: estimate no meio e Get my free quote.

Estado actual — preço e wizard. Deep Cleaning e End of Tenancy não têm limite máximo de horas no orçamento, na confirmação ou na nova visita do gestor; as horas representam o esforço total da equipe (por exemplo, 10 pessoas × 6 h = 60 h). O mínimo continua em 0,25 h e os demais serviços mantêm o limite de 24 h. O detalhe do orçamento rola por baixo do cabeçalho, com as abas Details e Chat (a conversa do lead, sem ícone no cabeçalho). O preço final ao cliente não se edita à mão: a duração e “Adjust price per hour” são a negociação, e o preço passa a ser essa tarifa vezes as horas. A visita fica com essas horas (estimatedEffort) e a tarifa em negotiatedHourlyRate. No carpete a duração só muda o bloco da visita. Os quick presets do wizard abrem em Custom no fim da lista (0 quartos / 0 casas de banho; carpete sem itens); Custom fica seleccionado quando a casa não coincide com um preset, e o orçamento não avança com 0 cômodos — um tamanho de casa é uma escolha e não se copia para o carpete.

Estado actual — endereço. Na confirmação do quote pelo gestor, Preference, Address e Property size formam um único cartão inicial branco, com ícones azuis e divisórias suaves, seguindo os detalhes da tarefa, antes do segundo grupo, Agendamento (dia e hora → frequência → sugestões de melhor dia → melhores funcionários, com análise da série quando recorrente); quartos e banheiros vêm desse endereço no cadastro do cliente ou lead, sem usar os cômodos de outra casa. No carpete, esses cômodos são apenas referência da casa: Quote summary lista os itens e quantidades selecionados para o serviço, independentemente do tamanho do imóvel. A busca por postcode preenche rua e cidade como sugestões editáveis, mesmo quando o mapa associa a rua a um postcode vizinho; o postcode validado é mantido. A rua só fica vazia e obrigatória quando o mapa não encontra uma sugestão. Nos formulários do escritório, o mapa começa recolhido: Ver mapa expande e carrega o mapa para confirmar a casa pelo pino; Ocultar mapa recolhe novamente. Assim, a rolagem do formulário não é capturada pelo mapa antes de abri-lo.

Estado actual — lead e área. O wizard público grava lead + cotação OPEN em /api/leads/chat-initiate (rascunho e envio convergem no mesmo telefone). Cliente e service_request só existem depois da confirmação administrativa. VAT e entidade fiscal entram nessa confirmação. No cadastro do cliente o email é opcional; se preenchido, tem de ser um endereço válido. A Service Area aceita áreas/distritos cobertos e distritos excluídos; a exclusão tem prioridade (por exemplo, KT cobre a área toda exceto KT13). Relógio: Londres (src/shared/time/london.ts). Recusar abre um modal com motivo opcional (até 2.000 caracteres); a nota automática no chat guarda esse motivo e a autoria do gestor autenticado. Se confirmar ou recusar for recusado, semana, período e equipe ficam, e o erro aparece junto ao botão.

Estado actual — fila. O chat empilha todas as cotações abertas do contato, incluindo serviços distintos como carpet e standard, e cada barra abre seu próprio orçamento. Ao confirmar, o painel recarrega a janela de pedidos (loadConfirmedBooking) antes de gravar equipe, fim e recorrência — o pedido nasce no servidor e o updateRequest ignora uma linha que a store não tem; quem abriu a fila pelo dashboard volta para ele, os demais vão para Operações. Na fila do gestor, cada widget usa o mesmo card que o board (22rem auto-fill, serviço debaixo da data, chat imediatamente à esquerda da seta); Recusados e Reservados têm o mesmo cabeçalho de secção e não repetem o estado no card. Cada grupo mostra as últimas 24 (DASHBOARD_GROUP_PAGE_SIZE) com “Show more”, como o board. Abrir um recusado só mostra o painel; Rever é que o reabre. O card reservado mostra data/hora, duração, equipe e o resumo da visita; o detalhe abre o mesmo bloco de resumo acima da checklist. Abrir uma visita reservada não muda de ecrã: fecha-se e volta-se à fila. A semente no chat é WIDGET_HANDOFF com o texto do wa.me; inbound WhatsApp com o mesmo texto (refs PC- ignoradas) promove essa linha para WHATSAPP + wamid em vez de duplicar a bolha. O cartão da fila marca Cliente ou Lead: quando a cotação é de um cliente já cadastrado (símbolo Client na lista), a lista e o boot resolvem o nome pelo client_id, o chat e a entidade fiscal inicial seguem esse cliente, a nova visita desse cliente grava a quote com a tarifa do cadastro ou a do serviço, e a nova visita do gestor abre o fecho e cria a visita sem quote aberta.

Estado actual — fecho. Revisão de 2026-09-25: a quote do cliente avisa o escritório com o mesmo push da quote de lead (notifyQuoteRaised) e aparece para o cliente no Dashboard (“Visits you asked for”, ClientPendingQuotes; o boot devolve ao CLIENT as quotes com o seu client_id); o painel do Chatwoot e o Inbox encontram a quote pelo dono (client_id ou lead_id). O fecho envia as horas e a forma de pagamento, e a visita nasce numa só escrita com preço, VAT, empresa, dia e pagamento (bookQuotedVisit → createQuoteRequest({ booking })); um dia de Londres que já passou é recusado (422 PAST_VISIT_DATE) e a quote volta a OPEN. Abaixo da empresa, “How the client pays” usa o mesmo seletor do Editar tarefa (PaymentMethodPicker): as rotas da empresa escolhida, a do cliente só enquanto é a empresa dele (Madrid abre em dinheiro); a frequência fica no grupo de agendamento, logo após dia e hora; horas e tarifa vêm depois desse grupo. Nova visita do gestor (ManagerVisitSheet, /api/atomic/visits/book): o cliente é digitado (nome, apelido ou telefone) com sugestões e, no fim da lista, “Add “nome” as a new client” — só essa escolha cria cliente, e um telefone que já é de um cliente agenda nesse cliente; o serviço começa vazio; o endereço é um do cadastro, corrigido pelo lápis (grava no próprio endereço) ou um novo (busca por postcode, UKAddressAutocomplete; coordenadas pelo postcode); se o cliente tem quote aberta, a folha mostra-a para ser respondida em vez de agendar outra; a busca lista também as quotes abertas de leads que batem com o nome ou telefone digitado (“Open the request”). A quote aberta dali herda o dia, a hora e a pessoa do vago clicado no Full Schedule (initialStart/initialCrewIds). Nesse modo o painel não mostra cabeçalho de quote, “Sent”, “expired” nem preferência; carpete sem tarifa própria começa sem preço. Os preços do wizard mostram pence (roundPence), como a quote grava. Um lead que toque em “nova visita” (busca) vai para o pedido de lead.

O fecho prepara cliente novo, endereço, visita e estado da quote antes de gravá-los num batch D1. Se a gravação falhar, nenhum desses dados parciais permanece; uma falha posterior ao commit não reabre uma quote já reservada.

O módulo PublicQuote é a porta de entrada de novos clientes para o Prime Crown. Trata-se de um wizard público interativo que calcula estimativas de limpeza residencial com precisão e converte visitantes em leads qualificados no sistema.

O indicador de progresso preserva contraste AA também nos passos inativos. O link da marca possui nome acessível alinhado ao texto visível “Prime Crown Cleaning Services”, mantendo toque, reconhecimento de voz e leitores de tela equivalentes em navegador, PWA e WebViews nativas.


sequenceDiagram
    autonumber
    actor Client as Cliente (Web)
    participant Step1 as Passo 1: Endereço & Cobertura
    participant Step2 as Passo 2: Detalhes da Casa
    participant Step3 as Passo 3: Resultado & Frequência
    participant API as /api/leads/chat-initiate
    participant D1 as Cloudflare D1

    Client->>Step1: Digita Postcode e seleciona endereço
    Step1->>Step2: Valida área de cobertura (ServiceArea)
    Client->>Step2: Seleciona quartos, banheiros e adicionais (Addons)
    Step2->>Step3: Calcula preço e exibe descontos de frequência
    Client->>Step3: Preenche Nome + E-mail/WhatsApp
    Step3->>API: POST com quote + issueGuestToken false
    API->>D1: Lead + canal + lead_quote OPEN
    Note over API,D1: Não cria cliente nem service_request
    API-->>Client: Confirma recebimento sem criar sessão JWT

🧮 2. Regras e Fórmulas de Cálculo de Preço

Section titled “🧮 2. Regras e Fórmulas de Cálculo de Preço”

O cálculo de estimativa utiliza a seguinte lógica de formação de preço:

  1. Preço Base do Serviço: $$\text{Custo Base} = \text{Preço Fixo da Categoria} + (\text{Quartos} \times \text{Taxa Quarto}) + (\text{Banheiros} \times \text{Taxa Banheiro})$$

  2. Horas Estimadas: $$\text{Horas} = \text{Horas Base} + (\text{Metragem} \times 0.015)$$

  3. Desconto por Frequência:

    • Semanal (Weekly): 20% de desconto recorrente.
    • Quinzenal (Bi-weekly): 10% de desconto recorrente.
    • Mensal (Monthly) / Avulsa (One-off): Preço padrão sem desconto.
  4. Addons (Serviços Adicionais):

    • Limpeza de Forno, Geladeira, Passadoria de Roupas ou Limpeza de Janelas Internas são somados ao valor total.

  • Página Principal: src/pages/PublicQuote/index.tsx
  • Componente de Resultado: src/pages/PublicQuote/StepQuoteResult.tsx
  • Endereço e Cobertura: src/pages/PublicQuote/StepAddressForm.tsx
  • Backend Handler: functions/api/leads/chat-initiate.ts
  • Contrato de Cotação: functions/api/leads/leadQuote.ts
  • Confirmação: functions/api/leads/confirmLeadQuote.ts
  • Fila Administrativa: src/pages/Quotes.tsx
  • Pedido Autenticado (cliente e lead): src/components/booking/ClientQuoteWizard.tsx → functions/api/atomic/client-quotes.ts
  • Quartos no endereço (2026-10-21, migração 0225): cada endereço guarda bedrooms e bathrooms. Toda quote num endereço grava a resposta mais recente (app do cliente/lead em /atomic/client-quotes, formulário público em chat-initiate) — só quando os dois contadores vêm e não são ambos zero (houseRoomsOf); a quote pública de um cliente atualiza só um endereço que ele já tem (rememberRooms, nunca cria linha). O escritório edita os dois no endereço do cliente (ClientAddressManager); a lista de endereços mostra “3 bed · 2 bath” e o formulário de quote começa desses números (StepServiceForm houseRooms).
  • Pedido em aberto (2026-10-21): no Dashboard, “Visits you asked for” → See abre ClientQuoteSheet (com vários pedidos, uma lista; cada linha abre o seu): estimativa, endereço, frequência, semana e período pedidos, e as ações Change day or time (WeekPeriodPicker, o mesmo da remarcação), Change the details (o formulário de novo: o mesmo serviço atualiza o pedido) e Withdraw this request (com confirmação). POST /api/atomic/client-quotes/:id aceita WHEN e WITHDRAW só do dono e só com a quote OPEN (409 para o resto); retirar é a recusa normal (declineLeadQuote) com a nota interna “Withdrawn by the client.” na conversa.

🔄 4. Lead, cotação e cliente são estados distintos

Section titled “🔄 4. Lead, cotação e cliente são estados distintos”

O visitante permanece em leads enquanto apenas solicita um preço. A intenção comercial vive em lead_quotes, com estado OPEN, CONFIRMED ou DECLINED. Reenviar o formulário atualiza a única cotação aberta daquele lead; um índice parcial único no D1 também faz dois envios simultâneos do mesmo serviço convergirem nessa linha. Decisões anteriores continuam como histórico.

O autosave de rascunho e o envio final podem chegar ao servidor em paralelo — por exemplo, se o navegador já tiver iniciado o rascunho quando a pessoa toca em enviar. chat-initiate usa um insert condicional atômico por telefone normalizado e resolve novamente a identidade após a gravação. Assim os dois pedidos convergem no mesmo lead, canal DIRECT e cotação, sem depender de um refresh do browser ou de uma limpeza posterior.

Somente a confirmação administrativa cria ou reutiliza uma linha em clients e materializa o service_request. O gestor escolhe a entidade fiscal e pode ajustar o preço final; VAT é calculado nesse momento porque depende da entidade que faturará. A confirmação também marca o lead como convertido e move contas cujo reference_type era LEAD para o cliente resultante. A recusa não cria cliente nem atendimento e cancela follow-ups comerciais pendentes.

Na promoção manual pela tela Leads, o cadastro do cliente é confirmado primeiro e seu ID exato segue para a conversão. Na promoção legada disparada por alocação, usa-se o cliente que já pertence à tarefa. A store nunca fabrica um segundo cliente: o backend move/consolida o canal no destino informado. Uma única operação por lead é aceita em cada instante; repetições compartilham a promise e destinos conflitantes são denunciados. Se a conversão falhar, somente o objeto otimista daquela tentativa é revertido, sem apagar edições paralelas em outros leads.

Equipe escolhida na confirmação. Escolher a equipe na quote é a confirmação da visita: o anchor sai SCHEDULED, com manualLaborCosts e financials.cost calculados por ProfitLogic.calculateStaffPayouts (horas por pessoa × wageForService) e lucro = preço fechado − custo, como no Team selection. Antes ficava PENDING com a equipe, fora de todas as listas do Operations.

Quote summary. Na revisão, o resumo (cômodos, frequência e extras que o cliente descreveu, lead_quotes.detail_lines_json) é um campo de texto editável: o gestor justifica ali qualquer mudança de escopo ou preço. Na confirmação ele vai em summary (uma linha por item; sem summary, vale o do cliente), fica gravado na cotação e vira service_requests.quote_summary (migration 0150), exibido no card “Quote summary” dos detalhes da tarefa e no painel de tarefa do chat. As visitas de uma série herdam o resumo (createChildOccurrence e recurrence-auto-extend). A equipe vê o resumo; o cliente não (redactRequestForViewer). Antes o texto ia para feedback, que é o campo da avaliação do cliente, e o formulário de avaliação abria preenchido com ele.

Na revisão, o preço final é um campo decimal obrigatório e editável — não um snapshot somente leitura. Total, VAT e mensagem de confirmação acompanham a edição. Confirmar e recusar aguardam a resposta autoritativa antes do feedback e atualizam a cotação local para que voltar à fila não ressuscite uma linha já decidida. A identificação de recorrência usa createUuid, sem Math.random, mantendo o mesmo contrato criptográfico em navegador, PWA e WebViews iOS/Android.

Confirmar e recusar compartilham um lock síncrono adquirido antes da primeira chamada remota, impedindo dois comandos ou ações cruzadas antes do próximo render. O composer de WhatsApp usa CFInput e Button, bloqueia edição/restauração durante o envio e adquire seu próprio lock antes de abrir a confirmação. A mensagem é aparada e capturada naquele momento; somente o texto efetivamente aprovado segue ao canal do lead, sem dois diálogos ou payload que muda durante a decisão. A prévia de confirmação e o texto livre usam o nome do serviço diretamente (por exemplo, “your Standard Cleaning is confirmed”). Fora da janela de 24 h, o WhatsApp usa o template aprovado na Meta. Todos os horários de clientes e agendamentos respeitam estritamente o fuso de Londres (Europe/London via src/shared/time/london.ts): a hora de envio da quote (quote.createdAt) é exibida em horário de Londres nos cards da fila e no painel, e a persistência de horário para o banco converte o horário comercial de Londres para UTC sem distorção quando o gestor opera de outros fusos (como no Brasil).

4.1. Operação Integrada de Cotações, Leads e Conversas

Section titled “4.1. Operação Integrada de Cotações, Leads e Conversas”

A esteira operacional conecta cotações abertas, leads e atendimento por chat de ponta a ponta:

  • Atalhos de Chat: Tanto na lista de cotações abertas quanto no modal de confirmação (QuoteConfirmationPanel), o gestor tem acesso direto ao botão de chat para falar com o lead ou cliente instantaneamente via WhatsApp/Chat interno.
  • Grade da fila e alternância de visualização: a barra de ferramentas oferece alternância entre o modo de cartões (QuoteCard em PagedWidgetGrid, padrão com foco nas tarefas) e o modo de tabela responsiva, preservando a preferência do operador via readUiPreference/writeUiPreference. Na grade, as colunas seguem o board (auto-fill com piso de 22rem).
  • Card da fila (QuoteCard): a fila separa Property cleaning e Carpet cleaning com o mesmo cabeçalho de seção do board (DashboardSectionHeader). No topo do card fica um único selo com a data e hora exatas de entrada (Londres) e a idade em dias corridos de Londres (quoteAgeDays em quoteAge.ts), colorido pela idade: até 1 dia verde, 2–4 amarelo, 5 ou mais vermelho — a faixa colorida do topo usa a mesma cor. O tipo de serviço fica imediatamente abaixo dessa data, como no card de tarefa, e o nome ocupa a largura toda. Cada widget estica à altura da linha da grelha (h-full). Abertos vêm do mais antigo para o mais novo (byArrival); Recusados e Reservados, do mais recente (byNewestArrival), 24 por página com “Show more” (PagedWidgetGrid, o mesmo piso do board). Cômodos, extras e itens de carpete (detailLines) aparecem no bloco data/morada, como o quoteSummary no card da visita. Quem é carpet é decidido por isCarpetQuote (id ou nome do serviço), a mesma regra nos grupos, no filtro do gestor de carpet e no badge da sidebar. O rodapé tem o chat à esquerda e a seta de abrir à direita, como no card de tarefa; o card inteiro abre a cotação. O painel de revisão mantém o aviso Expired (+14 days).
  • Vínculo Direto de Reserva: Recusados e Reservados são grupos com o mesmo cabeçalho do board. O card reservado e a tabela desktop leem a visita (startDateTime, duração, equipe e valor da visita): a tabela exibe a data agendada, o horário de término e os chips da equipe (AssignedStaffChips), e o botão de ação passa a ser “Ver Tarefa” (quotes.viewTask), abrindo a visita diretamente (TaskActionRegistry) em vez do botão de rever. Fechar a visita deixa o gestor na fila.
  • Status de Cotação nos Cards de Lead: O painel de Leads (LeadCard) exibe pílulas contextuais de cotação ativa com tipo de serviço e valor monetário, botão de chat direto e atalho para a ferramenta de mesclagem.
  • Mesclagem de Leads (MergeLeadsModal): Permite aos operadores consolidar um lead duplicado num outro lead ou num cliente já cadastrado (mergeTargets.ts: sugestões pelo mesmo número em qualquer formato — normalizePhoneIdentifier ou os 8 últimos dígitos — ou nome parecido; a busca acha o número digitado como 07…, +44 … ou sem espaços). Destino lead: PATCH /api/atomic/leads?action=merge, migrando cotações, mensagens e canais e marcando o duplicado com merged_into_id. Destino cliente: o mesmo vínculo da seção Duplicates (convertLeadToClient), e o lead passa a ser histórico do cliente. Um cliente nunca se funde com outro cliente (tarifas próprias; o mesmo número forma grupo de contato).

4.2. Nova Cotação Criada pelo Gestor — a mesma janela da New visit (2026-10-27)

Section titled “4.2. Nova Cotação Criada pelo Gestor — a mesma janela da New visit (2026-10-27)”

O gestor não tem mais uma janela própria de orçamento: New visit (ManagerVisitSheet) cria a visita ou o orçamento, escolhido só no último passo, porque muitas vezes ele só decide ali (cliente que já conhece → agenda; cliente novo → orçamento). A ManagerQuoteSheet foi apagada.

  • Passos: 1 Cliente (clientes e leads ativos, ou contato novo) → 2 Endereço (AddressStep) → 3 Serviço → 4 Book now | Send quote (abas no topo do passo).
    • Book now: o QuoteConfirmationPanel com bookDirect, como sempre (dia, hora, equipe, horas, preço, repetição, empresa).
    • Send quote: ManagerQuoteBranch — o formulário do site (StepServiceForm / StepCarpetQuoteForm, paridade total com o cliente), com o preço da tarifa sobre as horas do formulário (carpete, pelo catálogo, no servidor); sem campo próprio de horas e preço (tirado em 2026-10-27: o formulário já decide). Com o endereço já tendo os cômodos guardados, o passo How many rooms? vem recolhido numa linha (“3 bedrooms · 2 bathrooms”, Change abre os contadores); e, ao lado do Live estimate, a média de horas cobradas das últimas três visitas feitas desse serviço nesse endereço (pastVisitHours) — só referência, o valor continua sendo o dos cômodos. O mesmo vale no app do cliente (ClientQuoteWizard), que lê só as visitas que o app carregou (as fechadas dos últimos 14 dias e as ainda devidas). Contato novo vira lead (newLead). Após salvar, Send quote abre uma janela de envio (AdaptiveBottomSheet) sobre New task para revisar a mensagem (incluindo os dois serviços quando houver), com opção de abrir o WhatsApp Business; o envio é confirmado pelo gestor no WhatsApp. Fechar é explícito, sem criar novamente o orçamento.
  • Carpete é sempre orçamento (branchFor): com um serviço de carpete as abas somem e o passo 4 é o formulário de orçamento.
  • Lado sugerido (branchFor, só o destaque inicial; a escolha do gestor vale depois): aberta por New quote → orçamento; clique num horário vazio do Full Schedule → agendar; cliente com alguma visita não cancelada no app → agendar; lead, contato novo ou cliente sem visita → orçamento.
  • Troca com dados (newVisitCarry.ts): horas, preço, repetição, resumo (detailLines) e dia passam de um lado ao outro; o dia vira a semana (a segunda-feira de Londres, ou “o quanto antes” fora das três semanas oferecidas) e o período (antes do meio-dia manhã, depois tarde); a semana e o período do orçamento seguem como preferência no painel de agendar. Trocar o serviço no passo 3 zera o que foi carregado.
  • Pontos de entrada com o orçamento em destaque (initialBranch="QUOTE"): Quotes (+ New quote), cabeçalho da conversa, menu da bolha e menu da lista de conversas (estes passam o channelId).
  • Persistência Backend (POST /api/atomic/leadQuotes):
    • Autenticação restrita a administradores e gestores (ADMIN / MANAGER).
    • Suporta clientId, leadId ou newLead.
    • Garante e associa o endereço no cadastro do contato via ensureOwnerAddress. Os cômodos contados (bedrooms/bathrooms) ficam no endereço: num endereço novo pela criação, num já cadastrado por rememberRooms — o próximo orçamento ali já abre com eles recolhidos.
    • Cria o orçamento em lead_quotes com status = 'OPEN' e salva companion quotes de carpete quando aplicável.
    • Se originado a partir de uma conversa (channelId), anota uma nota interna (INTERNAL_NOTE) de handoff na conversa informando que a cotação foi levantada pelo gestor.
    • Atualiza o store em tempo real (upsertLeadQuote), refletindo a nova cotação na fila e nos badges de notificação.

Dentro do app, cliente e lead pedem pelo mesmo formulário (ClientQuoteWizard, POST /api/atomic/client-quotes) e veem a mesma tela inicial; um pedido novo de quem já é cliente também é uma quote. A única diferença é o preço: o cliente usa a sua tarifa por hora; o lead, a do serviço (o preço inicial ainda está em negociação). O dono vem da sessão, nunca do corpo. O passo do endereço é o mesmo da criação de tarefa (AddressStep): um do cadastro de endereços da pessoa ou um novo, achado pelo postcode (newAddress), que entra no cadastro na hora.

Cadastro único de endereços (0215). Lead e cliente usam a mesma tabela addresses (owner_type LEAD ou CLIENT, functions/api/common/addressBook.ts). O endereço de cada quote do lead (site, WhatsApp ou app, em createLeadQuote) e o que o escritório digita no registro do lead entram no cadastro dele, sem repetir. Quando o lead vira cliente — confirmação da quote, conversão manual, vínculo pelo WhatsApp ou Chatwoot — todas as linhas passam para o cliente (moveLeadAddresses): a que o cliente já tem não se duplica e o endereço padrão dele continua o padrão; na fusão de dois leads vão para o que fica. A visita confirmada fica no endereço da quote, nunca no primeiro do cadastro. Apagar ou anonimizar o lead apaga os endereços dele. O boot entrega o cadastro do lead em leads[].addresses. Website e aplicativo alimentam a mesma fila Quotes.

As telas de lead/cotação usam os primitives oficiais (PageHeader, Card, Button, CFInput, CFPillSelector, CFEmptyState e IconBadge) e superfícies claras responsivas. Envio de cotação tem lock síncrono contra toque duplo; o formulário do app limita o POST e devolve o formulário ao estado recuperável em caso de falha.

No wizard público, a preferência de semana usa CFSelect sem perder o picker nativo do sistema e as observações usam CFInput multilinha com o limite autoritativo de 500 caracteres. As opções de semana são computadas no calendário local para evitar desvios entre UTC e fuso do cliente. Manhã, tarde e horário flexível formam um grupo nomeado e publicam o estado pressionado, tornando a mesma seleção compreensível por teclado, TalkBack e VoiceOver em PWA, Android, iOS e desktop. Na confirmação do gestor, SlotSuggestionService e QuoteConfirmationPanel usam parseDate e ancoragem em segunda-feira para manter as sugestões de melhores slots rigorosamente dentro da semana indicada pelo lead. A opção 1 é o slot com mais faxineiros livres no turno (depois mais fora de turno, depois o mais cedo), contando só quem pode ir — EMPLOYEE, ou especialistas em carpete num orçamento de carpete; não pesa distância, cliente preferido nem lucro. O painel abre já com ela no campo de data, de modo que “Who is going” (ranqueado para um horário) aparece de imediato; o gestor troca livremente. Com um dia no campo (escolhido, digitado ou vindo da opção 1), as três opções passam a ser os melhores horários daquele dia (day no SlotSuggestionService; ainda dentro da manhã/tarde pedida, domingo incluído porque o escritório o escolheu) e o título diz “Best times on ”; só o dia conta, então mudar a hora não as reordena; dia sem horário restante mostra “No time left on this day”; limpar a data volta às opções da semana. Smart Rebalance (planRebalance, rebalancePlanner.ts): só para o horário escolhido (não ao ranquear os candidatos) e só para uma faxineira escolhida em “Who is going” que esteja ocupada — ou para qualquer uma quando ninguém está livre. Para a visita no caminho pesa duas saídas e mostra a melhor, até três: cobrir (outra faxineira assume a visita no mesmo horário — prefere a habitual do cliente, o que desfaz uma troca anterior; depois quem já foi lá; evita tirar a habitual; nunca alguém escolhido para a visita nova) ou mover (no mesmo dia e período, entre 8h e 18h, só em hora cheia ou meia hora (:00/:30, nunca 10:45), a menor mudança primeiro e perto dos horários de costume do cliente, com toda a equipe daquela visita livre). Visita já movida uma vez (recurrence.slot, ou fora da hora do anchorStart) não é movida de novo; iniciada, com horário prometido (expectedArrivalAt) ou a menos de uma hora não é tocada. Só sugere o que de fato deixa a faxineira livre. Cada sugestão diz o porquê (habitual do cliente, N visitas lá, horário de costume, pequena mudança). Cada sugestão tem seu botão (“Move it to 11:30”, “Give it to Bia”): o clique aplica pelo mesmo caminho do Full Schedule (planMove confere contra o quadro de agora, useApplyMove grava por rescheduleRequest e confirmAllocation, só aquela visita da série) e o resultado aparece ao lado (ActionResult). Distância (travelFit.ts): encaixar entre visitas perto é o principal critério. Nas opções, cada horário mede o menor deslocamento de uma faxineira livre a partir da visita dela logo antes ou até a logo depois, no mesmo dia (neighbourFit); a ordem é: alguém livre → menor deslocamento (sem visita em volta conta como 30 min) → mais cobertura → mais cedo, e o cartão diz “18 min from Ana at Mariana before”. No rebalance, contam o deslocamento de quem cobre até a visita que assume e o da faxineira liberada até a visita nova (travelBonus). Na week view (QuoteWeekAgendaSheet), com uma hora já escolhida, tocar um espaço verde de outro dia muda só o dia e mantém a hora; o faxineiro entra na equipe só se aquele espaço comporta o job nessa hora. Dias passados aparecem cinza (“Past”), sem espaços para tocar, e a seta não volta para antes da semana atual. Para cada horário (e frequência) o “Who is going” já vem com o melhor do ranking que está livre (numa série, o que cobre todas as visitas); ninguém se nenhum estiver. Ranking avulso: calculateStaffScore (disponibilidade, histórico com o cliente, avaliações, carga do dia/semana, deslocamento, equilíbrio de horas); série: visitas cobertas, depois deslocamento. Quando o gestor escolhe ou tira alguém, a pré-seleção para. O painel não mostra lucro nem margem projetados: não mudam a decisão de horário e equipe.

Os incrementos de quartos, duração de adicionais e ajuste final de tempo preservam os ícones compactos no desktop, mas usam touch-target para atingir 44×44 px em telas coarse/touch. Cada ação possui nome contextual (“Increase bedroom quantity”, “Decrease oven duration”, por exemplo), e o seletor de adicional publica aria-pressed; o mesmo controle permanece operável por polegar, teclado, TalkBack e VoiceOver.

As escolhas de tipo de serviço e frequência também publicam aria-pressed em cada opção. Assim, gradiente, borda e círculo continuam compondo a aparência visual, mas leitores de tela recebem a mesma seleção que usuários de mouse ou toque enxergam.

Catálogos, configuração e rascunho podem resolver em ordens diferentes, sobretudo em rede móvel. O corpo do wizard sincroniza novamente as durações mínimas dos adicionais quando o catálogo chega depois da seleção e recalcula o piso de progresso quando o serviço chega depois do rascunho. A sincronização só eleva mínimos e progresso: não reduz uma duração maior escolhida pelo visitante nem substitui sua escolha atual. quoteAsyncSync.test.ts protege essas condições para navegador, PWA e WebViews.

A revelação progressiva usa um único timeout substituível para scroll. Seleções rápidas cancelam o salto anterior antes de apontar para a etapa atual, e desmontagem cancela a navegação pendente; o wizard não volta visualmente para uma pergunta antiga depois que a pessoa já avançou em touch, teclado ou mouse.

Todas as chamadas do wizard usam o transporte limitado compartilhado por /quote, /pay, /statement, /proposal, /rate e pelas operações autenticadas que adotam a mesma primitiva. Leituras encerram em 12 segundos e mutações em 15 segundos. O chat-initiate espera os pushes do escritório antes de responder; o badge de cada push (visibleUnreadNotifications) lê os canais dos não lidos de uma vez (fetchInChunks) — um a um, com centenas de grupos por gestor, levava ~45 s e o orçamento caía em “The request timed out” (2026-10-13), embora gravado. Trocar de tela ou desmontar a WebView aborta catálogo, cálculo, rascunho e envio final; locks síncronos impedem duplo toque antes que o estado React seja renderizado. Uma falha de catálogo oferece Try again, enquanto cálculo e confirmação retornam ao estado interativo com mensagem de erro. O mesmo contrato vale para navegador, PWA, desktop e WebViews Android/iOS.

Tempo do carpet fica oculto. O tempo no local de carpet ainda não é nosso de definir, então não aparece: sem campo nem “min on site” no catálogo (Services & prices), sem labor-hrs, sem horário de término no card da tarefa nem nos detalhes (só o início) e sem “estimated completion” para o cliente. carpet_cleaning_items.duration_minutes continua guardado (itens novos recebem o padrão 30 do servidor) e só dimensiona o bloco da visita na agenda — soma dos itens, mínimo de 1h, em meias horas —, para a escala não sobrepor visitas.

O catálogo administrativo de preços de carpetes segue o mesmo contrato. A leitura mais nova cancela a anterior e somente ela pode publicar a lista; carregamento, falha com snapshot preservado e vazio confirmado são estados distintos. Salvar e excluir usam limite de 15 segundos, cancelamento no teardown e um lock síncrono único adquirido antes da confirmação de exclusão. Enquanto uma mutação está em voo, edição, exclusão e fechamento do formulário ficam indisponíveis e anunciam o estado ocupado; falha mantém o formulário ou item autoritativo e oferece retry explícito, sem falso sucesso em nenhuma das quatro superfícies.

Não há atalho «Can’t find your address? Enter manually»: o endereço só é digitado à mão quando o postcode é completo (isUkPostcode, com ou sem espaço: um bloco de fora no formato de district seguido de 3 caracteres) e esse primeiro bloco — sempre tudo antes dos 3 últimos caracteres (KT5ZZZ → KT5, SW209JZ → SW20) — está coberto, mas a base (postcodes.io) não o conhece ou não respondeu. O aviso, em âmbar, diz que o postcode não foi encontrado (ou não pôde ser verificado), pede para conferir a digitação e informa que atendemos os postcodes que começam pelo district coberto (coveringDistrict, ex.: KT5). Postcode incompleto, inventado («LONDON») ou fora da cobertura fica em erro, sem entrada manual; o campo Postcode da entrada manual mostra erro e invalida o passo se for alterado para algo assim.

O seletor compartilhado de endereço também reconcilia cobertura nos dois sentidos quando a lista de districts resolve: um postcode pode passar de fora da área para coberto sem nova digitação, e os indicadores de validação/completude acompanham a decisão atual. O Reset possui uma única fronteira de callback, evitando desmontar e limpar o wizard duas vezes em uma ativação por toque, teclado ou leitor de tela.

Lookup de postcode e refinamento geográfico são operações latest-wins: uma nova busca, Reset ou desmontagem aborta a anterior e invalida qualquer resposta tardia. O postcode possui teto de 12 segundos e o refinamento, 8 segundos; timeout retorna o formulário ao estado de erro recuperável em vez de deixá-lo preso em loading. O cleanup reabre o gate da busca automática durante a simulação do React StrictMode, preservando o mesmo comportamento em desenvolvimento e produção.

A rua e a cidade que a busca encontra são um palpite pelo centro do postcode: com o endereço encontrado, Street / Road e Town / Area ficam editáveis ao lado do número da casa, e as coordenadas são refinadas pelo que a pessoa digitou. Quando o mapa responde com a rua de outro postcode, a sugestão continua preenchida com aviso para conferir a propriedade, mantendo o postcode validado; só a ausência de rua exige digitação manual. Nos formulários do escritório (pinMap: cliente, funcionário, lead, endereço da tarefa e Nova visita do gestor) aparece um mapa (AddressPinMap, carregado só ali, nunca na quote pública): tocar ou arrastar o pino grava aquele ponto e preenche rua e cidade daquele lugar; o postcode buscado fica enquanto o pino está a até 150 m do seu centro (o centro mais próximo costuma ser de um vizinho), senão vira o postcode mais próximo. Um endereço reaberto mantém o ponto salvo, e a Nova visita envia o ponto (addressFields.lat/lng), que o servidor grava em vez do centro do postcode.

what3words do endereço (2026-10-12). Nos formulários de endereço de cliente do escritório (cadastro do cliente e o seletor de endereço da visita), abaixo do mapa do pino, há um campo what3words: o componente AutoSuggest oficial (@what3words/javascript-components, carregado sob demanda em What3wordsField, nunca no orçamento público), que pergunta por /api/w3w — a chave W3W_API_KEY fica no servidor, o país é sempre GB e só o AutoSuggest passa (o plano Free da conta não converte palavras em ponto nem ponto em palavras; testado em 2026-10-12: convert-to-3wa 402, convert-to-coordinates 401). Por isso as palavras não movem o pino: as sugestões vêm ordenadas perto dele e um aviso aparece se a escolhida fica a mais de 1 km. Só uma sugestão escolhida é salva (w3wAddress); digitar outra coisa apaga. A visita mostra ///palavras como link w3w.co, lido ao vivo do endereço como as notas de acesso (resolveTaskAddress).

4.3. Nome de pessoa padronizado (2026-11-06)

Section titled “4.3. Nome de pessoa padronizado (2026-11-06)”

Todo nome de cliente ou lead que chega ao servidor passa por normalizePersonName (src/shared/personName.ts): cada palavra digitada toda em maiúsculas (ou o nome inteiro em minúsculas) é gravada com só a primeira letra maiúscula (“MARIA DA SILVA” → “Maria da Silva”, “Laurence BOUCHER” → “Laurence Boucher”; hífen e apóstrofo abrem palavra; da/de/do/dos/das/e/van/von ficam minúsculas depois da primeira). Uma palavra que já mistura maiúsculas e minúsculas (“McDonald”) e uma inicial ficam como foram digitadas. Vale no cadastro do escritório (/atomic/clients, /atomic/leads), na nova visita e na quote do gestor, no orçamento público (chat-initiate), no call-me-back, no primeiro acesso (verify-profile) e no nome de perfil do WhatsApp (sanitizePushName). Um nome antigo em maiúsculas corrige-se ao salvar o cadastro.

O passo de confirmação não abre o chat de convidado. Por isso envia issueGuestToken: false: o backend conclui a captura, cria/atualiza o lead, o canal operacional e a cotação, mas não gera nem devolve um JWT desnecessário. A interface também não grava token ou channelId em sessionStorage. Outros consumidores de chat-initiate continuam recebendo o token por padrão quando realmente usam chat-messages.

Quote e Contact Us no widget do site gravam o lead (ou associam ao cliente existente via createClientQuote) mais a mensagem inicial no canal interno com source: WIDGET_HANDOFF e o texto exacto do wa.me. Em telemóvel abre wa.me no WhatsApp do visitante no toque (reserveExternalWindow). Em computador (DeviceService.isStrictDesktop, e a cópia no widget.js: sem UA de telemóvel, iOS/Android ou nativo, e ponteiro principal fino — nunca pela largura da janela, tela touch do portátil ou app instalado, que abriam o WhatsApp Web), não abre aba de surpresa: a tela de confirmação garante que o pedido foi recebido pela equipe e oferece QR Code para escanear com a câmera do telemóvel (mais atalho para WhatsApp Web). Em telemóvel e touch, nunca exibe QR Code e mantém o botão de toque direto. Por isso o número e o modelo vêm antes, de GET /api/public/whatsapp-handoff (público, CORS da allowlist, cache de 5 min), e o link é montado com resolveWidgetWhatsAppHandoff — o mesmo do servidor, então a semente continua a coincidir — no orçamento, e com a cópia inline no widget.js no Contact Us; o chat-initiate segue em paralelo (keepalive no widget e no envio do orçamento) e roda no servidor dentro de waitUntil: com o WhatsApp aberto, o celular manda a página para o fundo e corta o pedido, e sem isso a desconexão cancelava o Worker depois da cotação e antes da mensagem semente (corrigido em 2026-10-08; o rascunho não grava mensagem nenhuma). Sem esse config, o toque no celular reserva uma aba (reserveExternalWindow, com “Opening…” em vez de branco) que recebe o link da resposta. A tela de confirmação mantém o botão do WhatsApp para o browser que recusar mesmo assim. Quando o visitante envia esse texto, o inbound promove a semente para WHATSAPP (wamid, janela de 24 h) em vez de uma segunda bolha — refs PC- do Contact Us não contam na comparação. Nada é enviado automaticamente: o visitante escreve primeiro.

Live Chat no widget (Chatwoot). A opção Live Chat (controlada pela flag ENABLE_LIVE_CHAT no widget.js, desativada por padrão) integra o SDK do Chatwoot (chatwoot.caraivaexclusiva.com.br, inbox de website) e mostra o #cw-widget-holder dentro da janela do widget quando ativa: o iframe do Chatwoot nasce em #/messages em vez da tela inicial (a inbox não tem pré-chat). O iframe renderiza a 100% de altura dentro do corpo do widget (top: 0, bottom: 0, min-height: 100%), garantindo que a caixa de texto de digitação permaneça sempre fixada no rodapé e que tanto a conversa quanto a tela de resumo/histórico do chat fiquem totalmente visíveis abaixo do cabeçalho. O SDK só abre depois de o iframe /widget do Chatwoot avisar que carregou ($chatwoot.hasLoaded); até lá o widget mostra o spinner e, após 12 s, oferece o WhatsApp. a montagem só acontece depois de a janela estar no documento (o SDK procura o iframe com getElementById e lança erro se não o achar, o que interrompia o render() e deixava só o fundo desfocado); render() devolve o holder ao <body> antes de redesenhar, e o botão de fechar do Chatwoot (chatwoot:closed) volta ao menu. Para o iframe carregar, o proxy do Chatwoot (NPMplus no G11, npm.xframe=upstream) não pode enviar X-Frame-Options na /widget, e a zona caraivaexclusiva.com.br tem uma Configuration Rule que desliga o RUM (Web Analytics) no host do Chatwoot: o beacon injetado segura o DOMContentLoaded do widget quando a rede do visitante pendura esse domínio. Quando a flag está desativada, a opção é omitida do menu e atalhos de chat recaem suavemente no canal do WhatsApp.

O que o escritório vê quando a mensagem não chega (2026-10-14). A mensagem no WhatsApp é do visitante — ele precisa apertar enviar. Para não ficar no escuro, o envio do orçamento grava uma nota interna (INTERNAL_NOTE, nunca vai ao cliente) na conversa DIRECT: de que aparelho veio, pelo User-Agent (describeDevice em functions/api/leads/quoteHandoffNote.ts: telemóvel/computador/tablet, sistema, navegador, incluindo os navegadores internos do Instagram/Facebook), e qual caminho a página deu (handoff: OPENED_WHATSAPP no telemóvel, SHOWED_QR no computador). A resposta traz um handoffTapToken (escopo handoff de linkToken.ts, 24 h, assina o canal); tocar no botão “Open WhatsApp” / “Open WhatsApp Web” da confirmação chama POST /api/leads/handoff-tap (CORS da allowlist, rate limit, sem await no toque) e grava outra nota, uma só por 30 min. Escanear o QR acontece noutro aparelho e não é visto — a prova aí é a mensagem quando chega.

Qual WhatsApp abre. O orçamento força o WhatsApp pessoal, com um botão só. No Android, fora do app nativo, o toque de envio e o botão da confirmação usam um intent com o pacote com.whatsapp e o próprio wa.me como browser_fallback_url se ele não estiver instalado (src/pages/PublicQuote/personalWhatsApp.ts); quem navega é a janela de cima, porque o widget mostra o orçamento num iframe. No iPhone não há como forçar (os dois apps respondem aos mesmos links e o iOS escolhe), então lá fica o wa.me. Em 2026-10-14 chegou a ir ao ar um par de botões “WhatsApp” / “WhatsApp Business”; foi retirado no mesmo dia — dois botões confundem o cliente. Dentro do app é o contrário: todo link de WhatsApp força o Business (src/shared/whatsappBusiness.ts), porque o gestor responde por lá quando a janela de 24 h está fechada.

chat-initiate usa a allowlist CORS compartilhada. Navegadores são aceitos somente nos domínios oficiais, previews HTTPS controlados do Pages, desenvolvimento local e origins padrão do Capacitor; uma origem desconhecida recebe 403 antes de criar registros ou consultar o provedor de WhatsApp. Chamadas backend sem cabeçalho Origin continuam disponíveis para integrações confiáveis, e Vary: Origin evita que caches misturem decisões.

Clientes HTTP diretos passam ainda pelo rate limiter D1 antes do payload: chat-initiate permite 5 tentativas em 15 minutos por marcador de cliente e endpoint. Excesso retorna 429 com Retry-After, sem criar lead, canal ou mensagem nem consultar WhatsApp. O endereço recebido do edge é persistido somente como SHA-256; entradas expiradas são removidas dentro da própria janela.

Falhas internas desses endpoints não revelam mensagens do D1 ou stack ao formulário, PWA ou shells. chat-initiate grava a exceção pelo helper sanitizado e retorna uma orientação estável para revisar/tentar novamente.

Depois da captura, os CRUDs autenticados de leads, serviços, adicionais, descontos por frequência e área de atendimento usam o contrato atômico seguro. Uma falha inesperada de persistência é investigável em system_logs, mas não muda de forma entre desktop, PWA e shells nativos nem revela detalhes do D1.

Toda a superfície /api/public/* usada pelo orçamento aplica também publicServerError. Carregamento de serviços/adicionais, criação de lead e cálculo usam saídas protegidas: falhas do D1 e ausência de configuração fiscal ficam na telemetria sanitizada, enquanto o visitante recebe somente uma orientação estável de nova tentativa. Validações 400 e conflitos 409 continuam específicos. As antigas rotas de conversão pública direta foram removidas; somente a confirmação autenticada da cotação converte lead em cliente. Respostas bem-sucedidas de catálogo preservam seu cache público; erros não são armazenados.

/api/leads/chat-initiate identifica o visitante pelo telefone digitado. Quando o número é de um cliente existente, o canal é a conversa privada desse cliente com a gerência. Por isso:

  • Token de chat de convidado: só é emitido quando pedido (issueGuestToken, padrão false). Nem o orçamento público nem o widget.js usam esse token.
  • /api/leads/chat-messages: devolve só as mensagens a partir da emissão do token, nunca uma INTERNAL_NOTE. Antes, qualquer pessoa que soubesse o número lia a conversa inteira do cliente, notas internas incluídas.
  • Dados do cliente: o formulário não troca o nome de um cliente com nome confirmado e não retira o consentimento de WhatsApp. Pode concedê-lo, mas não revogá-lo.
  • Recusa de orçamento: só vale para cotação aberta, e a rota responde 409 caso contrário. Um toque atrasado numa cotação já confirmada a marcava como recusada e punha uma nota de “recusado” na conversa do cliente novo.
  • Rever orçamento recusado: abrir o card só lê. Revise no painel chama POST /atomic/leadQuotes/:id/reopen (admin/gestor), que volta DECLINED → OPEN numa instrução só e deixa o mesmo painel para precificar (preço, data, equipe, mensagem). Responde 409 se a cotação não estiver recusada ou se o lead já tiver outra aberta do mesmo serviço — o reenvio do formulário pode tê-la criado, e o índice admite uma por serviço. Deixa a nota interna “Quote reopened for revision.” na conversa, sem reativar follow-ups.
  • Confirmação de orçamento: reserva a cotação antes de gravar (UPDATE … WHERE status = 'OPEN' RETURNING) e a libera em caso de falha. Duas confirmações simultâneas criavam dois clientes.
  • Proposta de horário:
    • o horário é de Londres (londonWallClock), validado estritamente;
    • um link que carrega from é recusado se a visita já foi movida;
    • visita em andamento não pode ser remarcada.
  • Extrato público: não lista faturas em rascunho.
  • Cálculo do orçamento: deduplica e limita a 50 os ids recebidos, porque o D1 recusa mais de 100 parâmetros.

Pendências conhecidas:

  • Botões de WhatsApp (templates da Meta com respostas rápidas) para a proposta e a avaliação: próximo passo, depende da aprovação dos templates. As páginas continuam sendo o destino deles.

Página pública de avaliação: com 5★ o agradecimento mostra o botão “Review us on Google” e o cliente decide se vai — nada abre sozinho, para não parecer insistente.

Link de avaliação no Google: vem de uma constante só, GOOGLE_REVIEW_URL em src/shared/googleReview.ts, que aponta para primecrowncleaning.co.uk/review: uma página do site (repo prime-crown-cleaning, public/review.html) com preview próprio no WhatsApp (título, descrição e imagem og/review.jpg) que leva a pessoa à ficha da Prime Crown no Google Maps, na aba de avaliações — abre sem login; o Google só pede a conta se ela tocar em “Write a review” (o formulário direto writereview exigia login antes de mostrar qualquer coisa). As cinco cópias que ela substituiu mandavam o cliente avaliar outra empresa: duas usavam o place id de exemplo da documentação do Google (o escritório de Sydney) e três usavam links g.page não verificados. tests/googleReviewLink.test.ts recusa um link de avaliação escrito direto no código.

/api/client-links (só ADMIN/MANAGER) assina o link e o coloca na conversa do cliente com sendSystemWhatsApp, então ele sai pelo WhatsApp como qualquer mensagem. O link só abre aquele registro, naquela página, até expirar. Quem o tiver abre sem login, por isso quem gera é sempre a gerência.

Botão Onde Validade Página
Send statement cadastro do cliente 30 dias /statement/<token>: faturas enviadas, totais, dados bancários
Ask the client to rate this visit visita concluída ainda sem nota 14 dias /rate?token=: uma nota só, apenas para visita concluída
Reschedule (do manager; antes “Propose a new time to the client”) detalhes da visita (pendente, agendada ou em revisão); é o único Reschedule do manager — o de mover direto ficou só para o cliente até o fim do dia proposto, no máximo 7 dias /proposal?token=: aceitar ou manter o horário

Aceitar ou recusar a proposta vira uma nota interna (INTERNAL_NOTE) na conversa do cliente. Antes, a recusa não chegava a ninguém.

🏷️ 8. Fila de Orçamentos e Badge na Sidebar

Section titled “🏷️ 8. Fila de Orçamentos e Badge na Sidebar”

A barra lateral de navegação exibe no item Quotes um indicador visual numérico (badge) com a quantidade de orçamentos em aberto (status === 'OPEN'). O cálculo é imediato e reativo através do store compartilhado:

  • Para administradores e gerentes gerais, o badge reflete todas as solicitações abertas de limpeza e carpete aguardando precificação/decisão.
  • Para o gestor dedicado de Carpet Cleaning (isCarpetManager), o badge filtra estritamente os orçamentos do serviço de carpete (st-carpet), mantendo paridade com a visualização filtrada da fila na página Quotes.