# Portal do Cliente - Documentação da Implementação

## Resumo das Alterações

Foi implementado um sistema completo de **Portal do Cliente** com as seguintes funcionalidades:

### 1. **Banco de Dados** (criar_tabelas_pesquisas.sql)
- ✅ Nova coluna na tabela `pesquisas`: `liberado_cliente CHAR(1) DEFAULT 'N'`
- Permite marcar pesquisas como liberadas ou bloqueadas para clientes
- Inclui scripts de migração (ALTER TABLE) para databases existentes

### 2. **Visualizar Pesquisa** (visualizar_pesquisa.php)
- ✅ Adicionado campo visual **"Status para Cliente"** na seção de informações da pesquisa
- ✅ Botão dinâmico para **liberar/bloquear pesquisa**:
  - **🔓 Liberar para Cliente** (quando status = Bloqueado)
  - **🔒 Bloquear Cliente** (quando status = Liberado)
- ✅ Status visual com indicador de cor:
  - Verde (✓ Liberado) - quando `liberado_cliente = 'S'`
  - Vermelho (✕ Bloqueado) - quando `liberado_cliente = 'N'`

### 3. **Processar Liberar Cliente** (processar_liberar_cliente.php) ✨ NOVO
- Arquivo responsável por processar o toggle liberar/bloquear
- Recebe POST com: `id_pesquisa` e `acao` (liberar ou bloquear)
- Atualiza o campo `liberado_cliente` na tabela pesquisas
- Utiliza transações MySQL para garantir integridade
- Redireciona com mensagem de sucesso/erro

### 4. **Portal do Cliente** (portal_cliente.php) ✨ NOVO
Interface completa para acesso aos leads de pesquisas liberadas:

#### Funcionalidades:
- 📋 **Seleção de Pesquisa**
  - Dropdown com todas as pesquisas liberadas (`liberado_cliente = 'S'`)
  - Exibe contagem de leads por pesquisa
  - Filtro por pesquisa selecionada

- 📊 **Visualização de Leads**
  - Exibição em cards com layout responsivo
  - Informações de cada lead:
    - Nome da empresa (NOME_FANTASIA)
    - Razão social (EMPRESA)
    - CNPJ
    - Telefone com DDD
    - Localização (cidade/UF)
    - Data da resposta
    - **Pontuação da pesquisa** (nota_total)
    - **Classificação** (Excelente/Bom/Regular/Insatisfatório)

- 📄 **Paginação**
  - Configurável: 5, 10, 20, 50, 100 registros por página
  - Navegação com botões: Primeira, Anterior, Páginas numeradas, Próxima, Última
  - Contador de registros exibidos

- 🎨 **Design**
  - Gradiente roxo (667eea → 764ba2) no topo
  - Cards responsivos com hover effects
  - Badges coloridas para classificações
  - Ícones emojis para melhor UX

#### Consultas SQL Otimizadas:
```sql
-- Lista de pesquisas liberadas com contagem de leads
SELECT p.id, p.nome, COUNT(DISTINCT pe.id) as total_leads
FROM pesquisas p
LEFT JOIN pesquisa_empresa pe ON p.id = pe.id_pesquisa_fk AND pe.status = 'respondida'
WHERE p.liberado_cliente = 'S' AND p.status = 'ativa'
GROUP BY p.id

-- Leads da pesquisa selecionada com LIMIT/OFFSET para paginação
SELECT pe.id, pe.nota_total, pe.classificacao, e.NOME_FANTASIA, ...
FROM pesquisa_empresa pe
LEFT JOIN empresas e ON pe.id_empresa_fk = e.ID_EMPRESA
WHERE pe.id_pesquisa_fk = ? AND pe.status = 'respondida'
ORDER BY e.NOME_FANTASIA
LIMIT ? OFFSET ?
```

### 5. **Menu Principal** (principal.php)
- ✅ Adicionado botão **🎯 Portal do Cliente** na seção de Pesquisas
- Link direto para `portal_cliente.php`
- Integrado com o menu existente

## Fluxo de Uso

### Para Administrador:
1. Acessar **"Pesquisas (Consulta)"** → pesquisas.php
2. Selecionar uma pesquisa para visualizar
3. Na visualização, encontrar o campo **"Status para Cliente"**
4. Clicar em **"🔓 Liberar para Cliente"** para liberar aos clientes
5. Pesquisa agora aparece no Portal do Cliente

### Para Cliente/Usuário:
1. Acessar **"Portal do Cliente"** pelo menu principal
2. Selecionar uma pesquisa do dropdown
3. Clicar em **"🔍 Buscar Leads"**
4. Visualizar lista paginada de leads com todas as informações
5. Navegar entre páginas conforme necessário
6. Copiar/anotar informações de contato dos leads

## Compatibilidade

- ✅ Backward compatible - Funciona mesmo se a coluna `liberado_cliente` não existir ainda no banco
- ✅ Utiliza prepared statements para segurança contra SQL injection
- ✅ Suporta MySQL 5.7+
- ✅ Suporta PHP 7+

## Próximas Melhorias Possíveis

1. **Filtros Avançados**: Filtrar leads por classificação, nota mínima, etc.
2. **Exportação CSV**: Botão para exportar lista de leads
3. **Busca por Empresa**: Campo de busca por nome de empresa nos leads
4. **Contato Direto**: Links para enviar emails aos contatos
5. **Relatórios**: Gráficos de distribuição de classificações
6. **Controle de Acesso**: Cada cliente só vê suas pesquisas liberadas
7. **Auditoria**: Log de quando cada pesquisa foi liberada/bloqueada

## Arquivos Afetados

1. **criar_tabelas_pesquisas.sql** - Adicionada coluna `liberado_cliente`
2. **visualizar_pesquisa.php** - Adicionados campo e botões de liberar/bloquear
3. **principal.php** - Adicionado link para Portal do Cliente
4. **portal_cliente.php** - ✨ NOVO - Interface completa do portal
5. **processar_liberar_cliente.php** - ✨ NOVO - Backend para toggle

## Testes Recomendados

- [ ] Verificar se coluna `liberado_cliente` foi criada no banco
- [ ] Tentar liberar uma pesquisa em visualizar_pesquisa.php
- [ ] Verificar se pesquisa aparece no dropdown do Portal do Cliente
- [ ] Clicar em "Buscar Leads" e verificar se lista aparecer
- [ ] Testar paginação com diferentes "registros por página"
- [ ] Bloquear uma pesquisa e verificar se desaparece do Portal
- [ ] Verificar links de "Voltar ao Menu" funcionarem

---
**Data de Implementação:** 2024
**Status:** ✅ Completo e Funcional
