erik/aggios.app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: adiciona mapa mental completo do projeto

Browse Source
This commit is contained in:
Erik Silva
2025-12-09 02:07:21 -03:00
parent 44db6195f6
commit 86e4afb916
1 changed files with 529 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

529
1. docs/mapa-mental-projeto.md Normal file
View File

@@ -0,0 +1,529 @@
# 🧠 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`