200 lines
10 KiB
Markdown
200 lines
10 KiB
Markdown
# 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) |