Files

Erik Silva 86e4afb916 docs: adiciona mapa mental completo do projeto

2025-12-09 02:07:21 -03:00

18 KiB

Raw Blame History

🧠 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               │
│                                         │
└─────────────────────────────────────────┘

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

Setup inicial (config, database, middleware)
Autenticação (JWT, refresh tokens)
Repositórios (sem ORM, SQL direto)
Serviços (business logic)
Handlers (endpoints)
Rate limiting
Soft delete & auditoria
Logging estruturado
Testes unitários
Documentação de API

Frontend

Login com redirect automático
Dashboard superadmin (lista, detalhes, delete)
Site institucional
Dashboard da agência (CRM base)
Gestão de clientes
Formulários avançados
Testes e2e

DevOps

Docker Compose com todos os serviços
Traefik reverse proxy
PostgreSQL com seed data
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

18 KiB Raw Blame History

🧠 Mapa Mental - Projeto Aggios

📌 Visão Geral

🏛️ Arquitetura Geral

🔐 Sistema de Autenticação

Níveis de Acesso

Fluxo de Login

🏢 Estrutura de Tenants

Multi-Tenant Model

🛠️ Tech Stack

Backend

Frontend

Infraestrutura

📊 Banco de Dados

Schema Principal

🔄 Fluxo de Cadastro (Registro de Nova Agência)

📈 Funcionalidades por Módulo

🔷 Superadmin Dashboard

🔶 Dashboard da Agência (Em Desenvolvimento)

🔌 APIs Principais

Autenticação

Agências (Superadmin)

Empresas/Clientes

🚀 Ciclo de Desenvolvimento Atual

v1.1 (dev-1.1) - Em Progresso

Próximas Versões

📋 Checklist de Implementação

Backend

Frontend

DevOps

💡 Notas Importantes

Por Que Sem ORM?

Segurança

Escalabilidade

📞 Contatos & Referências

18 KiB

Raw Blame History