photum/backend

Photum Backend API

Backend para o sistema Photum, desenvolvido em Go com Gin Framework.

🚀 Tecnologias

• Go 1.21+
• Gin Framework - Web framework
• PostgreSQL 15 - Banco de dados
• SQLC - Geração de código type-safe para SQL
• JWT - Autenticação via tokens
• Swagger - Documentação da API
• Docker - Containerização

📋 Pré-requisitos

• Go 1.21+
• Docker Desktop
• SQLC - go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
• Swag - go install github.com/swaggo/swag/cmd/swag@latest

⚙️ Setup Rápido

Opção 1: Usando o script PowerShell (Recomendado para Windows)

# Iniciar ambiente completo (banco de dados + aplicação)
.\setup.ps1 dev

# Ou comandos individuais:
.\setup.ps1 db-up          # Apenas iniciar banco de dados
.\setup.ps1 sqlc-generate  # Gerar código SQLC
.\setup.ps1 swagger        # Gerar documentação Swagger
.\setup.ps1 run            # Executar aplicação

Opção 2: Passo a passo manual

# 1. Iniciar o banco de dados PostgreSQL
docker-compose up -d

# 2. Aguardar o banco ficar pronto (5-10 segundos)
# O schema será aplicado automaticamente

# 3. Gerar código SQLC (se houver mudanças nas queries)
sqlc generate

# 4. Gerar documentação Swagger
swag init -g cmd/api/main.go -o docs

# 5. Executar a aplicação
go run cmd/api/main.go

🔧 Configuração

O arquivo .env contém as configurações do ambiente:

APP_ENV=dev
APP_PORT=8080

DB_DSN=postgres://user:pass@localhost:5432/photum?sslmode=disable

JWT_ACCESS_SECRET=troque_essa_chave
JWT_REFRESH_SECRET=troque_essa_tbm
JWT_ACCESS_TTL_MINUTES=15
JWT_REFRESH_TTL_DAYS=30

⚠️ IMPORTANTE: Altere os secrets JWT antes de usar em produção!

📚 Documentação da API

Após iniciar a aplicação, acesse:

Swagger UI: http://localhost:8080/swagger/index.html

🔐 Endpoints Disponíveis

Autenticação (Público)

• POST /auth/register - Registrar novo usuário
• POST /auth/login - Login
• POST /auth/refresh - Renovar access token
• POST /auth/logout - Logout

Protegido (Requer autenticação)

• GET /api/me - Informações do usuário autenticado

🗄️ Estrutura do Banco de Dados

Tabela usuarios

• id (UUID) - Primary Key
• email (VARCHAR) - Único
• senha_hash (VARCHAR) - Hash bcrypt da senha
• role (VARCHAR) - Papel do usuário (default: 'profissional')
• ativo (BOOLEAN) - Status do usuário
• criado_em, atualizado_em (TIMESTAMPTZ)

Tabela refresh_tokens

• id (UUID) - Primary Key
• usuario_id (UUID) - Foreign Key para usuarios
• token_hash (VARCHAR) - Hash SHA256 do token
• user_agent, ip - Informações do dispositivo
• expira_em (TIMESTAMPTZ)
• revogado (BOOLEAN)

Tabela cadastro_profissionais

• Informações detalhadas dos profissionais
• Vinculada a usuarios via usuario_id

🧪 Testando a API

Exemplo de Registro

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "andre.fr93@gmail.com",
    "senha": "j87q9t0"
  }'

Exemplo de Login

curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "andre.fr93@gmail.com",
    "senha": "j87q9t0"
  }'

Testando rota protegida

curl -X GET http://localhost:8080/api/me \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN_AQUI"

🛠️ Comandos Úteis

# Ver logs do banco de dados
docker-compose logs -f postgres

# Parar banco de dados
docker-compose down

# Resetar banco de dados (apaga todos os dados)
docker-compose down -v
docker-compose up -d

# Executar testes
go test -v ./...

# Atualizar dependências
go mod tidy

📁 Estrutura do Projeto

photum-backend/
├── cmd/
│   └── api/
│       └── main.go              # Entry point da aplicação
├── internal/
│   ├── auth/                    # Módulo de autenticação
│   │   ├── handler.go           # Handlers HTTP
│   │   ├── service.go           # Lógica de negócio
│   │   ├── tokens.go            # Geração de tokens JWT
│   │   ├── middleware.go        # Middleware de autenticação
│   │   └── utils.go             # Utilitários (hash de senha)
│   ├── config/                  # Configurações
│   │   └── config.go
│   └── db/
│       ├── schema.sql           # Schema do banco de dados
│       ├── queries/             # Queries SQL
│       │   ├── usuarios.sql
│       │   ├── auth.sql
│       │   └── profissionais.sql
│       └── generated/           # Código gerado pelo SQLC
├── docs/                        # Documentação Swagger (gerada)
├── .env                         # Variáveis de ambiente
├── docker-compose.yml           # Configuração Docker
├── sqlc.yaml                    # Configuração SQLC
├── go.mod                       # Dependências Go
└── README.md

🐛 Troubleshooting

Erro: "failed to register user"

Causa: Banco de dados não está rodando ou não foi inicializado.

Solução:

# Verificar se Docker está rodando
docker ps

# Se não estiver, iniciar o banco
docker-compose up -d

# Aguardar alguns segundos e tentar novamente

Erro: "connection refused"

Causa: PostgreSQL não está acessível.

Solução:

# Verificar logs do container
docker-compose logs postgres

# Reiniciar o container
docker-compose restart postgres

Erro: "relation usuarios does not exist"

Causa: Schema não foi aplicado ao banco.

Solução:

# Resetar banco de dados
docker-compose down -v
docker-compose up -d

📝 Notas de Desenvolvimento

Fluxo de Autenticação

1. Registro: Cria usuário com senha hasheada (bcrypt)
2. Login:
   • Valida credenciais
   • Gera Access Token (JWT, 15 min)
   • Gera Refresh Token (UUID hasheado, 30 dias)
   • Armazena Refresh Token no banco
   • Retorna Access Token + define cookie HttpOnly com Refresh Token
3. Refresh: Usa Refresh Token para gerar novo Access Token
4. Logout: Revoga Refresh Token

Segurança

• Senhas hasheadas com bcrypt (custo 10)
• Refresh Tokens armazenados como SHA256 hash
• Access Tokens JWT assinados com HS256
• Cookies HttpOnly para web (CSRF protection)
• Suporte a tokens no body para mobile

📄 Licença

Este projeto é privado e proprietário.

👥 Contato

Para dúvidas ou suporte, entre em contato com a equipe de desenvolvimento.