Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
341 lines (270 loc) · 7.67 KB

DEVELOPMENT.md

File metadata and controls

341 lines (270 loc) · 7.67 KB

Guia de Desenvolvimento - Varion

🛠️ Ambiente de Desenvolvimento

Este guia abrange todas as informações necessárias para configurar e trabalhar no ambiente de desenvolvimento do Varion.

📋 Pré-requisitos

Softwares Obrigatórios

Editores Recomendados

  • Visual Studio Code com extensões:
    • TypeScript
    • Prettier
    • ESLint
    • Thunder Client (para testes de API)
    • Docker

🚀 Configuração Inicial

1. Clone do Repositório

git clone <repository-url>
cd Varion

2. Instalação de Dependências

# Instalar dependências do workspace
pnpm install

# Verificar instalação
pnpm list --depth=0

3. Configuração de Ambiente

# Backend
cp backend/.env.example backend/.env
# Editar variáveis conforme necessário

# Frontend
cp frontend/.env.example frontend/.env
# Configurar URL da API

4. Banco de Dados Local

# Opção 1: Docker (Recomendado)
docker-compose up -d postgres

# Opção 2: PostgreSQL local
# Criar database 'varion_dev'
createdb varion_dev

🏃‍♂️ Executando o Projeto

Desenvolvimento com Docker

# Executar todos os serviços
docker-compose up --build

# Executar apenas o banco
docker-compose up -d postgres

# Ver logs
docker-compose logs -f [service-name]

Desenvolvimento Local

# Terminal 1: Backend
cd backend
pnpm start:dev

# Terminal 2: Frontend
cd frontend
pnpm dev

# Terminal 3: Banco (se não usar Docker)
# Executar PostgreSQL localmente

📁 Estrutura do Projeto

Workspace Root

Varion/
├── backend/              # API Node.js + TypeScript
├── frontend/             # Interface Next.js + React
├── docs/                 # Documentação global
├── scripts/              # Scripts de automação
├── docker-compose.yml    # Configuração Docker
├── pnpm-workspace.yaml   # Configuração workspace
└── README.md            # Documentação principal

Backend Structure

backend/
├── src/
│   ├── controllers/      # Controladores da API
│   ├── entities/         # Entidades TypeORM
│   ├── middlewares/      # Middlewares Express
│   ├── routes/           # Definição de rotas
│   ├── services/         # Lógica de negócio
│   ├── types/            # Tipos TypeScript
│   ├── utils/            # Utilitários
│   └── app.ts           # Configuração do Express
├── docs/                 # Documentação específica
├── tests/                # Testes automatizados
├── Dockerfile           # Build de container
└── package.json         # Dependências backend

Frontend Structure

frontend/
├── src/
│   ├── app/              # App Router (Next.js 15)
│   ├── components/       # Componentes React
│   ├── hooks/            # Custom hooks
│   ├── types/            # Tipos TypeScript
│   ├── utils/            # Utilitários
│   └── styles/           # Estilos globais
├── public/               # Assets estáticos
├── docs/                 # Documentação específica
└── package.json         # Dependências frontend

🔧 Scripts de Desenvolvimento

Backend Scripts

cd backend

# Desenvolvimento
pnpm start:dev          # Servidor com hot reload
pnpm build             # Build para produção
pnpm start             # Executar build de produção

# Banco de Dados
pnpm migration:generate # Gerar migration
pnpm migration:run      # Executar migrations
pnpm migration:revert   # Reverter última migration

# Testes
pnpm test              # ✅ Executar todos os testes (517 testes)
pnpm test:watch        # ✅ Testes em modo watch
pnpm test:coverage     # ✅ Cobertura (98.58% atual)
pnpm test:verbose      # ✅ Testes com logs detalhados

# Qualidade de Código
pnpm lint              # ESLint
pnpm format            # Prettier

Frontend Scripts

cd frontend

# Desenvolvimento
pnpm dev               # Servidor de desenvolvimento
pnpm build             # Build para produção
pnpm start             # Executar build de produção

# Qualidade de Código
pnpm lint              # Next.js ESLint
pnpm lint:fix          # Corrigir problemas ESLint
pnpm format            # Prettier
pnpm type-check        # Verificação TypeScript

Workspace Scripts

# Executar em todos os projetos
pnpm -r [command]      # Recursivo em todos

# Executar em projeto específico
pnpm --filter backend [command]
pnpm --filter frontend [command]

🐛 Debug e Logs

Backend Debug

# Debug mode
DEBUG=app:* pnpm start:dev

# Logs de diferentes níveis
LOG_LEVEL=debug pnpm start:dev

Frontend Debug

# Debug mode
NEXT_DEBUG=1 pnpm dev

# Análise de bundle
pnpm build --analyze

Docker Debug

# Logs de serviço específico
docker-compose logs -f backend

# Executar comandos no container
docker-compose exec backend sh
docker-compose exec frontend sh

# Inspecionar container
docker inspect varion-backend

🔄 Workflow de Desenvolvimento

1. Feature Development

# 1. Criar branch feature
git checkout -b feature/nome-da-feature

# 2. Desenvolvimento iterativo
# - Implementar no backend se necessário
# - Implementar no frontend
# - Tester localmente

# 3. Testes
pnpm test              # ✅ Backend: 517 testes passando (98.58% cobertura)
pnpm --filter frontend lint    # Frontend: Lint (testes em desenvolvimento)

# 4. Commit
git add .
git commit -m "feat: descrição da feature"

2. Testes Locais

# Testar integração completa
docker-compose up --build

# Verificar endpoints
curl http://localhost:3001/api/health
curl http://localhost:3001/api/projects

# Testar interface
# Abrir http://localhost:3000

3. Code Review

  • Verificar tipagem TypeScript
  • Testar responsividade
  • Verificar performance
  • Validar UX/UI

🔍 Troubleshooting

Problemas Comuns

Port já em uso

# Encontrar processo usando a porta
lsof -i :3000
lsof -i :3001

# Parar processo
kill -9 <PID>

Problemas de Cache

# Limpar cache pnpm
pnpm store prune

# Limpar cache Next.js
cd frontend && rm -rf .next

# Limpar cache Docker
docker system prune -a

Problemas de Banco

# Resetar banco Docker
docker-compose down -v
docker-compose up -d postgres

# Verificar conexão
docker-compose exec postgres psql -U postgres -d varion

TypeScript Errors

# Verificar tipos
pnpm --filter backend type-check
pnpm --filter frontend type-check

# Reinstalar tipos
rm -rf node_modules/@types
pnpm install

📈 Performance

Monitoramento Local

# Análise de bundle Frontend
pnpm --filter frontend build --analyze

# Profiling Backend
NODE_ENV=development node --inspect src/app.ts

Métricas Importantes

  • Build time: < 30s para frontend
  • Start time: < 5s para backend
  • Hot reload: < 2s
  • Bundle size: < 1MB frontend

🔗 Links Úteis

📞 Suporte

Para problemas de desenvolvimento:

  1. Verificar troubleshooting acima
  2. Consultar documentação específica em /backend/docs/ ou /frontend/docs/
  3. Buscar no histórico de issues do Git
  4. Criar issue detalhada se necessário