aggios.app/1. docs/backend-deployment/QUICKSTART.md

# 🎯 Quick Start - Backend + Traefik

## 📋 O que foi criado?

Você agora tem uma arquitetura completa de produção com:

✅ **Backend em Go** com estrutura profissional
✅ **Traefik** como reverse proxy com suporte a multi-tenant
✅ **PostgreSQL** para dados com isolamento por tenant
✅ **Redis** para cache e sessões
✅ **MinIO** para storage S3-compatible
✅ **Docker Compose** com stack completa
✅ **Autenticação JWT** segura
✅ **Multi-tenant** com roteamento automático
✅ **Documentação** completa

## 🚀 Iniciar Desenvolvimento

### 1. Copiar variáveis de ambiente

```bash
cd aggios-app
cp .env.example .env
```

### 2. Iniciar stack com um comando

**Windows:**
```bash
.\scripts\start-dev.bat
```

**macOS/Linux:**
```bash
chmod +x ./scripts/start-dev.sh
./scripts/start-dev.sh
```

**Ou manualmente:**
```bash
docker-compose up -d
```

### 3. Verificar serviços

```bash
docker-compose ps

# OUTPUT esperado:
# NAME              STATUS
# traefik           Up (healthy)
# postgres          Up (healthy)
# redis             Up (healthy)
# minio             Up (healthy)
# backend           Up (healthy)
```

### 4. Testar API

```bash
# Health check
curl http://localhost:8080/api/health

# Response esperado:
# {"status":"up","timestamp":1733376000,"database":true,...}
```

## 📚 Documentação Importante

| Documento | Descrição |
|-----------|-----------|
| [ARCHITECTURE.md](./ARCHITECTURE.md) | Design da arquitetura |
| [API_REFERENCE.md](./API_REFERENCE.md) | Todos os endpoints |
| [DEPLOYMENT.md](./DEPLOYMENT.md) | Deploy e diagramas |
| [SECURITY.md](./SECURITY.md) | Guia de segurança |
| [backend/README.md](./backend/README.md) | Setup do backend |

## 🔄 Estrutura de Pastas

```
aggios-app/
├── backend/                    # ← Backend Go aqui
│   ├── cmd/server/main.go     # Entry point
│   ├── internal/
│   │   ├── api/               # Handlers, middleware, routes
│   │   ├── auth/              # JWT, passwords, tokens
│   │   ├── config/            # Configurações
│   │   ├── database/          # PostgreSQL, migrations
│   │   ├── models/            # Estruturas de dados
│   │   ├── services/          # Lógica de negócio
│   │   └── storage/           # Redis e MinIO
│   ├── migrations/            # SQL scripts
│   ├── go.mod                 # Dependencies
│   ├── Dockerfile             # Para Docker
│   └── README.md              # Backend docs
│
├── aggios.app-institucional/  # Frontend Institucional (Next.js)
├── dash.aggios.app/           # Frontend Dashboard (Next.js)
│
├── docker-compose.yml         # Stack completa
├── .env.example               # Template de env
├── .env                       # Variáveis reais (não committar!)
│
├── traefik/                   # Configuração Traefik
│   ├── traefik.yml           # Main config
│   ├── dynamic/rules.yml      # Dynamic routing rules
│   └── letsencrypt/          # Certificados (auto-gerado)
│
├── backend/internal/data/postgres/  # Inicialização PostgreSQL
│   └── init-db.sql                 # Schema initial
│
├── scripts/
│   ├── start-dev.sh          # Start em Linux/macOS
│   └── start-dev.bat         # Start em Windows
│
├── ARCHITECTURE.md            # Design detalhado
├── API_REFERENCE.md          # Endpoints
├── DEPLOYMENT.md             # Diagrama & deploy
├── SECURITY.md               # Segurança & checklist
└── README.md                 # Este arquivo
```

## 🛠️ Próximos Passos

### 1. Completar Autenticação (2-3 horas)
- [ ] Implementar login com validação real
- [ ] Adicionar password hashing (Argon2)
- [ ] Implementar refresh token logic
- [ ] Testes de autenticação

**Arquivo:** `backend/internal/api/handlers/auth.go`

### 2. Adicionar Endpoints de Usuário (1-2 horas)
- [ ] GET /api/users/me
- [ ] PUT /api/users/me (update profile)
- [ ] POST /api/users/me/change-password
- [ ] DELETE /api/users/me

**Arquivo:** `backend/internal/api/handlers/users.go`

### 3. Implementar Services Layer (2-3 horas)
- [ ] UserService
- [ ] TenantService
- [ ] TokenService
- [ ] FileService

**Pasta:** `backend/internal/services/`

### 4. Adicionar Endpoints de Tenant (1-2 horas)
- [ ] GET /api/tenant
- [ ] PUT /api/tenant
- [ ] GET /api/tenant/members
- [ ] Invite members

**Arquivo:** `backend/internal/api/handlers/tenant.go`

### 5. Implementar Upload de Arquivos (2 horas)
- [ ] POST /api/files/upload
- [ ] GET /api/files/{id}
- [ ] DELETE /api/files/{id}
- [ ] Integração MinIO

**Arquivo:** `backend/internal/api/handlers/files.go`

