Skip to content

README.md

Latest commit

 

History

History
284 lines (231 loc) · 11.2 KB

README.md

File metadata and controls

284 lines (231 loc) · 11.2 KB

Backend - Varion Project Management

Este é o backend do sistema de gerenciamento de projetos e tarefas Varion. Ele fornece uma API RESTful robusta para gerenciamento de projetos, tarefas, comentários e to-dos, com validação de dados, status customizados e documentação interativa completa.

📚 Documentação da API

A API possui documentação completa e interativa disponível através do Swagger UI:

A documentação inclui:

  • ✅ Todos os endpoints com exemplos de uso
  • ✅ Esquemas de validação Zod detalhados
  • ✅ Interface para testar requisições ao vivo
  • ✅ Códigos de status e tratamento de erros
  • ✅ Modelos de dados e relacionamentos

✨ Funcionalidades Principais

  • 🔄 CRUD Completo: Projetos, Tarefas, Comentários e Itens de To-do
  • 🗑️ Soft Delete: Proteção contra perda acidental de dados
  • 🎨 Estados Customizáveis: Sistema flexível de status para Projetos e Tarefas
  • 📊 Histórico de Status: Rastreamento completo de mudanças de estado das tarefas
  • ✅ Validação Robusta: Schemas Zod para garantir integridade dos dados
  • 🔄 Migrations: Gerenciamento automatizado de schema do banco de dados
  • 🐳 Docker Ready: Configuração pronta para containerização
  • 🛠️ Utilitários Centralizados: Manipulação padronizada de respostas, erros e validações

🚀 Tecnologias

  • Node.js + Express.js - Runtime e framework web
  • TypeScript - Tipagem forte e desenvolvimento seguro
  • TypeORM - ORM moderno para PostgreSQL
  • Zod - Validação de schemas type-safe
  • Swagger/OpenAPI - Documentação interativa da API
  • JWT - Autenticação segura (planejada)
  • PostgreSQL - Banco de dados relacional

📁 Estrutura de Pastas

src/
├── config/           # Configurações da aplicação
│   ├── app.ts        # Configuração do Express
│   ├── data-source.ts # Configuração do TypeORM
│   └── swagger.ts    # Configuração do Swagger
├── migrations/       # Scripts de migração do banco de dados
│   ├── 20240527-seed-default-states.ts
│   └── 20250527-add-status-history-tables.ts
├── modules/          # Módulos principais da aplicação
│   ├── comment/      # Entidade e schemas de comentários
│   ├── projects/     # CRUD de projetos e histórico de status
│   ├── states/       # Estados customizáveis
│   └── todo/         # Entidade de itens de to-do
├── utils/            # Utilitários reutilizáveis
│   ├── controllerUtils.ts   # Helpers para controllers
│   ├── errorHandler.ts      # Tratamento global de erros
│   ├── requestValidator.ts  # Middleware de validação
│   ├── responseHandler.ts   # Padronização de respostas
│   └── tools/              # Ferramentas auxiliares
├── server.ts         # Ponto de entrada da aplicação
└── swagger-docs.ts   # Definições da documentação Swagger

🔗 Rotas da API

Autenticação (🚧 A ser implementado)

  • POST /auth/login — Autenticar usuário e retornar token JWT
  • POST /auth/register — Registrar novo usuário

Projetos (/projects)

  • POST / — Criar um novo projeto
    • Body: { name: string, description?: string, code: string, stateId?: number }
  • GET / — Listar todos os projetos (informações básicas)
  • GET /:code — Obter detalhes de um projeto pelo seu código único
    • Retorna o projeto com suas tarefas, comentários e estado
  • PUT /:code — Atualizar um projeto existente
    • Body: { name?: string, description?: string, stateId?: number }
  • POST /:code/comments — Adicionar um comentário a um projeto
    • Body: { content: string, author?: string }

Itens de To-do via Projetos (/projects/todo)

  • POST /todo/:code — Adicionar um item de to-do a um projeto (identificado pelo code)
    • Body: { item: string }
  • PUT /todo/:id — Atualizar um item de to-do (marcar como feito/não feito, editar texto)
    • Body: { item?: string, done?: boolean }
  • DELETE /todo/:id — Deletar um item de to-do (soft delete)

Estados Customizáveis (/states)

  • POST / — Criar um novo estado
    • Body: { name: string, color?: string, order?: number }
  • GET / — Listar todos os estados disponíveis
  • PUT /:id — Atualizar um estado existente
    • Body: { name?: string, color?: string, order?: number }
  • DELETE /:id — Remover um estado
    • Nota: Um estado não pode ser removido se estiver em uso por projetos

⚙️ Configuração e Execução

Pré-requisitos

  • Node.js ≥18
  • pnpm (gerenciador de pacotes)
  • PostgreSQL (banco de dados)
  • Docker (opcional, para ambiente containerizado)

Variáveis de Ambiente

Configure as variáveis de ambiente copiando o arquivo de exemplo:

cp .env.example .env
# Edite o arquivo .env com suas configurações

Principais variáveis:

  • DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE
  • PORT (padrão: 3001)
  • NODE_ENV (development/production)
  • FRONTEND_URL (para CORS em produção)

📖 Documentação completa: ../docs/ENVIRONMENT.md

Exemplo de configuração:

# Configuração do Banco de Dados
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=varion
DB_PASSWORD=44ecrR525218rx
DB_DATABASE=project_management

# Configuração da Aplicação
PORT=3001
JWT_SECRET=your-very-strong-jwt-secret
NODE_ENV=development # ou production

