Aggios App

Plataforma composta por serviços de autenticação, painel administrativo (superadmin) e site institucional da Aggios, orquestrados via Docker Compose.

Visão geral

• Objetivo: permitir que superadministradores cadastrem e gerenciem agências (tenants) enquanto o site institucional apresenta informações públicas da empresa.
• Stack: Go (backend), Next.js 16 (dashboard e site), PostgreSQL, Traefik, Docker.
• Status: Sistema multi-tenant completo com segurança cross-tenant validada, branding dinâmico e file serving via API.

Componentes principais

• backend/: API Go com serviços de autenticação, operadores e CRUD de agências (endpoints /api/admin/agencies e /api/admin/agencies/{id}).
• front-end-agency/: Painel Next.js para agências - branding dinâmico, upload de logos, gestão de perfil e autenticação tenant-aware.
• front-end-dash.aggios.app/: painel Next.js – login do superadmin, listagem de agências, exibição detalhada e exclusão definitiva.
• frontend-aggios.app/: site institucional Next.js com suporte a temas claro/escuro e compartilhamento de tokens de design.
• backend/internal/data/postgres/: scripts de inicialização do banco (estrutura base de tenants e usuários).
• traefik/: reverse proxy e certificados automatizados.

Funcionalidades entregues

v1.4 - Segurança Multi-tenant e File Serving (13/12/2025)

• 🔒 Segurança Cross-Tenant Crítica:

  • Validação de tenant_id em endpoints de login (bloqueio de cross-tenant authentication)
  • Validação de tenant em todas rotas protegidas via middleware
  • Mensagens de erro genéricas (sem exposição de arquitetura multi-tenant)
  • Logs detalhados de tentativas de acesso cross-tenant bloqueadas

• 📁 File Serving via API:

  • Nova rota /api/files/{bucket}/{path} para servir arquivos do MinIO através do backend Go
  • Eliminação de dependência de DNS (files.localhost) - arquivos servidos via api.localhost
  • Headers de cache otimizados (Cache-Control: public, max-age=31536000)
  • CORS e content-type corretos automaticamente

• 🎨 Melhorias de UX:

  • Mensagens de erro humanizadas no formulário de login (sem pop-ups/toasts)
  • Erros inline com ícones e cores apropriadas
  • Feedback em tempo real ao digitar (limpeza automática de erros)
  • Mensagens específicas para cada tipo de erro (401, 403, 404, 429, 5xx)

• 🔧 Melhorias Técnicas:

  • Next.js middleware injetando headers X-Tenant-Subdomain para routing correto
  • TenantDetector middleware prioriza headers customizados sobre Host
  • Upload de logos retorna URLs via API ao invés de MinIO direto
  • Configuração MinIO com variáveis de ambiente MINIO_SERVER_URL e MINIO_BROWSER_REDIRECT_URL

v1.3 - Branding Dinâmico e Favicon (12/12/2025)

• Branding Multi-tenant: Logo, favicon e cores personalizadas por agência
• Favicon Dinâmico: Atualização em tempo real via localStorage e SSR metadata
• Upload de Arquivos: Sistema de upload para MinIO com bucket público
• Rate Limiting: 1000 requisições/minuto por IP

v1.2 - Redesign Interface Flat

• Adoção de design "Flat" (sem sombras), focado em bordas e limpeza visual
• Gestão avançada de agências com filtros robustos
• Detalhamento completo com visualização de branding

v1.1 - Fundação Multi-tenant

• Login de Superadmin com JWT
• Cadastro de Agências
• Proxy Interno Next.js para chamadas autenticadas
• Site Institucional com dark mode

Executando o projeto

1. Pré-requisitos: Docker Desktop e Node.js 20+ (para utilitários opcionais).
2. Variáveis: ajustar .env conforme referências existentes (docker-compose.yml, arquivos config).
3. Subir os serviços:

   docker-compose up --build
   

4. Hosts locais:
   • Painel SuperAdmin: http://dash.localhost
   • Painel Agência: http://{agencia}.localhost (ex: http://idealpages.localhost)
   • Site: http://aggios.app.localhost
   • API: http://api.localhost
   • Console MinIO: http://minio.localhost (admin: minioadmin / M1n10_S3cur3_P@ss_2025!)
5. Credenciais padrão: ver backend/internal/data/postgres/init-db.sql para usuário superadmin seed.

Segurança

• ✅ Cross-Tenant Authentication: Usuários não podem fazer login em agências que não pertencem
• ✅ Tenant Isolation: Todas rotas protegidas validam tenant_id no JWT vs tenant_id do contexto
• ✅ Erro Handling: Mensagens genéricas que não expõem arquitetura interna
• ✅ JWT Validation: Tokens validados em cada requisição autenticada
• ✅ Rate Limiting: 1000 req/min por IP para prevenir brute force

Estrutura de diretórios (resumo)

backend/                            API Go (config, domínio, handlers, serviços)
  internal/
    api/
      handlers/
        files.go                    🆕 Handler para servir arquivos via API
        auth.go                     🔒 Validação cross-tenant no login
      middleware/
        auth.go                     🔒 Validação tenant em rotas protegidas
        tenant.go                   🔧 Detecção de tenant via headers
backend/internal/data/postgres/     Scripts SQL de seed
front-end-agency/                   🆕 Dashboard Next.js para Agências
  app/login/page.tsx               🎨 Login com mensagens humanizadas
  middleware.ts                    🔧 Injeção de headers tenant
front-end-dash.aggios.app/          Dashboard Next.js Superadmin
frontend-aggios.app/                Site institucional Next.js
traefik/                            Regras de roteamento e TLS
1. docs/                            Documentação funcional e técnica

Testes e validação

• Consultar 1. docs/TESTING_GUIDE.md para cenários funcionais.
• Testes de Segurança:
  • ✅ Tentativa de login cross-tenant retorna 403
  • ✅ JWT de uma agência não funciona em outra agência
  • ✅ Logs registram tentativas de acesso cross-tenant
• Testes de File Serving:
  • ✅ Upload de logo gera URL via API (http://api.localhost/api/files/...)
  • ✅ Imagens carregam sem problemas de CORS ou DNS
  • ✅ Cache headers aplicados corretamente

Próximos passos sugeridos

• Implementar soft delete e trilhas de auditoria para exclusão de agências
• Adicionar validação de permissões por tenant em rotas de files (se necessário)
• Expandir testes automatizados (unitários e e2e) focados no fluxo do dashboard
• Disponibilizar pipeline CI/CD com validações de lint/build

Repositório

• Principal: https://git.stackbyte.cloud/erik/aggios.app.git
• Branch: dev-1.4 (Segurança Multi-tenant + File Serving)