### 6. Testes Unitários (3-4 horas)
- [ ] Auth tests
- [ ] Handler tests
- [ ] Service tests
- [ ] Middleware tests

**Pasta:** `backend/internal/*_test.go`

### 7. Documentação Swagger (1-2 horas)
- [ ] Adicionar comentários swagger
- [ ] Gerar OpenAPI/Swagger
- [ ] Publicar em `/api/docs`

**Dependency:** `github.com/swaggo/http-swagger`

### 8. Integração com Frontends (2-3 horas)
- [ ] Atualizar CORS_ALLOWED_ORIGINS
- [ ] Criar cliente HTTP no Next.js
- [ ] Autenticação no frontend
- [ ] Redirects de login

### 9. CI/CD Pipeline (2-3 horas)
- [ ] GitHub Actions workflow
- [ ] Build Docker image
- [ ] Push para registry
- [ ] Deploy automático

**Arquivo:** `.github/workflows/deploy.yml`

### 10. Monitoramento (1-2 horas)
- [ ] Adicionar logging estruturado
- [ ] Sentry integration
- [ ] Prometheus metrics
- [ ] Health check endpoint

---

## 📝 Exemplo: Adicionar um novo endpoint

### 1. Criar handler

```go
// backend/internal/api/handlers/agencias.go
package handlers

func (h *AgenciaHandler) ListAgencias(w http.ResponseWriter, r *http.Request) {
    tenantID := r.Header.Get("X-Tenant-ID")
    
    agencias, err := h.agenciaService.ListByTenant(r.Context(), tenantID)
    if err != nil {
        utils.RespondError(w, 500, "error", err.Error(), r.URL.Path)
        return
    }
    
    utils.RespondSuccess(w, 200, agencias, "Agências obtidas com sucesso")
}
```

### 2. Registrar na rota

```go
// backend/internal/api/routes.go
mux.HandleFunc("GET /api/agencias", middleware.Chain(
    agenciaHandler.ListAgencias,
    corsMiddleware,
    jwtMiddleware,
))
```

### 3. Testar

```bash
curl -X GET http://localhost:8080/api/agencias \
  -H "Authorization: Bearer {token}"
```

---

## 🐛 Troubleshooting

### Backend não inicia
```bash
# Ver logs
docker-compose logs -f backend

# Rebuildar
docker-compose build backend
docker-compose up -d backend
```

### PostgreSQL falha
```bash
# Verificar password
cat .env | grep DB_PASSWORD

# Reset database
docker-compose down -v postgres
docker-compose up -d postgres
```

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

# Verificar password
docker-compose exec redis redis-cli -a $(grep REDIS_PASSWORD .env) ping
```

### Certificado SSL
```bash
# Ver status Let's Encrypt
docker-compose logs traefik | grep acme

# Debug Traefik
docker-compose logs -f traefik
```

---

## 🔐 Segurança Inicial

**IMPORTANTE:** Antes de publicar em produção:

```bash
# 1. Gerar secrets seguros
openssl rand -base64 32 > jwt_secret.txt
openssl rand -base64 24 > db_password.txt

# 2. Editar .env com valores seguros
nano .env

# 3. Deletar .env.example
rm .env.example

# 4. Verificar .gitignore
echo ".env" >> .gitignore
git add .gitignore
```

---

## 🚀 Deploy em Produção

1. **Servidor Linux** (Ubuntu 20.04+)
2. **Docker + Compose** instalados
3. **Domain** apontando para servidor
4. **Secrets** em vault (não em .env)

```bash
# 1. Clone repo
git clone <repo> /opt/aggios-app
cd /opt/aggios-app

# 2. Setup secrets
export JWT_SECRET=$(openssl rand -base64 32)
export DB_PASSWORD=$(openssl rand -base64 24)

# 3. Start stack
docker-compose -f docker-compose.yml up -d

# 4. Health check
curl https://api.aggios.app/api/health
```

---

## 📊 Monitoramento

Após deploy em produção:

```bash
# Ver métricas
docker-compose stats

# Ver logs
docker-compose logs -f backend

# Verificar saúde
docker-compose ps

# Acessar dashboards:
# - Traefik: http://traefik.localhost
# - MinIO: http://minio-console.localhost
```

---

## 💬 Próximas Discussões

Quando estiver pronto, podemos implementar:

1. **OAuth2** (Google, GitHub login)
2. **WebSockets** (notificações em tempo real)
3. **gRPC** (comunicação inter-serviços)
4. **Message Queue** (Kafka/RabbitMQ)
5. **Search** (Elasticsearch)
6. **Analytics** (Big Query/Datadog)
7. **Machine Learning** (recomendações)
8. **Blockchain** (auditoria imutável)

---

## 📞 Suporte

Para dúvidas:
1. Consulte a documentação nos links acima
2. Verifique os logs: `docker-compose logs {service}`
3. Leia o arquivo correspondente em `ARCHITECTURE.md`, `API_REFERENCE.md` ou `SECURITY.md`

---

**Status**: ✅ Pronto para desenvolvimento
**Stack**: Go + PostgreSQL + Redis + MinIO + Traefik
**Versão**: 1.0.0
**Data**: Dezembro 2025