photum/backend/README.md

# 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+](https://golang.org/dl/)
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [SQLC](https://sqlc.dev/) - `go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest`
- [Swag](https://github.com/swaggo/swag) - `go install github.com/swaggo/swag/cmd/swag@latest`

## ⚙️ Setup Rápido

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

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

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

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

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

### Exemplo de Login

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

### Testando rota protegida

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

## 🛠️ Comandos Úteis

```powershell
# 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**:
```powershell
# 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**:
```powershell
# 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**:
```powershell
# 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.