Skip to content

Rodando em Desenvolvimento

Instruções completas para rodar frontend e backend localmente.

Backend (FastAPI)

Instalação das dependências

cd backend

# uv instala Python e cria venv automaticamente
uv sync

# Para incluir dependências de dev (ruff, mypy, pytest)
uv sync --group dev

Executar o servidor

# Modo reload (reinicia ao salvar arquivos)
uv run uvicorn app.main:app --reload --port 8000

# Com host explícito (necessário para WSL2 ou Docker)
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

O servidor estará disponível em: - API: http://localhost:8000 - Swagger UI: http://localhost:8000/docs - Health check: http://localhost:8000/health

Estrutura de rotas registradas

GET    /health
GET    /api/v1/deliveries
POST   /api/v1/deliveries
PATCH  /api/v1/deliveries/{id}/assign
PATCH  /api/v1/deliveries/{id}/start
PATCH  /api/v1/deliveries/{id}/complete
PATCH  /api/v1/deliveries/{id}/cancel
GET    /api/v1/drivers
GET    /api/v1/wallets/me
GET    /api/v1/wallets/me/transactions
POST   /api/v1/wallets/withdraw
PUT    /api/v1/locations/me
GET    /api/v1/locations
GET    /api/v1/pricing
PUT    /api/v1/pricing
POST   /api/v1/webhooks/asaas

Lint e formatação

# Checar código (sem modificar)
uv run ruff check app/

# Corrigir automaticamente
uv run ruff check app/ --fix

# Formatar
uv run ruff format app/

# Type check estrito
uv run mypy app

Testes

# Rodar todos os testes
uv run pytest

# Com output verboso
uv run pytest -v

# Rodar arquivo específico
uv run pytest tests/unit/test_pricing.py

# Com cobertura
uv run pytest --cov=app --cov-report=term-missing

Pre-commit hooks

# Instalar hooks (executar uma vez após clonar)
uv run pre-commit install

# Executar manualmente em todos os arquivos
uv run pre-commit run --all-files

Os hooks executam automaticamente ruff check, ruff format e mypy antes de cada commit.

Frontend (Next.js)

Instalação das dependências

cd frontend
npm install

Executar o servidor

npm run dev

O servidor estará disponível em http://localhost:3000.

O Next.js usa App Router com as seguintes rotas:

/                    → Redirect para /admin ou /driver dependendo do role
/(auth)/login        → Página de login
/(admin)/            → Dashboard do admin
/(admin)/deliveries  → Lista e criação de entregas
/(admin)/map         → Mapa com motoristas em tempo real
/(driver)/           → Dashboard do driver
/(driver)/deliveries → Entregas disponíveis e em andamento
/(driver)/wallet     → Carteira e solicitação de saque

Comandos disponíveis

npm run dev          # Servidor de desenvolvimento
npm run build        # Build de produção
npm run start        # Servidor de produção local
npm run lint         # ESLint
npm run lint:fix     # ESLint com correção automática
npm run format       # Prettier (formatar)
npm run format:check # Prettier (verificar)
npm run type-check   # TypeScript sem build

Verificações de qualidade

# TypeScript (sem erros = pronto para commit)
npm run type-check

# ESLint (sem warnings)
npm run lint

# Prettier (verificar formatação)
npm run format:check

Rodando Tudo Junto

Para desenvolvimento simultâneo com hot-reload:

Terminal 1 — Backend: 

cd /path/to/fast_deliv/backend
uv run uvicorn app.main:app --reload --port 8000

Terminal 2 — Frontend: 

cd /path/to/fast_deliv/frontend
npm run dev

Variáveis de Ambiente de Desenvolvimento

Verifique que FRONTEND_URL=http://localhost:3000 no .env do backend, pois isso é usado para configurar o CORS middleware:

# backend/app/main.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=[settings.frontend_url],  # → http://localhost:3000
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Testando a API Manualmente

Via Swagger UI

Acesse http://localhost:8000/docs para a interface interativa do FastAPI.

Para autenticar, obtenha um token JWT do Supabase e use o botão Authorize no topo da página com o valor Bearer <seu-token>.

Via cURL

# Health check
curl http://localhost:8000/health

# Obter token de autenticação (via Supabase)
TOKEN=$(curl -s -X POST \
  "https://<PROJECT>.supabase.co/auth/v1/token?grant_type=password" \
  -H "apikey: <ANON_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"senha123"}' \
  | jq -r '.access_token')

# Listar entregas (como admin)
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/deliveries

Troubleshooting Comum

ModuleNotFoundError: No module named 'app'

# Certifique-se de rodar uvicorn da pasta backend/
cd backend
uv run uvicorn app.main:app --reload

CORS error no browser

Verifique se FRONTEND_URL no .env do backend bate com a URL do frontend.

Invalid token na API

O SUPABASE_JWT_SECRET deve ser o mesmo usado pelo Supabase para assinar os tokens. Verifique em Dashboard > Settings > API > JWT Settings.

connection refused no Supabase

Verifique se SUPABASE_URL está correto e se o projeto Supabase está ativo (não pausado).