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

```bash
# 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)

```bash
# 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
}
```

```bash
# 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"
}
```

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

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

### Usuário (Autenticado)

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

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

### Health Check

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

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

## 🔐 Autenticação

### JWT Structure

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

### Headers esperados

```bash
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

```bash
cd backend
go mod download
go mod tidy

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

### Ambiente local

```bash
# Criar .env local
cp .env.example .env.local

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

### Testes

```bash
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:

```yaml
- 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

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

```env
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

```bash
# 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:

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

Exemplo React Native:

```javascript
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
```bash
docker-compose logs postgres
docker-compose exec postgres pg_isready -U aggios
```

### Redis não conecta
```bash
docker-compose logs redis
docker-compose exec redis redis-cli ping
```

### MinIO issues
```bash
docker-compose logs minio
docker-compose exec minio mc admin info minio
```

### Backend crashes
```bash
docker-compose logs backend
docker-compose exec backend /root/server # Testar manualmente
```

## 📚 Documentação Adicional

- [ARCHITECTURE.md](../ARCHITECTURE.md) - Design detalhado
- [Go Gin Documentation](https://gin-gonic.com/)
- [PostgreSQL Docs](https://www.postgresql.org/docs/)
- [Traefik Docs](https://doc.traefik.io/)
- [MinIO Docs](https://docs.min.io/)

## 📞 Suporte

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

---

**Última atualização**: Dezembro 2025