Especificação Técnica
Sistema Pipeline
Módulo de Licenciamento

Este documento constitui a Especificação Técnica Completa do Módulo de Licenciamento integrado ao sistema Pipeline da Vendemmia. O documento abrange toda a arquitetura de software, modelagem de banco de dados, APIs, segurança, infraestrutura e estratégias de evolução técnica.

1.1 Stack Tecnológica Detalhada

1.2 Arquitetura Geral do Sistema

O sistema adota uma arquitetura JAMstack (JavaScript + APIs + Markup) com backend como serviço (BaaS). Esta abordagem elimina a necessidade de servidores de aplicação próprios, reduz a superfície de ataque e minimiza custos operacionais.

1.3 Decisões Arquiteturais e Justificativas

2.1 Frontend — Single Page Application (SPA)

O frontend é uma SPA implementada em um único arquivo HTML (index.html) servida via GitHub Pages no domínio pipelinevendemmia.com.br. Toda a lógica de UI, state management e comunicação com APIs está contida neste arquivo.

Estrutura lógica do frontend

// Organização lógica do código em index.html (~11.000+ linhas)
// ─────────────────────────────────────────────────────────

// [1] HEAD: CDNs carregados em ordem de dependência
Leaflet CSS → Tabler Icons CSS → jsPDF → html2canvas
→ Leaflet JS → Chart.js → @supabase/supabase-js

// [2] STYLE: CSS global (~700 linhas)
- Variáveis CSS (design tokens)
- Componentes reutilizáveis (cards, buttons, modals)
- Módulos específicos (lic-*, fin-*, kb-*)

// [3] HTML: Estrutura de telas (SPA)
- #login-overlay      → tela de autenticação
- #main-system        → container principal (hidden até login)
  - header (nav global)
  - #page-dashboard   → tela Home/Pipeline
  - #page-kanban      → Kanban de oportunidades
  - #page-financeiro  → Financeiro
  - #page-licenciamento → Módulo Licenciamento
    - #lic-view-tabela       → dashboard + tabela
    - #lic-view-form         → formulário 11 seções
    - #lic-view-mapa         → mapa interativo
    - #lic-view-kanban       → kanban de leads
    - #lic-view-scorecard    → scorecard KPIs
    - #lic-view-auditoria    → pipeline auditoria
    - #lic-view-capacidade   → painel capacidade
    - #lic-view-disponibilidade → disponibilidade
  - Modais globais (fixed position)

// [4] SCRIPT: JavaScript (~9.000+ linhas)
- Inicialização e autenticação
- Módulos do sistema principal (Pipeline, Financeiro...)
- Módulo Licenciamento (funções lic*, lc*, aud*, sc*...)
  - State: baseLicLeads, _licPerfData, _audData, _licHistData
  - Funções de renderização: renderizarLicenciamento()
  - Funções de mapa: _licInicializarMapa(), _licAtualizarMarkers()
  - Funções de scorecard: calcLicScore(), getLicTier()
  - Funções de auditoria: audAvancarEtapa(), emitirCertificado()
  - Funções de histórico: registrarLicHistorico()
  - Funções de PDF: gerarLicPDF(), gerarBoardReport()

State Management

O sistema não utiliza biblioteca de state management. O estado é gerenciado via variáveis globais JavaScript com padrão de nomenclatura prefixada:

2.2 Backend — Supabase (BaaS)

O backend é inteiramente gerenciado pelo Supabase (projeto geojgcncmtbjebftosor, região sa-east-1 — São Paulo). O Supabase expõe automaticamente uma API REST via PostgREST sobre o PostgreSQL, com autenticação via JWT e controle de acesso por Row Level Security (RLS).

Componentes Supabase em uso

Padrão de chamada à API

// Inicialização do cliente Supabase (chamada única no carregamento)
const SUPABASE_URL = "https://geojgcncmtbjebftosor.supabase.co";
const SUPABASE_KEY = "eyJ..."; // anon key (safe para expor no client)
const { createClient } = supabase;
const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY);

// Padrão de leitura (SELECT)
const { data, error } = await supabaseClient
  .from('lic_leads')
  .select('*')
  .eq('status', 'Convertido')
  .order('created_at', { ascending: false });

// Padrão de escrita (INSERT)
const { data: novo, error } = await supabaseClient
  .from('lic_leads')
  .insert([{ razao_social: '...', status: 'Ativo' }])
  .select('id')
  .single();

// Padrão de atualização (UPDATE)
await supabaseClient
  .from('lic_leads')
  .update({ status: 'Convertido', updated_at: new Date().toISOString() })
  .eq('id', leadId);

// Upload para Storage
await supabaseClient.storage
  .from('lic-anexos')
  .upload(path, file, { cacheControl: '3600', upsert: false });

2.3 Storage e Estrutura de Arquivos

O Supabase Storage é usado para persistir todos os arquivos do módulo Licenciamento no bucket lic-anexos. A estrutura de paths garante isolamento por lead e rastreabilidade por tipo.