Instalação de Dependências

pnpm install

Configuração do Banco de Dados

Opção 1: Via Docker (Recomendado)

# Na raiz do projeto
docker-compose up -d db

Opção 2: PostgreSQL Local

  1. Instale o PostgreSQL em sua máquina
  2. Crie o banco de dados:
CREATE DATABASE project_management;
CREATE USER varion WITH PASSWORD '44ecrR525218rx';
GRANT ALL PRIVILEGES ON DATABASE project_management TO varion;

Migrations do Banco de Dados

Para criar o schema inicial e aplicar migrations pendentes:

pnpm typeorm migration:run -d src/config/data-source.ts

Para gerar uma nova migration após alterações nas entidades:

pnpm typeorm migration:generate src/migrations/NomeDaMigration -d src/config/data-source.ts

Executando Localmente

# Desenvolvimento (com hot reload)
pnpm run start:dev

# Produção
pnpm run build
pnpm run start

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

Executando com Docker

  1. Certifique-se de que o Docker e o Docker Compose estão instalados
  2. Ajuste o arquivo docker-compose.yml na raiz do projeto, se necessário
  3. Suba os serviços:
# Apenas banco de dados
docker-compose up -d db

# Backend e banco (quando disponível)
docker-compose up --build -d backend db

🛠️ Scripts Úteis

  • pnpm run start:dev — Inicia o servidor em modo desenvolvimento com hot reload
  • pnpm run build — Compila o código TypeScript para JavaScript (dist/)
  • pnpm run start — Inicia o servidor em modo de produção
  • pnpm run type-check — Executa checagem de tipos TypeScript
  • pnpm run docs — Abre a documentação Swagger no navegador
  • pnpm run docs:json — Obtém o schema JSON da API

Scripts de Testes

  • pnpm test — Executa todos os testes
  • pnpm test:verbose — Executa testes com saída detalhada
  • pnpm test:coverage — Executa testes e gera relatório de cobertura
  • pnpm test:watch — Executa testes em modo watch

Scripts de Migration

  • pnpm typeorm migration:run — Executa migrations pendentes
  • pnpm typeorm migration:revert — Reverte a última migration
  • pnpm typeorm migration:show — Mostra status das migrations
  • pnpm typeorm migration:generate — Gera nova migration baseada em mudanças

🧪 Testes Automatizados - IMPLEMENTADO ✅

Cobertura de Testes Excelente

Test Suites: 33 passed, 33 total
Tests:       517 passed, 517 total
Coverage:    98.58% statements, 83.06% branches, 96.62% functions, 100% lines

Tipos de Testes Implementados

  • 🔗 Testes de Integração: API completa testada com estados, projetos e todos
  • 🎯 Testes Unitários: Entidades, serviços, schemas e utilitários
  • 🏗️ Testes de Sistema: Request logger, error handling, documentação Swagger
  • 📋 Templates e Mocks: Estrutura reutilizável para novos testes

Documentação de Testes

  • 📚 Documentação Técnica Completa - Análise detalhada da implementação
  • ⚙️ Configurações Jest: Múltiplos ambientes e configurações especializadas
  • 🔧 Setup Automático: Banco de dados e ambiente de teste configurados automaticamente

Estrutura de Testes

src/__tests__/
├── basic.test.ts              # Testes básicos do Jest
├── integration.test.ts        # Testes de integração da API
├── integration/               # Testes específicos por módulo
│   ├── states.integration.test.ts
│   └── todo.integration.test.ts
├── examples/                  # Exemplos de testes
├── mocks/                     # Mocks reutilizáveis
├── setup/                     # Configuração de ambiente de teste
└── templates/                 # Templates para novos testes

🔄 Refatorações Recentes (Maio de 2025)

Centralização de Lógica e Padronização

  • responseHandler.ts: Funções padronizadas para envio de respostas HTTP (sucesso, erro, não encontrado, etc.)
  • requestValidator.ts: Middlewares para validação de corpo (body) e parâmetros (params) usando Zod schemas
  • errorHandler.ts: Middleware global de tratamento de erros e handler para rotas não encontradas
  • controllerUtils.ts: Utilitários para controllers, como findEntityOrThrow para buscar entidades ou retornar 404

Melhorias na Arquitetura

  • Validação com Zod: Todos os schemas de entrada foram padronizados e são validados por middlewares
  • Controllers Enxutos: Delegação de validação para middlewares, foco na lógica de orquestração
  • Serviços Robustos: Mantêm a lógica de negócios principal e interações com o banco de dados
  • Rotas Organizadas: Incluem middlewares de validação antes dos controllers

Correções na Documentação

  • Endpoints de To-do: Corrigidos para usar /projects/todo/
  • Swagger Atualizado: Documentação sincronizada com implementação real
  • API-DOCS.md: Referências de endpoints atualizadas para refletir rotas corretas

Próximos Passos

  • 🔐 Autenticação JWT: Implementação completa do sistema de auth
  • 🧪 Testes Frontend: Implementar testes para React components
  • 🤖 CI/CD Pipeline: GitHub Actions com testes automatizados
  • 📊 Analytics: Métricas de uso e performance dos projetos
  • 🔍 Busca Avançada: Filtros e pesquisa em projetos e tarefas
  • 🌐 Internacionalização: Suporte a múltiplos idiomas
  • ⚡ Cache: Implementação de cache para melhor performance

Última atualização da documentação: 07 de junho de 2025

API desenvolvida com TypeScript, Express, PostgreSQL e 517 testes automatizados 🚀