# Aggios App

Plataforma composta por serviços de autenticação, painel administrativo (superadmin) e site institucional da Aggios, orquestrados via Docker Compose.

## Visão geral
- **Objetivo**: permitir que superadministradores cadastrem e gerenciem agências (tenants) enquanto o site institucional apresenta informações públicas da empresa.
- **Stack**: Go (backend), Next.js 16 (dashboard e site), PostgreSQL, Traefik, Docker.
- **Status**: Sistema multi-tenant completo com CRM Beta (leads, funis, campanhas), portal do cliente, segurança cross-tenant validada, branding dinâmico e file serving via API.

## Componentes principais
- `backend/`: API Go com serviços de autenticação, operadores e CRUD de agências (endpoints `/api/admin/agencies` e `/api/admin/agencies/{id}`). Inclui handlers para CRM (leads, funis, campanhas), portal do cliente e exportação de dados.
- `front-end-agency/`: Painel Next.js para agências - branding dinâmico, upload de logos, gestão de perfil, CRM completo com Kanban, portal de cadastro de clientes e autenticação tenant-aware.
- `front-end-dash.aggios.app/`: painel Next.js – login do superadmin, listagem de agências, exibição detalhada e exclusão definitiva.
- `frontend-aggios.app/`: site institucional Next.js com suporte a temas claro/escuro e compartilhamento de tokens de design.
- `backend/internal/data/postgres/`: scripts de inicialização do banco (estrutura base de tenants e usuários) + migrações para CRM, funis e autenticação de clientes.
- `traefik/`: reverse proxy e certificados automatizados.

## Funcionalidades entregues

### **v1.5 - CRM Beta: Leads, Funis e Portal do Cliente (24/12/2025)**
- **🎯 Gestão Completa de Leads**:
  - CRUD completo de leads com status, origem e pontuação
  - Sistema de importação de leads (CSV/Excel)
  - Filtros avançados por status, origem, responsável e cliente
  - Associação de leads a clientes específicos
  - Timeline de atividades e histórico de interações
  
- **📊 Funis de Vendas (Sales Funnels)**:
  - Criação e gestão de múltiplos funis personalizados
  - Board Kanban interativo com drag-and-drop
  - Estágios customizáveis com cores e ícones
  - Vinculação de funis a campanhas específicas
  - Métricas e conversão por estágio
  
- **🎪 Gestão de Campanhas**:
  - Criação de campanhas com período e orçamento
  - Vinculação de campanhas a clientes específicos
  - Acompanhamento de leads gerados por campanha
  - Dashboard de performance de campanhas
  
- **👥 Portal do Cliente**:
  - Sistema de registro público de clientes
  - Autenticação dedicada para clientes (JWT separado)
  - Dashboard personalizado com estatísticas
  - Visualização de leads e listas compartilhadas
  - Gestão de perfil e alteração de senha
  
- **🔗 Compartilhamento de Listas**:
  - Tokens únicos para compartilhamento de leads
  - URLs públicas para visualização de listas específicas
  - Controle de acesso via token com expiração
  
- **👔 Gestão de Colaboradores**:
  - Sistema de permissões (Owner, Admin, Member, Readonly)
  - Middleware de autenticação unificada (agência + cliente)
  - Controle granular de acesso a funcionalidades
  - Atribuição de leads a colaboradores específicos
  
- **📤 Exportação de Dados**:
  - Exportação de leads em CSV
  - Filtros aplicados na exportação
  - Formatação otimizada para planilhas

### **v1.4 - Segurança Multi-tenant e File Serving (13/12/2025)**
- **🔒 Segurança Cross-Tenant Crítica**:
  - Validação de tenant_id em endpoints de login (bloqueio de cross-tenant authentication)
  - Validação de tenant em todas rotas protegidas via middleware
  - Mensagens de erro genéricas (sem exposição de arquitetura multi-tenant)
  - Logs detalhados de tentativas de acesso cross-tenant bloqueadas
  
- **📁 File Serving via API**:
  - Nova rota `/api/files/{bucket}/{path}` para servir arquivos do MinIO através do backend Go
  - Eliminação de dependência de DNS (`files.localhost`) - arquivos servidos via `api.localhost`
  - Headers de cache otimizados (Cache-Control: public, max-age=31536000)
  - CORS e content-type corretos automaticamente
  
- **🎨 Melhorias de UX**:
  - Mensagens de erro humanizadas no formulário de login (sem pop-ups/toasts)
  - Erros inline com ícones e cores apropriadas
  - Feedback em tempo real ao digitar (limpeza automática de erros)
  - Mensagens específicas para cada tipo de erro (401, 403, 404, 429, 5xx)
  
- **🔧 Melhorias Técnicas**:
  - Next.js middleware injetando headers `X-Tenant-Subdomain` para routing correto
  - TenantDetector middleware prioriza headers customizados sobre Host
  - Upload de logos retorna URLs via API ao invés de MinIO direto
  - Configuração MinIO com variáveis de ambiente `MINIO_SERVER_URL` e `MINIO_BROWSER_REDIRECT_URL`

### **v1.3 - Branding Dinâmico e Favicon (12/12/2025)**
- **Branding Multi-tenant**: Logo, favicon e cores personalizadas por agência
- **Favicon Dinâmico**: Atualização em tempo real via localStorage e SSR metadata
- **Upload de Arquivos**: Sistema de upload para MinIO com bucket público
- **Rate Limiting**: 1000 requisições/minuto por IP

