530 lines
18 KiB
Markdown
530 lines
18 KiB
Markdown
# 🧠 Mapa Mental - Projeto Aggios
|
|
|
|
## 📌 Visão Geral
|
|
**Aggios** é uma plataforma **SaaS multi-tenant** que gerencia agências digitais com controle centralizado, gestão de clientes, soluções integradas (CRM/ERP) e sistema de pagamento.
|
|
|
|
---
|
|
|
|
## 🏛️ Arquitetura Geral
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ AGGIOS PLATFORM │
|
|
├─────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────────────────────────────────────────┐ │
|
|
│ │ Super Admin Dashboard (dash.localhost) │ │
|
|
│ │ - Gerenciar todas as agências │ │
|
|
│ │ - Visualizar cadastros │ │
|
|
│ │ - Excluir/arquivar agências │ │
|
|
│ │ - Controle de planos e pagamentos │ │
|
|
│ └──────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌────────────┼────────────┐ │
|
|
│ │ │ │ │
|
|
│ ┌────────▼──┐ ┌─────▼────┐ ┌───▼────────┐ │
|
|
│ │ Agência A │ │ Agência B │ │ Agência N │ │
|
|
│ │ Subdomain │ │ Subdomain │ │ Subdomain │ │
|
|
│ │ A │ │ B │ │ N │ │
|
|
│ └─────┬─────┘ └──────┬────┘ └────┬───────┘ │
|
|
│ │ │ │ │
|
|
│ ┌─────▼──────┐ ┌─────▼──────┐ ┌─▼───────────┐ │
|
|
│ │CRM / ERP │ │CRM / ERP │ │CRM / ERP │ │
|
|
│ │Clientes │ │Clientes │ │Clientes │ │
|
|
│ │Soluções │ │Soluções │ │Soluções │ │
|
|
│ └────────────┘ └────────────┘ └─────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔐 Sistema de Autenticação
|
|
|
|
### Níveis de Acesso
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ PERMISSÕES E ROLES │
|
|
├─────────────────────────────────────────┤
|
|
│ │
|
|
│ SUPERADMIN (admin@aggios.app) │
|
|
│ ├─ Gerenciar todas as agências │
|
|
│ ├─ Visualizar cadastros │
|
|
│ ├─ Excluir/arquivar agências │
|
|
│ ├─ Controlar planos │
|
|
│ └─ Gerenciar pagamentos │
|
|
│ │
|
|
│ ADMIN_AGENCIA (por agência) │
|
|
│ ├─ Gerenciar clientes próprios │
|
|
│ ├─ Acessar CRM/ERP │
|
|
│ ├─ Visualizar relatórios │
|
|
│ └─ Configurar agência │
|
|
│ │
|
|
│ CLIENTE (por agência) │
|
|
│ ├─ Visualizar próprios dados │
|
|
│ ├─ Acessar serviços contratados │
|
|
│ └─ Submeter solicitações │
|
|
│ │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
### Fluxo de Login
|
|
|
|
```
|
|
Usuário acessa:
|
|
dash.localhost
|
|
↓
|
|
Detecta "dash" no hostname
|
|
↓
|
|
Busca localStorage (token + user)
|
|
↓
|
|
┌─ Token válido? → Redireciona para /superadmin
|
|
│
|
|
└─ Sem token? → Mostra /login
|
|
↓
|
|
Submete credenciais
|
|
↓
|
|
Backend valida contra DB
|
|
↓
|
|
┌─ Válido → Retorna JWT + user data
|
|
│ → Salva em localStorage
|
|
│ → Redireciona para /superadmin
|
|
│
|
|
└─ Inválido → Toast error
|
|
```
|
|
|
|
---
|
|
|
|
## 🏢 Estrutura de Tenants
|
|
|
|
### Multi-Tenant Model
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ TENANT (Agência) │
|
|
├─────────────────────────────────────────┤
|
|
│ │
|
|
│ ID: UUID │
|
|
│ name: "Agência Ideal Pages" │
|
|
│ subdomain: "idealpages" │
|
|
│ domain: "idealpages.aggios.app" │
|
|
│ cnpj: "XX.XXX.XXX/XXXX-XX" │
|
|
│ razao_social: "Ideal Pages Ltda" │
|
|
│ status: active | inactive │
|
|
│ │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ USERS (pertencentes ao tenant) │ │
|
|
│ ├─────────────────────────────────┤ │
|
|
│ │ - Admin (ADMIN_AGENCIA) │ │
|
|
│ │ - Operadores │ │
|
|
│ │ - Suporte │ │
|
|
│ │ - Clientes │ │
|
|
│ └─────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ COMPANIES (clientes) │ │
|
|
│ ├─────────────────────────────────┤ │
|
|
│ │ - ID, CNPJ, email, telefone │ │
|
|
│ │ - Dados de contato │ │
|
|
│ │ - Status │ │
|
|
│ └─────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ SOLUTIONS (CRM, ERP, etc) │ │
|
|
│ ├─────────────────────────────────┤ │
|
|
│ │ - Módulos disponíveis │ │
|
|
│ │ - Integrações │ │
|
|
│ │ - Configurações │ │
|
|
│ └─────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
### Backend
|
|
```
|
|
Backend (Go)
|
|
├─ HTTP Server (net/http)
|
|
├─ JWT Authentication
|
|
├─ Password Hashing (Argon2)
|
|
├─ PostgreSQL (SQL direto, sem ORM)
|
|
├─ Redis (cache/sessions)
|
|
├─ MinIO (object storage)
|
|
└─ Middleware (CORS, Security, Rate Limit)
|
|
```
|
|
|
|
### Frontend
|
|
```
|
|
Frontend (Next.js 14)
|
|
├─ Dashboard (Superadmin)
|
|
│ ├─ Listagem de agências
|
|
│ ├─ Detalhes/visualização
|
|
│ └─ Excluir/arquivar
|
|
│
|
|
├─ Portais de Agência
|
|
│ ├─ Login específico por subdomain
|
|
│ ├─ Dashboard da agência
|
|
│ ├─ Gerenciador de clientes (CRM)
|
|
│ ├─ ERP
|
|
│ └─ Integrações
|
|
│
|
|
└─ Site Institucional (aggios.app)
|
|
├─ Landing page
|
|
├─ Pricing/Planos
|
|
├─ Documentação
|
|
└─ Contato
|
|
```
|
|
|
|
### Infraestrutura
|
|
```
|
|
Docker Compose
|
|
├─ PostgreSQL 16 (DB)
|
|
├─ Redis 7 (Cache)
|
|
├─ MinIO (S3-compatible storage)
|
|
├─ Traefik (Reverse Proxy)
|
|
├─ Backend (Go)
|
|
├─ Dashboard (Next.js)
|
|
└─ Institucional (Next.js)
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Banco de Dados
|
|
|
|
### Schema Principal
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────┐
|
|
│ DATABASE SCHEMA │
|
|
├──────────────────────────────────────────────────┤
|
|
│ │
|
|
│ TENANTS │
|
|
│ ├─ id (UUID) │
|
|
│ ├─ name, subdomain, domain │
|
|
│ ├─ cnpj, razao_social │
|
|
│ ├─ email, phone, website, address │
|
|
│ ├─ description, industry │
|
|
│ ├─ is_active │
|
|
│ └─ timestamps (created_at, updated_at) │
|
|
│ ↑ │
|
|
│ └─── FK em USERS │
|
|
│ └─── FK em COMPANIES │
|
|
│ │
|
|
│ USERS │
|
|
│ ├─ id (UUID) │
|
|
│ ├─ tenant_id (FK → TENANTS) │
|
|
│ ├─ email (UNIQUE) │
|
|
│ ├─ password_hash │
|
|
│ ├─ first_name, last_name │
|
|
│ ├─ role (SUPERADMIN | ADMIN_AGENCIA | CLIENTE) │
|
|
│ ├─ is_active │
|
|
│ └─ timestamps │
|
|
│ │
|
|
│ REFRESH_TOKENS │
|
|
│ ├─ id (UUID) │
|
|
│ ├─ user_id (FK → USERS) │
|
|
│ ├─ token_hash │
|
|
│ ├─ expires_at │
|
|
│ └─ created_at │
|
|
│ │
|
|
│ COMPANIES (Clientes das agências) │
|
|
│ ├─ id (UUID) │
|
|
│ ├─ tenant_id (FK → TENANTS) │
|
|
│ ├─ cnpj (UNIQUE por tenant) │
|
|
│ ├─ razao_social, nome_fantasia │
|
|
│ ├─ email, telefone │
|
|
│ ├─ status │
|
|
│ ├─ created_by_user_id (FK → USERS) │
|
|
│ └─ timestamps │
|
|
│ │
|
|
└──────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Fluxo de Cadastro (Registro de Nova Agência)
|
|
|
|
```
|
|
1. INICIO
|
|
│
|
|
├─ Usuário acessa: http://dash.localhost/cadastro
|
|
│
|
|
├─ Preenche formulário:
|
|
│ ├─ Nome fantasia
|
|
│ ├─ Razão social
|
|
│ ├─ CNPJ
|
|
│ ├─ Email comercial
|
|
│ ├─ Telefone
|
|
│ ├─ Website
|
|
│ ├─ Endereço completo
|
|
│ ├─ Cidade/Estado/CEP
|
|
│ ├─ Segmento (indústria)
|
|
│ ├─ Descrição
|
|
│ ├─ Email do admin da agência
|
|
│ └─ Senha inicial do admin
|
|
│
|
|
├─ Validação Frontend
|
|
│ ├─ Campos obrigatórios
|
|
│ ├─ Formato de email
|
|
│ ├─ Força de senha
|
|
│ └─ CNPJ válido?
|
|
│
|
|
├─ POST /api/admin/agencies/register (Backend)
|
|
│ │
|
|
│ ├─ Validação Backend (regras de negócio)
|
|
│ │
|
|
│ ├─ Transação DB:
|
|
│ │ ├─ Criar TENANT (gera UUID, subdomain)
|
|
│ │ ├─ Criar USER (ADMIN_AGENCIA)
|
|
│ │ ├─ Hash password (Argon2)
|
|
│ │ └─ Commit
|
|
│ │
|
|
│ └─ Retorna: {tenant_id, subdomain, access_url}
|
|
│
|
|
├─ Frontend recebe resposta
|
|
│ ├─ Exibe toast de sucesso
|
|
│ ├─ Salva dados temporários
|
|
│ └─ Redireciona para /superadmin
|
|
│
|
|
└─ FIM (Agência criada e pronta para uso)
|
|
└─ Acesso: {subdomain}.localhost/login
|
|
```
|
|
|
|
---
|
|
|
|
## 📈 Funcionalidades por Módulo
|
|
|
|
### 🔷 Superadmin Dashboard
|
|
|
|
```
|
|
dash.localhost/superadmin
|
|
├─ Header
|
|
│ ├─ Logo Aggios
|
|
│ ├─ Título "Painel Administrativo"
|
|
│ ├─ Email do admin
|
|
│ └─ Botão Sair
|
|
│
|
|
├─ Stats (KPIs)
|
|
│ ├─ Total de agências
|
|
│ ├─ Agências ativas
|
|
│ ├─ Agências inativas
|
|
│ └─ (Expandível: faturamento, etc)
|
|
│
|
|
├─ Listagem de Agências
|
|
│ ├─ Tabela com:
|
|
│ │ ├─ Nome fantasia
|
|
│ │ ├─ Subdomain
|
|
│ │ ├─ Status (ativo/inativo)
|
|
│ │ ├─ Data de criação
|
|
│ │ └─ Ações (Ver detalhes, Deletar)
|
|
│ │
|
|
│ └─ Busca/Filtro
|
|
│
|
|
└─ Modal de Detalhes
|
|
├─ Seção: Dados da Agência
|
|
│ ├─ Nome fantasia, razão social
|
|
│ ├─ CNPJ, segmento
|
|
│ ├─ Descrição
|
|
│ └─ Status
|
|
│
|
|
├─ Seção: Endereço e Contato
|
|
│ ├─ Endereço, cidade, estado, CEP
|
|
│ ├─ Website
|
|
│ ├─ Email comercial
|
|
│ └─ Telefone
|
|
│
|
|
├─ Seção: Administrador
|
|
│ ├─ Nome do admin
|
|
│ ├─ Email do admin
|
|
│ ├─ Role
|
|
│ └─ Data de criação
|
|
│
|
|
└─ Botões
|
|
├─ Abrir painel da agência (link externo)
|
|
├─ Deletar agência
|
|
└─ Fechar
|
|
```
|
|
|
|
### 🔶 Dashboard da Agência (Em Desenvolvimento)
|
|
|
|
```
|
|
{subdomain}.localhost/dashboard
|
|
├─ Sidebar
|
|
│ ├─ Dashboard
|
|
│ ├─ Clientes (CRM)
|
|
│ ├─ Projetos
|
|
│ ├─ Financeiro (ERP)
|
|
│ ├─ Configurações
|
|
│ └─ Suporte
|
|
│
|
|
├─ Stats
|
|
│ ├─ Total de clientes
|
|
│ ├─ Projetos em andamento
|
|
│ ├─ Tarefas pendentes
|
|
│ └─ Faturamento
|
|
│
|
|
└─ Seções (em construção)
|
|
├─ CRM → Gerenciar clientes, pipeline, negociações
|
|
├─ ERP → Pedidos, estoque, NF, financeiro
|
|
├─ Projetos → Planejamento, execução, entrega
|
|
└─ Integrações → API, webhooks, automações
|
|
```
|
|
|
|
---
|
|
|
|
## 🔌 APIs Principais
|
|
|
|
### Autenticação
|
|
|
|
```
|
|
POST /api/auth/login
|
|
Request: { email, password }
|
|
Response: { token, user: { id, email, name, role } }
|
|
|
|
POST /api/auth/change-password
|
|
Request: { old_password, new_password }
|
|
Response: { success: true }
|
|
|
|
POST /api/auth/logout
|
|
Request: {}
|
|
Response: { success: true }
|
|
```
|
|
|
|
### Agências (Superadmin)
|
|
|
|
```
|
|
GET /api/admin/agencies
|
|
Response: [{ id, name, subdomain, status, ... }]
|
|
|
|
POST /api/admin/agencies/register
|
|
Request: { name, cnpj, email, admin_email, admin_password, ... }
|
|
Response: { tenant_id, subdomain, access_url }
|
|
|
|
GET /api/admin/agencies/{id}
|
|
Response: { tenant, admin, access_url, ... }
|
|
|
|
DELETE /api/admin/agencies/{id}
|
|
Response: { success: true } | 204 No Content
|
|
|
|
PATCH /api/admin/agencies/{id}
|
|
Request: { status, ... }
|
|
Response: { tenant }
|
|
```
|
|
|
|
### Empresas/Clientes
|
|
|
|
```
|
|
GET /api/companies
|
|
Response: [{ id, cnpj, razao_social, email, ... }]
|
|
|
|
POST /api/companies/create
|
|
Request: { cnpj, razao_social, email, telefone, ... }
|
|
Response: { company }
|
|
|
|
GET /api/companies/{id}
|
|
Response: { company }
|
|
|
|
PUT /api/companies/{id}
|
|
Request: { razao_social, email, ... }
|
|
Response: { company }
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Ciclo de Desenvolvimento Atual
|
|
|
|
### v1.1 (dev-1.1) - Em Progresso
|
|
|
|
- ✅ Reorganização do banco (init-db em backend/internal/data/postgres)
|
|
- ✅ Autenticação de login com redirect automático
|
|
- ✅ Aumento de rate limit em dev (30 tentativas/min)
|
|
- 🔄 Melhorias na UX do dashboard superadmin
|
|
- ⏳ Implementação de CRM (clientes, pipeline)
|
|
- ⏳ Implementação de ERP básico (pedidos, financeiro)
|
|
|
|
### Próximas Versões
|
|
|
|
- 📅 v1.2: Soft delete, auditoria, trilha de mudanças
|
|
- 📅 v1.3: Integrações externas (Zapier, Make, etc)
|
|
- 📅 v1.4: Sistema de pagamento (Stripe, PagSeguro)
|
|
- 📅 v2.0: Marketplace de templates/extensões
|
|
|
|
---
|
|
|
|
## 📋 Checklist de Implementação
|
|
|
|
### Backend
|
|
- [x] Setup inicial (config, database, middleware)
|
|
- [x] Autenticação (JWT, refresh tokens)
|
|
- [x] Repositórios (sem ORM, SQL direto)
|
|
- [x] Serviços (business logic)
|
|
- [x] Handlers (endpoints)
|
|
- [x] Rate limiting
|
|
- [ ] Soft delete & auditoria
|
|
- [ ] Logging estruturado
|
|
- [ ] Testes unitários
|
|
- [ ] Documentação de API
|
|
|
|
### Frontend
|
|
- [x] Login com redirect automático
|
|
- [x] Dashboard superadmin (lista, detalhes, delete)
|
|
- [x] Site institucional
|
|
- [ ] Dashboard da agência (CRM base)
|
|
- [ ] Gestão de clientes
|
|
- [ ] Formulários avançados
|
|
- [ ] Testes e2e
|
|
|
|
### DevOps
|
|
- [x] Docker Compose com todos os serviços
|
|
- [x] Traefik reverse proxy
|
|
- [x] PostgreSQL com seed data
|
|
- [x] Redis e MinIO
|
|
- [ ] CI/CD pipeline
|
|
- [ ] Monitoramento
|
|
- [ ] Backup strategy
|
|
|
|
---
|
|
|
|
## 💡 Notas Importantes
|
|
|
|
### Por Que Sem ORM?
|
|
|
|
- Controle fino sobre queries
|
|
- Performance previsível
|
|
- Menos abstrações, mais explícito
|
|
- Facilita debugging
|
|
- Legível para new devs
|
|
|
|
**Trade-off:** Mais boilerplate de SQL, mas melhor para equipes experientes.
|
|
|
|
### Segurança
|
|
|
|
- JWT + Refresh tokens
|
|
- Password hashing (Argon2)
|
|
- Rate limiting (5 req/min em prod, 30 em dev)
|
|
- CORS configurado
|
|
- Security headers
|
|
- Input validation em frontend + backend
|
|
|
|
### Escalabilidade
|
|
|
|
- Multi-tenant isolado por tenant_id
|
|
- Índices em FK e campos frequentes
|
|
- Redis para cache de sessions
|
|
- MinIO para object storage
|
|
- Stateless backend (escalável horizontalmente)
|
|
|
|
---
|
|
|
|
## 📞 Contatos & Referências
|
|
|
|
- **Repository:** https://git.stackbyte.cloud/erik/aggios.app.git
|
|
- **Documentação detalhada:** `/1. docs/backend-deployment/`
|
|
- **API Reference:** `/1. docs/backend-deployment/API_REFERENCE.md`
|
|
- **Deployment Guide:** `/1. docs/backend-deployment/DEPLOYMENT.md`
|
|
|