Ir para o conteúdo

Guia de Desenvolvimento Local

Este guia fornece instruções completas para configurar e executar o ambiente de desenvolvimento local do Billings Ease.

Índice

  1. Pré-requisitos
  2. Configuração Inicial
  3. Backend
  4. Frontend Web
  5. Banco de Dados
  6. Variáveis de Ambiente
  7. Executando a Aplicação
  8. Troubleshooting

Pré-requisitos

Software Necessário

Verificar Instalação

go version      # Deve mostrar 1.25.0 ou superior
node --version # Deve mostrar v20+ ou superior
pnpm --version # Deve mostrar v10+ ou superior
psql --version # Deve mostrar 12+ ou superior
git --version

Configuração Inicial

1. Clonar Repositório

git clone https://github.com/seu-usuario/billings-ease.git
cd billings-ease

2. Estrutura do Projeto

billings-ease/
├── billings-ease-backend/    # Backend Go
├── billings-ease-web/        # Frontend React
├── billings-ease-documentation/  # Documentação
└── billings-ease-mobile/     # Mobile (não necessário para web)

Backend

1. Instalar Dependências

cd billings-ease-backend
go mod download

2. Configurar Banco de Dados

Criar banco: 

psql -U postgres
CREATE DATABASE billings_ease_dev;
CREATE USER billings_user WITH PASSWORD 'senha_segura';
GRANT ALL PRIVILEGES ON DATABASE billings_ease_dev TO billings_user;
\q

3. Configurar Variáveis de Ambiente

Criar arquivo de ambiente em billings-ease-backend/ a partir do exemplo:

cp .env.example .env.local
# ou
cp .env.example .env.docker
# ou
cp .env.example .env.test

Para desenvolvimento local, use .env.local:

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=billings_user
DB_PASSWORD=senha_segura
DB_NAME=billings_ease_dev

# JWT
JWT_SECRET=seu-jwt-secret-super-seguro
JWT_REFRESH_SECRET=seu-refresh-secret-super-seguro

# Server
PORT=8080
ENV=local

# CORS
CORS_ORIGIN=http://localhost:5173,http://localhost:3000

# Email (opcional para desenvolvimento)
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=seu-email@gmail.com
SMTP_PASSWORD=sua-senha-app
EMAIL_FROM=noreply@billings-ease.com

# R2 Storage (opcional para desenvolvimento)
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=
R2_ENDPOINT=
R2_PUBLIC_URL=

# OAuth (opcional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
APPLE_CLIENT_ID=
APPLE_TEAM_ID=
APPLE_KEY_ID=
APPLE_PRIVATE_KEY=

# Frontend URL
FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:8080

4. Executar Migrações

# Opção 1: Via script Go
go run ./cmd/migrate

# Opção 2: Via psql
psql -U billings_user -d billings_ease_dev -f migrations/001_add_symbol_id_and_appearance_id_to_observations.sql
# ... executar todas as migrações em ordem

5. Executar Backend

go run ./cmd/api

Ou com air (hot reload): 

air

Backend estará disponível em: http://localhost:8080

Frontend Web

1. Instalar Dependências

cd billings-ease-web
pnpm install

2. Configurar Variáveis de Ambiente

Criar arquivo .env em billings-ease-web/:

VITE_API_URL=http://localhost:8080/api

3. Executar Frontend

pnpm dev

Frontend estará disponível em: http://localhost:5173

Banco de Dados

Setup Inicial

1. Instalar PostgreSQL: 

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# macOS
brew install postgresql
brew services start postgresql

2. Criar Banco: 

createdb billings_ease_dev

3. Executar Migrações: 

cd billings-ease-backend
go run ./cmd/migrate

Reset do Banco (Desenvolvimento)

# CUIDADO: Apaga todos os dados!
dropdb billings_ease_dev
createdb billings_ease_dev
go run ./cmd/migrate

Variáveis de Ambiente

Backend (.env.local/.env.docker/.env.test)

Obrigatórias: - DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME - JWT_SECRET, JWT_REFRESH_SECRET

Opcionais (desenvolvimento): - EMAIL_PROVIDER, SMTP_* - Para envio de emails - R2_* - Para upload de arquivos - GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET - Para OAuth - APPLE_* - Para Apple Sign In

Frontend (.env)

Obrigatória: - VITE_API_URL - URL do backend

Executando a Aplicação

Ordem de Execução

1. Banco de Dados: 

# PostgreSQL deve estar rodando
sudo systemctl start postgresql  # Linux
# ou
brew services start postgresql   # macOS

2. Backend: 

cd billings-ease-backend
go run ./cmd/api

3. Frontend: 

cd billings-ease-web
npm run dev

Verificar Funcionamento

Backend: 

curl http://localhost:8080/health
# Deve retornar: {"status":"ok"}

Frontend: Abrir http://localhost:5173 no navegador

Troubleshooting

Backend não conecta ao banco

Problema: failed to connect to database

Soluções: 1. Verificar PostgreSQL está rodando: 

sudo systemctl status postgresql

  1. Verificar credenciais no .env.local (ou no arquivo de ambiente em uso)

  2. Verificar banco existe: 

    psql -U postgres -l | grep billings_ease_dev

  3. Testar conexão manual: 

    psql -U billings_user -d billings_ease_dev -h localhost

Frontend não conecta ao backend

Problema: Erro de CORS ou conexão recusada

Soluções: 1. Verificar VITE_API_URL no .env do frontend 2. Verificar backend está rodando 3. Verificar CORS no backend permite http://localhost:5173

Migrações falham

Problema: Erro ao executar migrações

Soluções: 1. Verificar banco existe 2. Verificar usuário tem permissões 3. Executar migrações uma por uma para identificar problema 4. Verificar se migrações já foram executadas (idempotência)

Porta já em uso

Problema: port 8080 already in use

Soluções: 1. Mudar porta no .env: 

PORT=8081

  1. Matar processo na porta: 
    lsof -ti:8080 | xargs kill

Próximos Passos

Após setup completo:

  1. Criar usuário admin inicial
  2. Testar login/registro
  3. Configurar OAuth (opcional)
  4. Configurar R2 Storage (opcional)

Referências