diff --git a/1. docs/mapa-mental-projeto.md b/1. docs/mapa-mental-projeto.md new file mode 100644 index 0000000..685ff38 --- /dev/null +++ b/1. docs/mapa-mental-projeto.md @@ -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` +