Sumário Executivo
Este documento constitui a Especificação Funcional Completa do Módulo de Licenciamento integrado ao sistema Pipeline da Vendemmia Comércio Internacional Ltda. O módulo foi concebido para suportar a operação e expansão estratégica da Rede de Licenciamento Vendemmia — modelo de negócio no qual operadores logísticos com espaço ocioso tornam-se parceiros certificados, oferecendo capacidade de armazenagem sob a marca e padrões operacionais da Vendemmia.
O documento cobre, em três fases, todos os aspectos funcionais e técnicos necessários para operação, manutenção e evolução do sistema:
Confidencialidade: Este documento contém informações estratégicas e proprietárias da Vendemmia Comércio Internacional Ltda. Sua distribuição é restrita à diretoria, equipe de tecnologia e parceiros autorizados. Reprodução não autorizada é proibida.
1. Visão Geral Seção 1
1.1 Objetivo do Sistema
O Módulo de Licenciamento do Pipeline tem como objetivo central dar visibilidade operacional e estratégica ao time comercial e à diretoria da Vendemmia sobre todos os armazéns parceiros (licenciados) disponíveis na rede, incluindo sua localização geográfica, capacidade de armazenagem, nível de qualificação, performance operacional e status de negociação.
O sistema suporta o ciclo de vida completo de um parceiro logístico: desde a prospecção inicial, passando pelo processo formal de auditoria e homologação, até a operação ativa como licenciado certificado na rede Vendemmia.
1.2 Escopo do Sistema
O módulo abrange as seguintes capacidades funcionais:
| Domínio | Escopo Incluído | Escopo Excluído |
|---|---|---|
| Cadastro de Leads | Prospecção, formulário completo de 11 seções, portal público de preenchimento | Contratos jurídicos assinados digitalmente |
| Auditoria | Pipeline de 6 etapas, checklists, relatório de visita, certificação digital | Auditorias de campo com geolocalização em tempo real |
| Performance | Scorecard de KPIs por licenciado, histórico trimestral, planos de remediação | Integração automática com WMS/TMS dos parceiros |
| Mapa e Disponibilidade | Mapa interativo com choropleth, gap analysis, ferramenta de match comercial | Cálculo de rotas e otimização logística |
| Relatórios | Board Report PDF automático, histórico do lead, alertas e renovações | BI externo ou integração com Power BI/Tableau |
| Portal Público | Link de preenchimento por parceiro, upload de documentos, auto-save | Assinatura digital de contratos pelo parceiro |
1.3 Benefícios do Sistema
1.4 Problemas que o Sistema Resolve
2. Perfis de Usuário e Permissões Seção 2
O Módulo de Licenciamento opera com 4 perfis distintos. Os três primeiros são usuários internos autenticados na plataforma Pipeline; o quarto é o parceiro externo que acessa apenas o portal público via link exclusivo.
Acesso restrito por whitelist: O botão "Licenciamento" no menu principal do Pipeline é visível apenas para usuários cujos e-mails estão na lista de acesso autorizado (atualmente: gppereira@vendemmia.com.br e jprado@vendemmia.com.br). Novos usuários devem ser adicionados pela equipe técnica.
Usuário com visão estratégica completa da rede. Utiliza principalmente o Board Report, Mapa e Scorecard para tomada de decisão.
PERMISSÕES
- Visualizar todos os leads e licenciados
- Gerar Board Report PDF
- Aprovar etapas de auditoria
- Emitir certificados digitais
- Acessar scorecard e histórico completo
- Visualizar mapa e gap analysis
- Exportar dados e relatórios
RESTRIÇÕES
- Não altera configurações de acesso de outros usuários
- Não exclui registros históricos
Usuário principal do sistema. Prospecta novos parceiros, conduz o processo de auditoria, acompanha o kanban e gera links de formulário.
PERMISSÕES
- Criar, editar e excluir leads
- Gerar links de formulário para parceiros
- Mover leads no Kanban de Auditoria
- Registrar eventos no histórico (reuniões, contatos)
- Lançar KPIs no Scorecard
- Usar ferramenta de match comercial
- Gerar PDF individual do lead
- Acessar mapa e disponibilidade
RESTRIÇÕES
- Não emite certificados digitais
- Não acessa configurações de sistema
Responsável pela condução técnica do processo de homologação. Realiza visitas técnicas, completa checklists e faz upload de relatórios.
PERMISSÕES
- Visualizar todos os leads
- Completar checklists de auditoria
- Fazer upload de relatório de visita
- Avançar etapas após checklist completo
- Registrar notas e observações
- Visualizar scorecard e histórico
RESTRIÇÕES
- Não cria nem exclui leads
- Não gera relatórios executivos
- Não emite certificados
O candidato a licenciado recebe um link único por WhatsApp ou e-mail e acessa o portal público para preencher seus dados operacionais.
PERMISSÕES (no portal público)
- Preencher formulário de 11 seções
- Fazer upload de documentos (Contrato Social, fotos, certificados)
- Salvar progresso parcial e retornar depois
- Enviar formulário final
RESTRIÇÕES
- Não acessa o sistema Pipeline interno
- Visualiza apenas os dados do seu próprio lead
- Não pode editar após status "concluído" (sem autorização)
- Link único e intransferível por lead
3. Módulos do Sistema Seção 3
O Módulo de Licenciamento é composto por 9 sub-módulos integrados, cada um acessível pelo menu de navegação horizontal dentro da tela de Licenciamento:
| # | Módulo | Função Principal | Usuários Principais |
|---|---|---|---|
| 01 | Tela Inicial / Dashboard | Visão consolidada: KPIs, gráficos de evolução, funil de leads, receita projetada e tabela de todos os leads | Todos os perfis internos |
| 02 | Mapa Interativo | Visualização geográfica da rede com marcadores por licenciado, choropleth de cobertura, Gap Analysis e painel de detalhes por ponto | Comercial, Diretor |
| 03 | Kanban de Licenciamento | Gestão visual dos leads pelas etapas do pipeline comercial (Prospecção → Onboarding → Perdido), com drag & drop | Comercial |
| 04 | Capacidade da Rede | Visão operacional de m² total, por nível, por região; composição de tiers; top licenciados; alertas de capacidade | Comercial, Diretor |
| 05 | Disponibilidade Comercial | m² disponível em tempo real (considerando utilização), ferramenta de match cliente-licenciado, projeção 3/6 meses | Comercial |
| 06 | Scorecard de Performance | KPIs operacionais por licenciado (OTIF, acuracidade, D2S, utilização, NPS, onboarding), histórico trimestral, planos de remediação | Gestor, Diretor |
| 07 | Pipeline de Auditoria | Kanban de 6 etapas de homologação com checklists obrigatórios, SLA por etapa, upload de relatório de visita técnica e emissão de certificado digital | Auditor, Comercial, Diretor |
| 08 | Board Report | Geração em 1 clique de PDF executivo completo com todos os indicadores da rede para apresentação à diretoria | Diretor |
| 09 | Central de Alertas | Notificações proativas sobre eventos críticos: certificações vencendo, score em queda, capacidade crítica, formulários preenchidos, aniversários de contrato | Todos os perfis internos |
Portal Público (externo): Adicionalmente, existe o portal.html — uma página pública acessível via link único, sem autenticação, onde o candidato a licenciado preenche o formulário completo de cadastro com 7 seções e upload de documentos.
4. Requisitos Funcionais Seção 4
Os requisitos funcionais estão organizados por domínio. Cada requisito contém: identificador único, descrição, regras de negócio, fluxo de execução, validações e critério de aceite.
4.1 Gestão de Leads e Cadastro
O sistema deve permitir o cadastro completo de um candidato a licenciado (lead) por meio de formulário interno de 11 seções, cobrindo dados da empresa, contato, localização com CEP e geocodificação, capacidade instalada (múltiplos armazéns), tipos de carga, maturidade tecnológica, certificações, plano comercial, opção de WMS, etapa do funil e acompanhamento comercial.
- Os campos Razão Social e E-mail do contato são obrigatórios para salvar o lead
- O CEP, quando informado, deve ser validado via BrasilAPI e, como fallback, via ViaCEP
- Coordenadas GPS (lat/lng) são extraídas automaticamente do CEP via BrasilAPI e salvas no banco
- O campo Status aceita apenas os valores: Ativo, Convertido ou Perdido
- Se status = "Perdido", o campo Motivo da perda deve ser preenchido
- Armazéns são cadastrados dinamicamente (múltiplos por lead), com consolidação automática de m² total
- 1. Usuário clica em "+ Novo Lead" → formulário abre em modo criação, etapa 1 de 11
- 2. Usuário navega entre seções pelo stepper ou botão "Próximo →"
- 3. Na etapa 11, o botão "Próximo" muda para "✅ Salvar lead"
- 4. Ao salvar, dados são enviados para Supabase (tabela
lic_leads) e anexos para Storage bucketlic-anexos - 5. Sistema exibe toast de confirmação e retorna à tela de origem
- Lead salvo corretamente no banco com todos os campos preenchidos
- CEP válido resulta em preenchimento automático de UF, cidade, logradouro e bairro
- Salvar sem Razão Social exibe mensagem de erro e mantém o formulário aberto
O sistema deve permitir a edição de qualquer campo de um lead já cadastrado, com carregamento dos dados existentes no formulário de 11 seções.
- Ao editar, todos os campos são pré-preenchidos com os valores atuais do banco
- Arquivos anexados são exibidos com link de download; novos arquivos podem ser adicionados
- A alteração de status para "Convertido" dispara registro automático no histórico do lead
- O campo
updated_até atualizado automaticamente no Supabase a cada edição - O botão "📄 Gerar PDF" aparece no formulário somente quando há um lead existente (edição)
- Dados editados salvos corretamente; campos não alterados mantêm seus valores anteriores
- Evento de edição registrado automaticamente no histórico do lead
O sistema deve permitir a exclusão definitiva de um lead, removendo todos os dados associados (anexos, histórico, KPIs de performance, dados de auditoria).
- A exclusão exige confirmação via modal (dialog de confirmação)
- A exclusão em cascata remove automaticamente:
lic_anexos,lic_historico,lic_performance,lic_auditoria - Arquivos no Storage não são removidos automaticamente — requerem limpeza manual ou job agendado
- Leads com status "Convertido" e ativos na rede devem exibir aviso adicional antes da exclusão
- Lead removido do banco e da tabela sem erros
- Modal de confirmação exibido antes da exclusão efetiva
- Lead não aparece mais em nenhuma tela após exclusão
O sistema deve calcular automaticamente o nível (tier) de qualidade de cada licenciado ativo, com base em um score de 0 a 100 pontos, e exibir o nível em todos os componentes visuais do sistema.
| Dimensão | Peso Máximo | Critério |
|---|---|---|
| OTIF (%) | 30 pts | ≥98%=30 | ≥95%=20 | ≥90%=12 | >0%=5 |
| Acuracidade de Inventário (%) | 25 pts | ≥99.5%=25 | ≥98%=18 | ≥95%=10 | >0%=4 |
| Certificações ativas | 20 pts | 5 pts por certificação (máx. 20) |
| Maturidade tecnológica | 15 pts | Avançado=15 | Intermediário=10 | Em desenvolvimento=5 |
| Escala (m² total) | 10 pts | ≥20k=10 | ≥10k=7 | ≥5k=4 | >0=2 |
- Score calculado corretamente conforme a fórmula
- Badge exibido na tabela de leads, kanban, mapa e scorecard
- Somente leads com status "Convertido" recebem classificação
O sistema deve manter um histórico cronológico completo de todos os eventos relacionados a um lead, desde a prospecção inicial até o status atual.
- Mudança de etapa no Kanban de Licenciamento
- Avanço de etapa no Pipeline de Auditoria
- Emissão de certificado digital
- Lançamento de KPIs no Scorecard
- Geração de link de formulário
- Preenchimento do formulário pelo parceiro (portal público)
- Reunião realizada (data, participantes, resultado)
- Contato realizado (tipo, resultado)
- Proposta enviada
- Nota interna
- Mudança de etapa manual
- Timeline exibida no painel do mapa (tab "Histórico") e no formulário do lead
- Eventos ordenados cronologicamente (mais recentes primeiro)
- Documentos anexados aparecem mesclados na timeline com link de download
4.2 Portal Público de Preenchimento
O sistema deve gerar um link único e seguro para cada lead, permitindo que o próprio candidato preencha seus dados no portal público sem necessidade de login.
- O token é gerado via
crypto.getRandomValues()— 32 caracteres hexadecimais - O token é salvo no campo
form_tokenda tabelalic_leads(campo UNIQUE) - O link tem o formato:
https://pipelinevendemmia.com.br/portal.html?token=TOKEN - Um novo token pode ser gerado para o mesmo lead — o anterior é substituído
- O modal exibe: link copiável, QR Code, botão de compartilhar via WhatsApp e via E-mail
- Token único salvo no banco sem erro de duplicidade
- Link abre o portal público com os dados do lead pré-preenchidos (se existentes)
- QR Code gerado e exibido corretamente
O portal público (portal.html) exibe um formulário multi-etapa de 7 seções para que o candidato a licenciado preencha seus dados operacionais sem intervenção do time comercial.
| # | Seção | Campos Principais |
|---|---|---|
| 1 | Dados da empresa | Razão social*, CNPJ*, website, faturamento*, segmentos, upload Contrato Social |
| 2 | Contato principal | Nome*, cargo*, e-mail*, telefone*, decisor |
| 3 | Localização | CEP (com geocodificação automática), UF*, polo logístico*, logradouro, bairro, exclusividade |
| 4 | Capacidade instalada | Múltiplos armazéns: nome, UF, cidade, m²*, docas, ocupação, páletes, pé-direito, upload fotos |
| 5 | Tipos de carga | Carga geral, perigosa (classes IMDG), temperatura controlada, licenças ativas, observações |
| 6 | Maturidade tecnológica | WMS, ERP, sistemas integrados, nível de maturidade (Básico→Avançado) |
| 7 | Certificações | Certificações ativas, OTIF, acuracidade de inventário, observações, upload de certificados |
- Auto-save após cada seção avançada — dados salvos com
form_status = 'preenchendo' - Ao enviar,
form_statusmuda para'concluido'eform_filled_até registrado - Se formulário já estava "concluído", exibe tela de aviso com opção de editar
- Token inválido exibe tela de "Link inválido ou expirado"
- Uploads enviados para bucket
lic-anexosno Supabase Storage
- Formulário salvo automaticamente em cada navegação entre etapas
- Dados persistidos corretamente na tabela
lic_leadsao final - Tela de agradecimento exibida após envio final
O portal deve permitir que o parceiro faça upload de documentos em seções específicas do formulário, com armazenamento seguro no Supabase Storage.
- Seção 1 (Empresa): Contrato Social — PDF, DOC, JPG, PNG — máx. 10 MB
- Seção 4 (Capacidade): Fotos por armazém (cada armazém tem sua própria zona de upload) — JPG, PNG, HEIC — máx. 10 MB cada
- Seção 7 (Certificações): Documentos de certificação — PDF, JPG, PNG — múltiplos — máx. 10 MB cada
- Arquivos ficam "pendentes" durante o preenchimento e são enviados ao Supabase no submit final
- Cada foto de armazém é vinculada ao armazém específico (tipo:
foto_armazem_1,foto_armazem_2) - Política de Storage: bucket
lic-anexoscom política de INSERT para usuários anônimos
- Arquivo enviado aparece listado com nome e tamanho
- Registro criado em
lic_anexoscom URL pública para download - Arquivo superior a 10 MB exibe alerta e é ignorado
4.3 Pipeline de Auditoria e Homologação
O sistema deve permitir iniciar o processo formal de homologação de qualquer lead cadastrado, criando um registro de auditoria com a etapa inicial "Prospectado".
| Etapa | Descrição | SLA | Checklist |
|---|---|---|---|
| 1. Prospectado | Contato inicial e envio do formulário | 7 dias | 4 itens |
| 2. Formulário Enviado | Dados preenchidos pelo parceiro | 14 dias | 4 itens |
| 3. Análise Documental | Revisão jurídica, fiscal e de certificações | 10 dias | 5 itens |
| 4. Visita Técnica | Inspeção in loco e relatório | 21 dias | 7 itens |
| 5. Aprovação | Revisão pela diretoria e assinatura de contrato | 14 dias | 4 itens |
| 6. Ativo na Rede | Certificado emitido e go-live confirmado | — | 4 itens |
- Cada lead pode ter apenas 1 registro ativo em
lic_auditoria(campo UNIQUE porlead_id) - Alertas visuais de SLA: verde (no prazo), âmbar (70%+ do prazo), vermelho (vencido)
- O avanço de etapa só é possível após todos os itens do checklist estarem marcados
- Registro criado em
lic_auditoriacom etapa "prospectado" e prazo calculado - Botão "Avançar" bloqueado enquanto checklist incompleto
- Card do lead exibido na coluna correta do kanban
Ao concluir a etapa "Ativo na Rede", o sistema deve permitir a emissão formal de um certificado digital ao licenciado, contendo número único, data de emissão e validade.
- A emissão do certificado altera automaticamente o
statusdo lead para "Convertido" - O formato do número segue a convenção:
VDM-AAAA-NNN(ex.: VDM-2026-001) - A validade padrão é de 2 anos a partir da data de emissão
- O evento é registrado automaticamente no histórico do lead
- Após emissão, o licenciado passa a aparecer no mapa, scorecard e painel de capacidade
- Campos de número, emissão e validade salvos em
lic_auditoria - Lead com status "Convertido" visível em todos os painéis da rede
- Toast de confirmação exibido com mensagem de sucesso
4.4 Scorecard de Performance
O sistema deve permitir o registro trimestral de KPIs operacionais para cada licenciado ativo, com validação automática dos thresholds e ativação de plano de remediação quando necessário.
| KPI | Unidade | Verde | Amarelo | Vermelho |
|---|---|---|---|---|
| OTIF | % | ≥97% | 90–96% | <90% |
| Acuracidade de Inventário | % | ≥98% | 95–97% | <95% |
| Dock-to-Stock Time | horas | ≤24h | 24–48h | >48h |
| Utilização de Capacidade | % | ≤85% | 85–95% | >95% |
| NPS do cliente alocado | pontos | ≥50 | 20–49 | <20 |
| Tempo médio de onboarding | dias | ≤20d | 21–30d | >30d |
- O bloco de "Plano de Remediação" aparece automaticamente quando qualquer KPI estiver em vermelho OU quando o licenciado for nível Bronze
- O lançamento de KPIs atualiza automaticamente
otif_pcteacuracidade_pctna tabelalic_leads - O período segue o formato
Q1/Q2/Q3/Q4 AAAAe é salvo com data de referência (periodo_ref)
- KPIs salvos em
lic_performancecom período correto - Semáforos atualizados nos cards do scorecard após o lançamento
- Plano de remediação exibido quando aplicável
4.5 Mapa Interativo e Disponibilidade
O sistema deve exibir um mapa interativo do Brasil com todos os licenciados e leads ativos representados por marcadores georreferenciados, com choropleth de intensidade por estado.
- Tile base: CartoDB Voyager (colorido — estradas, parques, água em cores reais)
- Choropleth: Estados coloridos em tons de roxo conforme volume de m² de licenciados ativos
- Marcadores: Tags retangulares com área (m²) e UF; cor por status (verde=Convertido, roxo=Ativo, vermelho=Perdido)
- Hover popup: Ao passar o mouse, exibe foto, nome, m² disponível, fee/mês, badges
- Side panel: Ao clicar, abre painel lateral com 3 abas: Dados | Histórico | Documentos
- Prioridade 1: Coordenadas GPS do CEP (via BrasilAPI) — máxima precisão
- Prioridade 2: Polo logístico/cidade no dicionário interno (80+ cidades)
- Prioridade 3: Capital do estado como fallback
- Mapa exibe todos os licenciados com coordenadas corretas
- Hover popup aparece em menos de 300ms após passar o mouse
- Side panel carrega dados e histórico do lead ao clicar no marcador
O sistema deve oferecer um modo de análise de gaps que destaca visualmente os estados sem cobertura de licenciados, permitindo identificação rápida de oportunidades de expansão.
- Acionado pelo botão "Gap Analysis" no header do mapa
- Estados coloridos em 3 categorias: Verde = licenciado ativo, Âmbar = em prospecção, Vermelho = sem cobertura
- Painel lateral exibe contagem por categoria e lista de UFs sem cobertura como "Oportunidades prioritárias"
- Clicar no botão novamente desativa o modo e retorna ao mapa normal
- Choropleth tricolor exibido corretamente ao ativar o modo
- Lista de UFs sem cobertura atualizada em tempo real conforme os dados do banco
O sistema deve oferecer uma ferramenta de busca de disponibilidade no painel "Disponibilidade Comercial" para que o time de vendas encontre licenciados compatíveis com as necessidades de um cliente durante uma reunião.
- Estados necessários: Multi-select (Ctrl+clique para múltiplos)
- m² mínimo: Campo numérico (capacidade disponível mínima)
- Tipo de carga: Dropdown (paletizado, refrigerado, farmacêutico, alto valor, etc.)
- m² disponível =
area_total_m2 × (1 - utilizacao_capacidade / 100) - Resultados ordenados por maior m² disponível
- Licenciados sem dados de utilização registrados não são filtrados pelo critério de m²
- Resultados exibidos inline no painel com m² disponível, tier badge e status
- Nenhum resultado exibe mensagem clara ao usuário
4.6 Central de Alertas e Renovações
O sistema deve gerar automaticamente alertas baseados em eventos e condições detectadas nos dados, exibindo-os em um painel centralizado com badge de contagem no botão de navegação.
| Tipo | Prioridade | Condição |
|---|---|---|
| Certificação vencendo | Crítico | Validade do certificado ≤ 30 dias |
| Capacidade crítica | Crítico | m² disponível < 500 |
| Risco de downgrade | Crítico | Queda de OTIF >3% ou acuracidade >2% entre períodos |
| Certificação atenção | Atenção | Validade do certificado entre 31 e 60 dias |
| Alta ocupação | Atenção | Utilização de capacidade > 70% |
| Sem atualização | Atenção | Lead ativo sem atualização há > 60 dias |
| Aniversário de contrato | Info | Aniversário do certificado nos próximos 30 dias |
| Formulário preenchido | Info | Portal preenchido nos últimos 7 dias |
| Sem KPIs registrados | Info | Licenciado ativo sem nenhum registro em lic_performance |
- Alertas dispensados são salvos em
localStoragepor ID único gerado a partir do tipo + lead_id + mês - Alertas reaparecerão no mês seguinte se a condição persistir
- O badge no botão "Alertas" fica vermelho se há alertas críticos, âmbar se apenas atenção
- Cada alerta tem um botão "Ver →" que navega diretamente à tela relevante
- Badge atualizado automaticamente após cada carregamento de dados
- Alertas agrupados corretamente por prioridade (Crítico → Atenção → Informação)
- Dispensar um alerta o remove da lista sem afetar outros
O sistema deve gerar automaticamente, em 1 clique, um relatório executivo em PDF com todos os indicadores da rede, pronto para apresentação à diretoria.
- Capa: Branding Vendemmia/Pipeline, mês de referência, data e hora de geração
- 4 KPIs de destaque: Licenciados ativos, m² total da rede, score médio, fee mensal total
- Distribuição por nível: Contagem e m² por Platina/Ouro/Prata/Bronze com barras
- Atividade do período: Novos licenciados, em qualificação, alertas, sem KPIs
- Saúde da rede: Verde/Amarelo/Vermelho/Sem dados com percentuais
- Cobertura geográfica: Contagem e m² por região + lista de estados cobertos
- Top 5 licenciados: Tabela ordenada por score com tier badge
- Alertas e pontos de atenção: Licenciados críticos identificados
- Geração via html2canvas (escala 2x) + jsPDF com paginação automática em A4
- Nome do arquivo:
Board_Report_Licenciamento_AAAA-MM.pdf - Rodapé: "Documento Confidencial — distribuição restrita à diretoria Vendemmia"
- PDF gerado e baixado automaticamente em menos de 10 segundos
- Conteúdo reflete os dados atuais do banco no momento da geração
- Formatação A4 correta sem cortes de conteúdo
Próximas entregas:
Fase 2 cobre: Regras de Negócio detalhadas (RN-001 a RN-040), Fluxos Operacionais completos com passo a passo, especificação de cada tela do sistema e Casos de Uso completos.
Fase 3 cobre: Validações por campo, Relatórios e Dashboards, Notificações, Critérios de Aceite para homologação e Requisitos Não-Funcionais (performance, segurança, escalabilidade).