### **v1.2 - Redesign Interface Flat**
- Adoção de design "Flat" (sem sombras), focado em bordas e limpeza visual
- Gestão avançada de agências com filtros robustos
- Detalhamento completo com visualização de branding

### **v1.1 - Fundação Multi-tenant**
- Login de Superadmin com JWT
- Cadastro de Agências
- Proxy Interno Next.js para chamadas autenticadas
- Site Institucional com dark mode

## Executando o projeto
1. **Pré-requisitos**: Docker Desktop e Node.js 20+ (para utilitários opcionais).
2. **Variáveis**: ajustar `.env` conforme referências existentes (`docker-compose.yml`, arquivos `config`).
3. **Subir os serviços**:
	```powershell
	docker-compose up --build
	```
4. **Hosts locais**:
	- Painel SuperAdmin: `http://dash.localhost`
	- Painel Agência: `http://{agencia}.localhost` (ex: `http://idealpages.localhost`)
	- Portal do Cliente: `http://{agencia}.localhost/cliente` (cadastro e área logada)
	- Site: `http://aggios.app.localhost`
	- API: `http://api.localhost`
	- Console MinIO: `http://minio.localhost` (admin: minioadmin / M1n10_S3cur3_P@ss_2025!)
5. **Credenciais padrão**: ver `backend/internal/data/postgres/init-db.sql` para usuário superadmin seed.

## Segurança
- ✅ **Cross-Tenant Authentication**: Usuários não podem fazer login em agências que não pertencem
- ✅ **Tenant Isolation**: Todas rotas protegidas validam tenant_id no JWT vs tenant_id do contexto
- ✅ **Erro Handling**: Mensagens genéricas que não expõem arquitetura interna
- ✅ **JWT Validation**: Tokens validados em cada requisição autenticada
- ✅ **Rate Limiting**: 1000 req/min por IP para prevenir brute force

## Estrutura de diretórios (resumo)
```
backend/                            API Go (config, domínio, handlers, serviços)
  internal/
    api/
      handlers/
        crm.go                      🎯 CRUD de leads, funis e campanhas
        customer_portal.go          👥 Portal do cliente (auth, dashboard, leads)
        export.go                   📤 Exportação de dados (CSV)
        collaborator.go             👔 Gestão de colaboradores
        files.go                    Handler para servir arquivos via API
        auth.go                     🔒 Validação cross-tenant no login
      middleware/
        unified_auth.go             🔐 Autenticação unificada (agência + cliente)
        customer_auth.go            🔑 Middleware de autenticação de clientes
        collaborator_readonly.go    📖 Controle de permissões readonly
        auth.go                     🔒 Validação tenant em rotas protegidas
        tenant.go                   🔧 Detecção de tenant via headers
    domain/
      auth_unified.go               🆕 Domínios para autenticação unificada
    repository/
      crm_repository.go             🆕 Repositório de dados do CRM
backend/internal/data/postgres/     Scripts SQL de seed
  migrations/
    015_create_crm_leads.sql        🆕 Estrutura de leads
    020_create_crm_funnels.sql      🆕 Sistema de funis
    018_add_customer_auth.sql       🆕 Autenticação de clientes
front-end-agency/                   Dashboard Next.js para Agências
  app/
    (agency)/
      crm/
        leads/                      🆕 Gestão de leads
        funis/[id]/                 🆕 Board Kanban de funis
        campanhas/                  🆕 Gestão de campanhas
    cliente/
      cadastro/                     🆕 Registro público de clientes
      (portal)/                     🆕 Portal do cliente autenticado
    share/leads/[token]/            🆕 Compartilhamento de listas
    login/page.tsx                  Login com mensagens humanizadas
  components/
    crm/
      KanbanBoard.tsx               🆕 Board Kanban drag-and-drop
      CRMCustomerFilter.tsx         🆕 Filtros avançados de CRM
    team/
      TeamManagement.tsx            🆕 Gestão de equipe e permissões
  middleware.ts                     Injeção de headers tenant
front-end-dash.aggios.app/          Dashboard Next.js Superadmin
frontend-aggios.app/                Site institucional Next.js
traefik/                            Regras de roteamento e TLS
1. docs/                            Documentação funcional e técnica
```

## Testes e validação
- Consultar `1. docs/TESTING_GUIDE.md` para cenários funcionais.
- **Testes de Segurança**:
  - ✅ Tentativa de login cross-tenant retorna 403
  - ✅ JWT de uma agência não funciona em outra agência
  - ✅ Logs registram tentativas de acesso cross-tenant
- **Testes de File Serving**:
  - ✅ Upload de logo gera URL via API (`http://api.localhost/api/files/...`)
  - ✅ Imagens carregam sem problemas de CORS ou DNS
  - ✅ Cache headers aplicados corretamente

## Próximos passos sugeridos
- Implementar soft delete e trilhas de auditoria para exclusão de agências
- Adicionar validação de permissões por tenant em rotas de files (se necessário)
- Expandir testes automatizados (unitários e e2e) focados no fluxo do dashboard
- Disponibilizar pipeline CI/CD com validações de lint/build

## Repositório
- Principal: https://git.stackbyte.cloud/erik/aggios.app.git
- Branch: 1.5-crm-beta (v1.5 - CRM Beta com leads, funis, campanhas e portal do cliente)