Estrutura de paths no bucket lic-anexos

lic-anexos/
├── leads/
│   └── {lead_id}/
│       ├── contrato_social/
│       │   └── {timestamp}_{nome_arquivo}     ← Contrato Social (PDF/DOC)
│       ├── foto_armazem_1/
│       │   └── {timestamp}_{nome_arquivo}     ← Fotos do Armazém 1 (JPG/PNG)
│       ├── foto_armazem_2/
│       │   └── {timestamp}_{nome_arquivo}     ← Fotos do Armazém 2
│       ├── certificado/
│       │   └── {timestamp}_{nome_arquivo}     ← Certificações (PDF/JPG)
│       ├── relatorio_visita/
│       │   └── {timestamp}_{nome_arquivo}     ← Relatório de visita técnica (PDF)
│       └── pdf_lead/
│           └── {timestamp}_lead_{id}_AAAA-MM.pdf  ← PDF gerado do lead

Políticas de Storage (RLS em storage.objects)

2.4 Autenticação e Sessão

Fluxo de autenticação

// 1. Login — Supabase Auth (e-mail + senha)
const { data, error } = await supabaseClient.auth
  .signInWithPassword({ email, password });

// 2. JWT obtido → armazenado no localStorage pelo SDK
//    Chave: 'sb-geojgcncmtbjebftosor-auth-token'

// 3. Todas as chamadas subsequentes incluem automaticamente
//    o header: Authorization: Bearer {jwt_token}

// 4. Controle de acesso ao módulo Licenciamento
const LICENCIAMENTO_WHITELIST = [
  'gppereira@vendemmia.com.br',
  'jprado@vendemmia.com.br'
];
// Verificação via EMAIL_USUARIO_LOGADO após login

// 5. Sessão persistente: SDK recupera sessão do localStorage
//    automaticamente no reload da página
//    JWT expira em ~3600s; SDK faz refresh automático

2.5 Comunicação entre Componentes

3.1 Modelo Lógico de Dados

O módulo Licenciamento utiliza 5 tabelas próprias no banco Supabase, além de referenciar a tabela auth.users do Supabase Auth. Todas as tabelas têm Row Level Security (RLS) habilitado.

lic_leads (id PK)
    │
    ├──── lic_auditoria (lead_id FK UNIQUE) — 1:1 por lead
    │
    ├──── lic_performance (lead_id FK) — 1:N por lead (múltiplos períodos)
    │
    ├──── lic_historico (lead_id FK) — 1:N por lead (linha do tempo)
    │
    └──── lic_anexos (lead_id FK) — 1:N por lead (múltiplos arquivos)
  

3.2 Tabela: lic_leads

Tabela principal. Armazena todos os dados cadastrais de cada lead/licenciado da rede.

3.3 Tabela: lic_auditoria

3.4 Tabela: lic_performance

3.5 Tabela: lic_historico

3.6 Tabela: lic_anexos

3.7 Índices Recomendados

-- lic_leads: queries mais frequentes
CREATE INDEX idx_lic_leads_status ON lic_leads(status);
CREATE INDEX idx_lic_leads_uf ON lic_leads(uf);
CREATE INDEX idx_lic_leads_etapa ON lic_leads(etapa);
CREATE INDEX idx_lic_leads_created_at ON lic_leads(created_at DESC);
CREATE UNIQUE INDEX idx_lic_leads_form_token ON lic_leads(form_token)
  WHERE form_token IS NOT NULL; -- partial unique index

-- lic_auditoria: lookup por lead
CREATE UNIQUE INDEX idx_lic_auditoria_lead ON lic_auditoria(lead_id);
CREATE INDEX idx_lic_auditoria_estagio ON lic_auditoria(estagio_atual);
CREATE INDEX idx_lic_auditoria_cert_val ON lic_auditoria(certificado_validade)
  WHERE certificado_validade IS NOT NULL; -- para alertas de renovação

-- lic_performance: queries por lead + ordenação por período
CREATE INDEX idx_lic_perf_lead_periodo ON lic_performance(lead_id, periodo_ref DESC);

-- lic_historico: timeline ordenada por lead
CREATE INDEX idx_lic_hist_lead_created ON lic_historico(lead_id, created_at DESC);

-- lic_anexos: lookup por lead e tipo
CREATE INDEX idx_lic_anx_lead_tipo ON lic_anexos(lead_id, tipo);

3.8 Row Level Security (RLS)

Todas as tabelas do módulo Licenciamento têm RLS habilitado com política "Allow all" para usuários autenticados. O controle de acesso granular é feito na camada de aplicação (whitelist no frontend).

-- Padrão aplicado em todas as 5 tabelas
ALTER TABLE lic_leads ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Allow all lic_leads" ON lic_leads
  FOR ALL USING (true) WITH CHECK (true);

-- Nota: política permissiva necessária pois o portal público
-- (usuário anônimo) precisa ler/escrever dados de leads via token.
-- Evolução: implementar RLS por token (ver Fase 3 - evolução técnica)