aggios.app/backend/README.md

Backend Go - Aggios

Backend robusto em Go com suporte a multi-tenant, autenticação segura (JWT), PostgreSQL, Redis e MinIO.

🚀 Quick Start

Pré-requisitos

• Docker & Docker Compose
• Go 1.23+ (para desenvolvimento local)

Setup inicial

# 1. Clone o repositório
cd aggios-app

# 2. Copiar variáveis de ambiente
cp .env.example .env

# 3. Iniciar stack (Traefik + Backend + BD + Cache + Storage)
docker-compose up -d

# 4. Verificar status
docker-compose ps
docker-compose logs -f backend

# 5. Testar API
curl -X GET http://localhost:8080/api/health

📚 Endpoints Disponíveis

Autenticação (Público)

# Login
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "senha123"
}

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "aB_c123xYz...",
  "token_type": "Bearer",
  "expires_in": 86400
}

# Registrar novo usuário
POST /api/auth/register
Content-Type: application/json

{
  "email": "newuser@example.com",
  "password": "senha123",
  "confirm_password": "senha123",
  "first_name": "João",
  "last_name": "Silva"
}

# Refresh token
POST /api/auth/refresh
Content-Type: application/json

{
  "refresh_token": "aB_c123xYz..."
}

Usuário (Autenticado)

# Obter dados do usuário
GET /api/users/me
Authorization: Bearer {access_token}

# Logout
POST /api/logout
Authorization: Bearer {access_token}

Health Check

# Status da API e serviços
GET /api/health

# Response
{
  "status": "up",
  "timestamp": 1733376000,
  "database": true,
  "redis": true,
  "minio": true
}

🔐 Autenticação

JWT Structure

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "tenant_id": "acme-tenant-id",
  "exp": 1733462400,
  "iat": 1733376000
}

Headers esperados

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

🏢 Multi-Tenant

Cada tenant tem seu próprio subdomain:

• api.aggios.app - API geral
• acme.aggios.app - Tenant "acme"
• empresa1.aggios.app - Tenant "empresa1"

O JWT contém o tenant_id, garantindo isolamento de dados.

📦 Serviços

PostgreSQL

• Host: postgres (docker) / localhost (local)
• Porta: 5432
• Usuário: aggios
• Database: aggios_db

Redis

• Host: redis (docker) / localhost (local)
• Porta: 6379

MinIO (S3)

• Endpoint: minio:9000
• Console: http://minio-console.localhost
• API: http://minio.localhost

Traefik

• Dashboard: http://traefik.localhost
• Usuário: admin / admin

🛠️ Desenvolvimento Local

Build local

cd backend
go mod download
go mod tidy

# Rodar com hot reload (recomenda-se usar Air)
go run ./cmd/server/main.go

Ambiente local

# Criar .env local
cp .env.example .env.local

# Ajustar hosts para localhost
DB_HOST=localhost
REDIS_HOST=localhost
MINIO_ENDPOINT=localhost:9000

Testes

cd backend
go test ./...
go test -v -cover ./...

📝 Estrutura do Projeto

backend/
├── cmd/server/           # Entry point
├── internal/
│   ├── api/             # Handlers e middleware
│   ├── auth/            # JWT e autenticação
│   ├── config/          # Configuração
│   ├── database/        # PostgreSQL
│   ├── models/          # Estruturas de dados
│   ├── services/        # Lógica de negócio
│   └── storage/         # Redis e MinIO
└── migrations/          # SQL scripts

🔄 Docker Compose

Inicia stack completa:

- Traefik: Reverse proxy + SSL
- PostgreSQL: Banco de dados
- Redis: Cache e sessões
- MinIO: Storage S3-compatible
- Backend: API Go
- Frontend: Next.js (institucional + dashboard)

Comandos úteis

# Iniciar
docker-compose up -d

# Ver logs
docker-compose logs -f backend

# Parar
docker-compose down

# Resetar volumes (CUIDADO!)
docker-compose down -v

🚀 Deploy em Produção

Variáveis críticas

JWT_SECRET=            # 32+ caracteres aleatórios
DB_PASSWORD=           # Senha forte
REDIS_PASSWORD=        # Senha forte
MINIO_ROOT_PASSWORD=   # Senha forte
ENV=production         # Ativar hardening

HTTPS/SSL

• Let's Encrypt automático via Traefik
• Certificados salvos em traefik/letsencrypt/acme.json
• Renovação automática

Backups

# PostgreSQL
docker exec aggios-postgres pg_dump -U aggios aggios_db > backup.sql

# MinIO
docker exec aggios-minio mc mirror minio/aggios ./backup-minio

📱 Integração Mobile

A API é pronta para iOS e Android:

# Não requer cookies (stateless JWT)
# Suporta CORS
# Content-Type: application/json
# Versionamento de API: /api/v1/*

Exemplo React Native:

const login = async (email, password) => {
  const response = await fetch('https://api.aggios.app/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });
  
  const data = await response.json();
  // Salvar data.access_token em AsyncStorage
  // Usar em Authorization header
};

🐛 Troubleshooting

PostgreSQL não conecta

docker-compose logs postgres
docker-compose exec postgres pg_isready -U aggios

Redis não conecta

docker-compose logs redis
docker-compose exec redis redis-cli ping

MinIO issues

docker-compose logs minio
docker-compose exec minio mc admin info minio

Backend crashes

docker-compose logs backend
docker-compose exec backend /root/server # Testar manualmente

📚 Documentação Adicional

• ARCHITECTURE.md - Design detalhado
• Go Gin Documentation
• PostgreSQL Docs
• Traefik Docs
• MinIO Docs

📞 Suporte

Para issues ou perguntas sobre a API, consulte a documentação ou abra uma issue no repositório.

---

Última atualização: Dezembro 2025