# 🧠 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`