5. Regras de Negócio Seção 5
As regras de negócio definem as restrições, fórmulas, automações e validações que governam o comportamento do sistema independentemente da interface.
5.1 Cadastro e Gestão de Leads (RN-001 a RN-010)
RN-001Status permitidos e transições de estadoCrítico
Regra
Um lead de licenciamento pode assumir apenas três status: Ativo, Convertido ou Perdido. As transições são restritas conforme a tabela abaixo:
| De | Para | Quem pode | Efeito colateral |
|---|---|---|---|
| Ativo | Convertido | Diretor / Comercial | Licenciado aparece no mapa, scorecard e painel de capacidade. Emissão de certificado obrigatória. |
| Ativo | Perdido | Comercial | Exige preenchimento obrigatório do campo "Motivo da perda". Lead sai do kanban para coluna "Perdido". |
| Convertido | Ativo | Diretor apenas | Licenciado removido da rede ativa. KPIs e certificado mantidos como histórico. |
| Perdido | Ativo | Comercial | Motivo da perda mantido no histórico. Lead retorna ao kanban na etapa em que estava. |
RN-002Unicidade do token de formulário
Regra
Cada lead possui no máximo um token de formulário ativo por vez. Ao gerar um novo link, o token anterior é substituído e o link antigo deixa de funcionar. O token tem 32 caracteres hexadecimais gerados por crypto.getRandomValues().
Implicação
- Links compartilhados anteriormente ficam inválidos após a regeneração
- O sistema exibe aviso claro sobre isso no modal de geração de link
RN-003Cálculo de m² disponívelCrítico
Fórmula
m² Disponível = area_total_m2 × (1 − utilizacao_capacidade / 100)
Regras
- O resultado nunca pode ser negativo — se o cálculo resultar em valor negativo, exibe 0 m²
- Licenciados sem
utilizacao_capacidaderegistrada no Scorecard são marcados como "Sem dados" — não aparecem como 100% disponíveis - O campo
area_total_m2é consolidado automaticamente como a soma das áreas de todos os armazéns cadastrados no lead
RN-004Geocodificação e prioridade de coordenadas
Hierarquia de precisão
| Prioridade | Fonte | Precisão | Condição |
|---|---|---|---|
| 1ª | BrasilAPI (CEP) | Endereço exato (rua) | CEP informado e válido |
| 2ª | Dicionário interno (80+ cidades) | Centro da cidade | polo_logistico reconhecido |
| 3ª | Capital do estado | Capital da UF | Apenas UF informada |
Quando coordenadas GPS são obtidas via CEP, é adicionado um offset aleatório de ±0,04° para evitar sobreposição exata de múltiplos pontos no mesmo endereço.
RN-005Cálculo e renovação do Score de Qualidade (Tier)Crítico
Recálculo
O score é calculado dinamicamente no frontend a cada carregamento, não é armazenado no banco. Isso garante que qualquer atualização nos dados do lead (ex.: nova certificação) reflita imediatamente no score sem processamento batch.
Reclassificação
- O tier pode melhorar (ex.: Bronze → Prata) quando o licenciado lança novos KPIs acima dos thresholds
- Downgrade (ex.: Ouro → Prata) ocorre quando KPIs registrados ficam abaixo dos mínimos
- Alerta automático "Risco de downgrade" é disparado quando OTIF cai >3% ou acuracidade cai >2% entre dois períodos consecutivos
RN-006Vinculação de fotos por armazém
Regra
Fotos de armazéns são armazenadas com tipo composto (foto_armazem_1, foto_armazem_2...) na tabela lic_anexos. Esta convenção garante rastreabilidade de qual foto pertence a qual armazém, mesmo que os armazéns sejam renomeados posteriormente.
Implicação
- A deleção de um armazém do formulário não remove as fotos vinculadas — elas permanecem no histórico
- O campo de preview no mapa usa a primeira foto do tipo
foto_armazem_%encontrada
RN-007Registro automático de eventos no histórico
Regra
O sistema registra automaticamente os seguintes eventos na tabela lic_historico, sem intervenção do usuário:
| Evento | Gatilho | Tipo registrado |
|---|---|---|
| Mudança de etapa no Kanban | Função _licKbMoverEtapa() | etapa_kanban |
| Avanço de auditoria | Função audAvancarEtapa() | auditoria_avanco |
| Emissão de certificado | Função emitirCertificado() | certificado_emitido |
| Lançamento de KPIs | Função salvarLicKpi() | kpi_lancado |
| Geração de link | Função licGerarLinkForm() | link_gerado |
| Formulário preenchido | Mudança de form_status → 'concluido' | formulario_preench |
RN-008Projeção de disponibilidade (3 e 6 meses)
Método de cálculo
A projeção usa regressão linear simples sobre os últimos 4 períodos registrados de m² disponível (calculado a partir de histórico de utilização no Scorecard). A fórmula extrai slope e intercept para projetar os próximos N meses.
Restrições
- Mínimo de 2 períodos registrados para ativar a projeção — com apenas 1 período, exibe linha plana
- O resultado nunca pode ser negativo (m² disponível projetado ≥ 0)
- A projeção é estritamente indicativa — não substitui análise de demanda real
5.2 Pipeline de Auditoria (RN-011 a RN-020)
RN-011Bloqueio de avanço de etapa por checklistCrítico
Regra
O botão "Avançar para próxima etapa" permanece desabilitado enquanto existir qualquer item do checklist da etapa atual desmarcado. O bloqueio é implementado tanto via CSS (cursor:not-allowed, opacidade reduzida) quanto via validação JavaScript antes de chamar a API.
Exceção
- Diretores podem forçar o avanço desconsiderando o checklist — funcionalidade reservada para situações excepcionais documentadas
RN-012Cálculo e exibição de SLA por etapa
Cálculo
dias_na_etapa = floor((hoje - etapa_iniciada_em) / 86400000)
| Status | Condição | Cor |
|---|---|---|
| No prazo | dias_na_etapa ≤ sla_dias × 0.7 | Verde |
| Atenção | dias_na_etapa > sla_dias × 0.7 | Âmbar |
| Vencido | dias_na_etapa > sla_dias | Vermelho |
RN-013Relatório de visita técnica obrigatório na etapa 4
Regra
A etapa "Visita Técnica" inclui no checklist o item "Relatório técnico elaborado e assinado". O sistema disponibiliza uma zona de upload de arquivo (PDF/DOC) integrada ao checklist. O auditor deve fazer upload do relatório para marcar este item como concluído.
Armazenamento
- Arquivo salvo em:
lic-anexos/leads/{id}/relatorio_visita/{timestamp}_{nome} - URL pública registrada em
lic_auditoria.relatorio_visita_url
RN-014Emissão de certificado ativa o licenciado na redeCrítico
Regra
A emissão do certificado digital é o único mecanismo que altera o status do lead de Ativo → Convertido de forma automática. Nenhuma outra ação no sistema produz essa transição de status sem intervenção explícita do usuário.
Efeitos cascata
- Lead aparece no mapa como marcador verde (Convertido)
- Lead entra no painel de Capacidade e Disponibilidade
- Score de qualidade passa a ser calculado e exibido
- KPIs podem ser lançados no Scorecard
- Alertas de renovação de certificado passam a ser monitorados
5.3 Scorecard de Performance (RN-021 a RN-030)
RN-021Ativação obrigatória do plano de remediação
Condições de ativação
O bloco de Plano de Remediação é exibido automaticamente no modal de lançamento de KPIs quando pelo menos uma das seguintes condições for verdadeira:
- Qualquer KPI inserido resultar em classificação Vermelho
- O licenciado sendo avaliado for do nível Bronze
Campos obrigatórios no plano
- Ações corretivas (texto livre)
- Data de início do plano
- Data prevista de resolução
RN-022Não sobreposição de KPIs no mesmo período
Regra
O sistema permite múltiplos registros no mesmo período (Q1 2026, por exemplo) para o mesmo lead — não há restrição de unicidade por período/lead. Isso possibilita correções e atualizações dentro do mesmo trimestre. O scorecard sempre exibe o registro mais recente por período ao calcular saúde e tendência.
5.4 Mapa e Disponibilidade (RN-031 a RN-040)
RN-031Alertas de capacidade e thresholdsCrítico
| Condição | Alerta | Ação sugerida |
|---|---|---|
| m² disponível < 500 | Crítico — Capacidade mínima | Notificar diretoria; prospectar novo licenciado na região |
| Utilização > 70% | Atenção — Alta ocupação | Monitorar; preparar alternativa regional |
| Utilização > 90% | Crítico — Capacidade esgotada | Não ofertar este licenciado para novos clientes |
RN-032Descarte de alertas via localStorage
Regra
Alertas descartados são salvos em localStorage com ID único no formato {tipo}_{leadId}_{AAAA-MM}. O sufixo AAAA-MM garante que o alerta reaparece no mês seguinte se a condição persistir — ou seja, o descarte é temporário (mensal), não permanente.
Exceção
- Alertas de tipo
FORM_PREENCHIDOexpiram naturalmente após 7 dias e não dependem de localStorage
6. Fluxos Operacionais Seção 6
6.1 Fluxo: Prospecção e Cadastro de Lead
1
Identificação do candidato
Comercial identifica um operador logístico com espaço ocioso através de indicação, evento, prospecção ativa ou LinkedIn. Dados básicos são levantados informalmente.
2
Criação do lead no sistema
Comercial acessa Pipeline → Licenciamento → "+ Novo Lead". Preenche minimamente: Razão Social (obrigatório) e e-mail do contato. Os demais campos podem ser preenchidos depois ou pelo próprio parceiro via portal.
3
Geração do link de portal (opcional)
Comercial clica em "Gerar link" → Sistema gera token único → Modal exibe link + QR Code → Comercial compartilha via WhatsApp ou e-mail com o candidato.
4
Preenchimento pelo parceiro (se link gerado)
Parceiro acessa portal.html?token=XXX → Tela de boas-vindas → Preenche 7 seções com auto-save → Faz upload de documentos → Clica "Enviar formulário" → Sistema registra form_status='concluido'. Alerta automático "Formulário preenchido" aparece para o Comercial.
5
Revisão e início da auditoria
Comercial revisa os dados preenchidos, acessa Auditoria → "+ Iniciar Auditoria" → Seleciona o lead → Define auditor responsável → Lead entra na etapa "Prospectado" do kanban de auditoria.
Fluxo alternativo — preenchimento interno: Se o comercial optar por preencher diretamente sem enviar link ao parceiro, todas as 11 seções do formulário interno podem ser preenchidas pela equipe Vendemmia. O fluxo segue do passo 5 sem o passo 3 e 4.
6.2 Fluxo: Preenchimento no Portal Público
1
Acesso ao link
Parceiro abre o link:
pipelinevendemmia.com.br/portal.html?token=TOKEN. Sistema valida o token no Supabase. Se inválido → tela de erro. Se já preenchido → tela de aviso com opção de editar.2
Tela de boas-vindas
Portal exibe nome da empresa (se já cadastrado), badge "Rede de Licenciamento Vendemmia", informações sobre o processo (10-15 min), badges de garantias (dados protegidos, salvo automaticamente, funciona no celular) e botão "Começar preenchimento".
3
Preenchimento das 7 seções
Parceiro navega pelas seções usando "Próximo →". A cada navegação, os dados são salvos automaticamente (form_status='preenchendo'). Barra de progresso atualiza em tempo real. CEP auto-preenche cidade, UF e endereço via BrasilAPI.
4
Upload de documentos
Nas seções 1, 4 e 7, o parceiro pode arrastar ou selecionar arquivos para upload (Contrato Social, fotos dos armazéns por armazém, certificados). Arquivos ficam pendentes até o submit final.
5
Envio final
Na seção 7, parceiro clica "✅ Enviar formulário". Sistema faz upload de todos os arquivos pendentes para o Storage, atualiza form_status='concluido' e form_filled_at no banco, exibe tela de agradecimento.
6.3 Fluxo: Auditoria Completa (Prospectado → Ativo)
P
Prospectado — SLA: 7 dias
Checklist: Contato inicial realizado; Informações básicas coletadas; Potencial de m² confirmado; Link do formulário enviado. Avançar quando: Todos 4 itens marcados.
F
Formulário Enviado — SLA: 14 dias
Checklist: Formulário preenchido; Contrato Social anexado; CNPJ validado; Capacidade de m² confirmada. Avançar quando: Todos 4 itens marcados.
D
Análise Documental — SLA: 10 dias
Checklist: Documentação jurídica aprovada; Certidões negativas OK; Situação fiscal regular; Certificações verificadas; Referências comerciais checadas. Avançar quando: Todos 5 itens marcados.
V
Visita Técnica — SLA: 21 dias
Checklist: Visita agendada; Estrutura física aprovada; AVCB verificado; m² confirmado in loco; WMS verificado; Fotos registradas; Relatório elaborado e assinado. Upload obrigatório: Relatório de visita técnica em PDF/DOC. Avançar quando: Todos 7 itens marcados e arquivo uploadado.
A
Aprovação — SLA: 14 dias
Checklist: Relatório aprovado pela diretoria; Plano de implantação definido; Contrato assinado; Número de licenciado atribuído. Avançar quando: Todos 4 itens marcados.
★
Ativo na Rede — Emissão de Certificado
Ação final: Usuário clica "Emitir Certificado" → Preenche número, data de emissão e validade → Sistema registra em
lic_auditoria, altera lead para status "Convertido" e registra evento no histórico. Licenciado passa a aparecer em toda a rede.6.4 Fluxo: Lançamento Trimestral de KPIs
1
Acesso ao Scorecard
Gestor acessa Licenciamento → Scorecard. Visualiza cards de todos os licenciados com status de saúde atual. Identifica licenciados sem KPIs ou com alertas.
2
Início do lançamento
Clica em "+ Lançar KPIs" no card do licenciado. Modal abre com período pré-selecionado (trimestre atual), valores do último período pré-preenchidos para facilitar atualização.
3
Preenchimento dos KPIs
Preenche os 6 KPIs. A cada valor digitado, o sistema verifica o threshold em tempo real e muda a cor dos campos. Se qualquer KPI ficar vermelho ou licenciado for Bronze, bloco de Plano de Remediação aparece automaticamente.
4
Salvamento
Clica "Salvar KPIs" → Sistema salva em
lic_performance → Atualiza otif_pct e acuracidade_pct no lead → Registra evento no histórico → Fecha modal → Cards do scorecard recarregam com novos semáforos.6.5 Fluxo: Match Comercial em Reunião de Vendas
1
Necessidade do cliente identificada
Durante reunião, cliente informa necessidade: ex. "Preciso de 3.000 m² refrigerados em SP e RS a partir de outubro".
2
Acesso à ferramenta de Match
Vendedor abre Pipeline → Licenciamento → Disponibilidade Comercial. Preenche: Estado(s) = SP + RS, m² mínimo = 3.000, tipo de carga = Refrigerado. Clica "Buscar".
3
Resultado em tempo real
Sistema exibe inline os licenciados compatíveis: nome, UF, polo logístico, m² disponível, tier badge e status de capacidade. Resultado ordenado por maior disponibilidade.
4
Apresentação e proposta
Vendedor apresenta as opções ao cliente diretamente na tela ou gera Board Report PDF para formalizar a proposta de cobertura da rede.
6.6 Fluxo: Gestão de Alertas Proativos
1
Detecção automática
A cada carregamento da tela de Licenciamento, o sistema varre todos os leads e detecta condições de alerta (certificados vencendo, ocupação alta, etc.). O badge no botão "Alertas" é atualizado com a contagem.
2
Visualização do painel
Usuário clica em "Alertas" → Painel lateral desliza da direita → Alertas agrupados por prioridade (Crítico / Atenção / Informação). Cada alerta mostra empresa, condição detectada e botão "Ver →".
3
Ação corretiva
Usuário clica "Ver →" para navegar diretamente à tela relevante (Auditoria, Scorecard, Disponibilidade ou formulário do lead). Toma a ação corretiva (renovar certificado, lançar KPIs, etc.).
4
Descarte do alerta
Após resolver ou reconhecer o alerta, clica "Dispensar" → Alerta removido da lista e salvo em localStorage. O alerta reaparece automaticamente no mês seguinte se a condição persistir.
7. Telas do Sistema Seção 7
7.1 Dashboard Principal (Tela Inicial)
Licenciamento → (tela inicial após navegar)
Objetivo
Consolidar em uma única visão todos os indicadores da rede de licenciamento, substituindo o dashboard separado e oferecendo acesso rápido a todas as funcionalidades do módulo.
Componentes da Tela
| Componente | Descrição | Dados |
|---|---|---|
| Header de navegação | Título + filtros de status (Todos/Ativo/Convertido/Perdido) + botões de módulo | Estático + contagem dinâmica |
| 4 KPI cards | Total de leads, Em negociação, Convertidos, Fee/mês total | Calculado de baseLicLeads |
| Evolução mensal | Gráfico de barras com novos leads e linha de convertidos por mês | created_at dos leads |
| Composição do pipeline | Donut de distribuição por status (Ativo/Convertido/Perdido) | Status dos leads |
| Funil de conversão | Barras horizontais por etapa do kanban com taxa de avanço | Campo etapa dos leads |
| Canal de origem | Barras horizontais por origem do lead | Campo origem dos leads |
| Mix de planos | Donut com distribuição Starter/Pro/Enterprise/Custom | Campo plano dos convertidos |
| Perdas por etapa | Barras de leads perdidos por etapa do kanban | Status + etapa |
| Motivos de perda | Ranking com barras de progresso | motivo_perda dos leads |
| m² por UF | Barras por estado | area_total_m2 dos convertidos |
| Receita projetada | Linha acumulada de 60 meses baseada no fee total atual | fee_mensal dos convertidos |
| Tabela de leads | Listagem com colunas: Empresa, UF, Plano, Etapa, m², Fee/mês, Responsável, Status, Nível, Ações | baseLicLeads filtrado |
Ações disponíveis
- Filtrar leads por status (chips Todos/Ativo/Convertido/Perdido)
- Abrir Mapa / Kanban / Capacidade / Disponibilidade / Scorecard / Auditoria / Board Report / Alertas
- Gerar link de formulário para qualquer lead
- Criar novo lead
- Editar (✏️), Gerar PDF (📄) e Excluir (🗑) qualquer lead da tabela
7.2 Formulário Interno do Lead (11 Seções)
Licenciamento → + Novo Lead / ✏️ Editar
Objetivo
Coletar e editar todos os dados de um candidato a licenciado, com navegação por stepper e auto-save a cada seção. Suporta criação e edição com pré-carregamento de dados existentes.
Estrutura do Formulário
| # | Seção | Campos Principais | Obrigatório |
|---|---|---|---|
| 1 | Dados da empresa | Razão social, CNPJ, website, faturamento, segmentos, Contrato Social (upload) | Razão social |
| 2 | Contato principal | Nome, cargo, e-mail, telefone, decisor | Nome + e-mail |
| 3 | Localização | CEP (geocod. automática), UF, polo logístico, logradouro, bairro, exclusividade | UF + polo |
| 4 | Capacidade instalada | Múltiplos armazéns (add/remove) + upload de fotos por armazém | — |
| 5 | Tipos de carga | Carga geral, perigosa (IMDG), temperatura, licenças, observações | — |
| 6 | Maturidade tecnológica | WMS, ERP, sistemas integrados, nível de maturidade | — |
| 7 | Certificações | Certificações, OTIF, acuracidade, upload de certificados | — |
| 8 | Planos comerciais | Seleção de plano (cards visuais), fee mensal, status, motivo de perda | — |
| 9 | Implantação WMS | Toggle Sim/Não + opções Senior ou API (com valores) | — |
| 10 | Funil de etapas | Seleção da etapa atual (6 opções de Prospecção a Onboarding) | — |
| 11 | Acompanhamento | Origem, datas de contato, próxima ação, responsável, observações | Responsável |
Comportamentos
- Barra de progresso de preenchimento atualiza dinamicamente no header
- Stepper no topo mostra etapas concluídas (verde ✓) e ativa (roxo com glow)
- Na etapa 11 o botão "Próximo" muda para "✅ Salvar lead" (verde)
- Botão "📄 Gerar PDF" aparece apenas no modo de edição (lead existente)
- Ao salvar, qualquer arquivo pendente é enviado ao Supabase Storage
7.3 Pipeline de Auditoria e Homologação
Licenciamento → Auditoria
Objetivo
Gerenciar o processo formal de homologação de candidatos a licenciados, com kanban visual de 6 etapas, checklists obrigatórios por etapa e SLA monitorado.
Componentes
| Componente | Descrição |
|---|---|
| Header escuro | Gradiente roxo com contagem de leads por etapa em mini-badges |
| Kanban de 6 colunas | Uma coluna por etapa; cards com: nome da empresa, tier badge, dias na etapa, barra de progresso do checklist, auditor responsável |
| Card de auditoria | Clicável → abre painel lateral. Exibe: semáforo de SLA (verde/âmbar/vermelho), progresso checklist (X/Y ✓) |
| Painel lateral | Stepper de 6 etapas; checklist interativo com persistência em tempo real; Upload de relatório (etapa 4); Notas livres; Botão "Avançar" (bloqueado até checklist completo); Seção de certificado (etapa 6) |
7.4 Scorecard de Performance
Licenciamento → Scorecard
Objetivo
Monitorar a saúde operacional de cada licenciado ativo através de KPIs trimestrais com semáforos visuais, histórico de evolução e gestão de planos de remediação.
Componentes
| Componente | Descrição |
|---|---|
| Banner de saúde da rede | Chips contando licenciados por categoria: ✅ Saudável · ⚠️ Atenção · 🔴 Crítico · ⚪ Sem dados |
| Filtros | Por nível (Platina/Ouro/Prata/Bronze) e por status de saúde |
| Grid de cards | Um card por licenciado com: 6 linhas de KPI com semáforo (🟢🟡🔴), tier badge, score visual, indicador de remediação ativa se aplicável |
| Modal de lançamento | Seletor de período (trimestre + ano), 6 campos numéricos com meta exibida, bloco de remediação condicional |
| Painel de histórico | Gráfico de linhas (OTIF + Acuracidade + NPS por período), tabela de todos os registros com semáforos, plano de remediação ativo |
7.5 Mapa Interativo da Rede
Licenciamento → Mapa
Objetivo
Visualizar geograficamente a cobertura da rede de licenciados com informações de disponibilidade, histórico e documentos acessíveis diretamente pelo mapa.
Componentes
| Componente | Descrição |
|---|---|
| Mapa base | CartoDB Voyager (colorido), zoom 3–14, controles posicionados no canto inferior direito |
| Choropleth de estados | 5 tons de roxo por intensidade de m². Clique no estado dá zoom na região |
| Marcadores (tags) | Tags retangulares com m² e UF; verde=Convertido, roxo=Ativo, vermelho=Perdido. Hover exibe popup com foto, dados e hint de clique |
| Hover popup | Foto do armazém (ou placeholder), nome, localização, m² disponível, fee/mês, badges de nível e status, hint "Clique para ver detalhes →" |
| Side panel (3 abas) | Dados: todos os campos do lead + armazéns + certificações. Histórico: timeline CRM completa. Documentos: lista de anexos com download |
| Barra de busca | Texto livre + filtros por UF, Plano e Status. Contador de resultados dinâmico |
| Gap Analysis | Modo alternativo: choropleth tricolor (verde/âmbar/vermelho) + painel com lista de estados sem cobertura |
| Painel lateral esquerdo | Totais da rede, m² por região (barras), top estados, legenda |
7.6 Disponibilidade Comercial
Licenciamento → Disponibilidade
Objetivo
Responder em segundos à pergunta "o que posso oferecer a um cliente agora?", com dados de disponibilidade real calculados a partir da utilização registrada no Scorecard.
Componentes
| Componente | Descrição |
|---|---|
| Hero escuro | 4 KPIs: m² Disponível Agora · Licenciados com espaço · Alertas de capacidade · Sem dados de utilização |
| Match comercial | Formulário de busca: estados (multi-select), m² mínimo, tipo de carga → resultado inline com licenciados compatíveis |
| m² por região | Gráfico de barras empilhadas (disponível vs. ocupado) por região geográfica |
| Alertas de capacidade | Lista de licenciados com >70% de ocupação, com barra visual e nível de criticidade |
| Por tipo de carga | Ranking de tipos de carga por número de licenciados habilitados e m² disponíveis |
| Projeção 3/6 meses | Gráfico de linha com histórico e projeção via regressão linear. Toggle 3/6 meses. Insight textual automático |
| Tabela detalhada | Todos os licenciados com m² total, % ocupado (barra visual), m² disponível, status de capacidade |
7.7 Portal Público de Preenchimento
pipelinevendemmia.com.br/portal.html?token=TOKEN
Objetivo
Oferecer ao candidato a licenciado uma interface exclusiva, sem autenticação, para preenchimento autônomo de dados operacionais. Funciona como onboarding digital do parceiro.
Telas do Portal
| Estado | Condição | Conteúdo exibido |
|---|---|---|
| Carregando | Sempre (validação do token) | Spinner animado em fundo gradiente roxo |
| Link inválido | Token não encontrado no banco | Card branco com mensagem e instrução para contatar o comercial Vendemmia |
| Já preenchido | form_status = 'concluido' | Card informativo com botão "Atualizar dados" |
| Boas-vindas | Token válido | Fundo escuro com orbs animados, badge Vendemmia, título, badges de garantias, botão CTA |
| Formulário | Após "Começar" | Topbar com logo + stepper 7 etapas + progresso + formulário centralizado (max-width 720px) |
| Agradecimento | Após submit final | Card branco com ícone ✅, mensagem personalizada com nome da empresa, badge de aguardar contato |
Recursos de UX
- Responsivo e funcional em smartphones
- CEP com auto-preenchimento (BrasilAPI + ViaCEP como fallback)
- Armazéns dinâmicos (add/remove) com upload de fotos individualizadas
- Progresso salvo automaticamente a cada etapa avançada
- Indicador de progresso de preenchimento na topbar
8. Casos de Uso Seção 8
UC-001Cadastrar e qualificar novo lead de licenciamento
Objetivo
Registrar um candidato a licenciado no sistema e iniciar o processo de qualificação com todas as informações operacionais necessárias.
Atores
- Ator primário: Comercial Vendemmia
- Ator secundário: Candidato a licenciado (opcional — via portal)
Pré-condições
- Usuário autenticado com acesso ao módulo Licenciamento
- Candidato identificado e contato inicial realizado
Fluxo principal
- 1. Comercial acessa Licenciamento → clica "+ Novo Lead"
- 2. Preenche Seção 1: Razão Social (obrigatório) e demais campos disponíveis
- 3. Navega pelas 11 seções preenchendo dados conhecidos
- 4. Na Seção 8, define o Plano estimado e fee mensal
- 5. Na Seção 11, registra a data de primeiro contato e responsável
- 6. Clica "✅ Salvar lead" — sistema salva e retorna à tela principal
- 7. Lead aparece na tabela com status "Ativo"
Fluxos alternativos
- FA-1 — Parceiro preenche via portal: Após passo 2, Comercial clica "Gerar link" e envia o link ao candidato. Candidato preenche via portal. Comercial revisa e completa campos comerciais (passo 4-5) que o parceiro não preenche.
- FA-2 — Salvar sem campos obrigatórios: Sistema exibe toast de erro e mantém o formulário aberto na seção com o campo obrigatório ausente.
Pós-condições
- Lead registrado em
lic_leadscom todos os dados informados - Evento "Prospecção iniciada" registrado em
lic_historico - Lead visível na tabela, no kanban e no mapa (se com coordenadas)
UC-002Gerar e enviar link de preenchimento ao parceiro
Objetivo
Criar um link exclusivo para que o candidato a licenciado preencha seus próprios dados operacionais sem intervenção da equipe Vendemmia.
Atores
- Ator primário: Comercial Vendemmia
- Ator beneficiário: Candidato a licenciado
Pré-condições
- Lead já cadastrado no sistema (pode ser com apenas o nome)
- Usuário autenticado com acesso ao módulo
Fluxo principal
- 1. Comercial clica em "🔗 Gerar link" (header) ou ícone 🔗 na linha do lead na tabela
- 2. Se via header: modal abre → seleciona lead existente OU digita nome para criar lead novo → clica "Gerar link agora"
- 3. Sistema gera token único (32 hex chars) via
crypto.getRandomValues() - 4. Token salvo em
lic_leads.form_token; form_status definido como 'pendente' - 5. Modal exibe: link copiável, QR Code (200×200), botão WhatsApp e botão E-mail
- 6. Comercial copia o link ou clica "WhatsApp" para compartilhar diretamente
Pós-condições
- Token único registrado no banco; link anterior (se existia) invalidado
- Evento "Link compartilhado" registrado no histórico do lead
UC-003Avançar etapa no Pipeline de Auditoria
Objetivo
Mover um lead de uma etapa do pipeline de auditoria para a próxima, após conclusão de todos os itens do checklist obrigatório.
Atores
- Ator primário: Auditor / Comercial
Pré-condições
- Lead com processo de auditoria aberto em
lic_auditoria - Usuário autenticado
Fluxo principal
- 1. Auditor acessa Auditoria → clica no card do lead
- 2. Painel lateral abre com checklist da etapa atual
- 3. Auditor marca cada item — cada marcação salva automaticamente no Supabase
- 4. Ao marcar o último item, botão "Avançar" fica habilitado e muda de cor
- 5. (Etapa 4 — Visita Técnica) Auditor faz upload do relatório antes de avançar
- 6. Auditor clica "Avançar para [próxima etapa]"
- 7. Sistema registra conclusão da etapa atual no histórico, define nova etapa e reinicia o contador de SLA
- 8. Painel fecha, kanban recarrega com lead na nova coluna
Fluxo alternativo
- FA-1: Tentativa de avançar com checklist incompleto → botão permanece desabilitado; mensagem exibe quantos itens faltam
Pós-condições
- Campo
estagio_atualatualizado emlic_auditoria - Histórico do lead atualizado com evento "Auditoria avançou"
- Card do lead exibido na nova coluna do kanban
UC-004Realizar match comercial para cliente em reunião
Objetivo
Identificar em tempo real quais licenciados da rede atendem aos requisitos de espaço, localização e tipo de carga de um cliente durante uma negociação.
Atores
- Ator primário: Comercial Vendemmia
Pré-condições
- Pelo menos 1 licenciado ativo (Convertido) com dados de utilização no Scorecard
- Usuário autenticado
Fluxo principal
- 1. Comercial acessa Disponibilidade Comercial → seção "Buscar disponibilidade"
- 2. Seleciona estados necessários (Ctrl+clique para múltiplos)
- 3. Informa m² mínimo e tipo de carga necessário
- 4. Clica "🔍 Buscar"
- 5. Sistema filtra licenciados convertidos com m² disponível ≥ ao mínimo e que atendem ao tipo de carga
- 6. Resultado exibido inline: nome, UF, m² disponível, tier badge, status de capacidade
- 7. Comercial apresenta opções ao cliente ou gera Board Report para formalizar proposta
Pós-condições
- Nenhuma alteração no banco — match é operação de leitura
- Comercial tem insumos para elaborar proposta comercial
UC-005Emitir certificado digital e ativar licenciado na rede
Objetivo
Formalizar a aprovação final de um candidato homologado emitindo o certificado digital Vendemmia e ativando-o como licenciado oficial da rede.
Atores
- Ator primário: Diretor ou Comercial autorizado
Pré-condições
- Lead com processo de auditoria na etapa "Ativo na Rede"
- Todos os itens do checklist da etapa 6 marcados
Fluxo principal
- 1. Usuário abre painel do lead na etapa "Ativo na Rede"
- 2. Clica "🏆 Emitir Certificado e Ativar"
- 3. Modal abre solicitando: número do certificado, data de emissão, data de validade
- 4. Usuário preenche e confirma
- 5. Sistema atualiza
lic_auditoriacom dados do certificado - 6. Sistema altera
lic_leads.statuspara "Convertido" - 7. Evento "Certificado emitido: VDM-2026-XXX" registrado no histórico
- 8. Lead passa a ser exibido como licenciado ativo em: Mapa, Capacidade, Disponibilidade, Scorecard, Board Report
Pós-condições
- Licenciado ativo em toda a rede Vendemmia
- Alerta automático de renovação de certificado monitorado para os próximos 24 meses
PIPELINE by Vendemmia
Especificação Funcional EF-LIC-2026-001 · Versão 1.0 · Fase 2 de 3
Confidencial — Vendemmia Comércio Internacional Ltda.
pipelinevendemmia.com.br · Maio 2026