PontuaFlow API

API para suporte à aplicação de gestão de projetos, desenvolvedores e tarefas com gamificação por pontos.

Sobre   •   Instalação   •   Integração   •   Autor  

---

Sobre o projeto

O PontuaFlow API é uma aplicação backend construída em .NET 8 que suporta a gestão de projetos, tarefas, desenvolvedores e equipes. A aplicação integra um sistema de gamificação, incentivando o progresso através de pontuações bem definidas.

Funcionalidades

• Projetos e Semanas: Controle hierárquico onde Weeks (semanas) possuem numeração única garantida por projeto.
• Desenvolvedores (Devs) e Equipes (DevTeams): Cadastro unificado e associação direta com os projetos.
• Ciclo e Avaliação de Tarefas (Tasks): Atribuição de tarefas ao dev e vinculação à semana específica do projeto.
• Regras de Pontuação (Gamificação): Validação fixa de pontos baseada no resultado da tarefa:
  • 🔴 0 : Zerou / Não deu
  • 🟠 2 : Saiu algo
  • 🟡 3 : Quase
  • 🟢 5 : Deu bom (Meta regular)
  • 🔵 8 : Extra (Superação)
• Métricas e Ranking:
  • Total de Pontos: Soma simples de todos os pontos ganhos em tarefas fechadas por um dev num projeto.
  • Aproveitamento (%): Cálculo fundamentado em ((Pontos Obtidos) / (Quantidade de Tasks Cadastradas * 5)) * 100.
  • Ranking: Lista de Devs de um determinado projeto ordenada do maior para o menor multiplicador/pontuação.

Tecnologias utilizadas

Voltar para o início ↺

Instalação

Iniciando o projeto

Important

Certifique-se de ter os seguintes requisitos antes de iniciar:

1. Clone o repositório

git clone https://github.com/juletopi/PontuaFlowAPI.git
cd PontuaFlowAPI

2. Restaure as dependências do projeto

dotnet restore

3. Configure a string de conexão

Edite o arquivo appsettings.json na raiz da API ou os User Secrets, ajustando com os seus dados locais do PostgreSQL:

"ConnectionStrings": {
  "DefaultConnection": "Host=localhost;Database=PontuaFlowDB;Username=postgres;Password=suasenha"
}

4. Aplique as Migrations

dotnet ef database update

5. Inicie o projeto

dotnet run

Note

O Swagger irá gerar automaticamente a documentação UI dos endpoints da API. Ele estará acessível através da rota http://localhost:<PORTA_LOCAL>/swagger/index.html.

Voltar para o início ↺

Guia de Integração

Para consumir a PontuaFlow API no seu projeto Web (React, Vue, Angular, etc.), siga estes passos práticos:

Important

A API deve estar em execução (servidor ligado) para conseguir responder às requisições do seu outro projeto. Escolha uma das formas abaixo:

• Via Docker (Recomendado): Na raiz deste repositório, rode docker-compose up -d. Isso levanta o banco e a API automaticamente (geralmente em http://localhost:8080).
• Via .NET CLI: Siga o painel de Instalação acima e mantenha o terminal rodando com o comando dotnet run.

1. Configurar a Base URL

Crie uma variável de ambiente no seu frontend apontando para a API (ex: no .env):

VITE_API_BASE_URL=http://localhost:8080/api

Configure o cliente HTTP (ex: Axios) para utilizar essa URL e facilitar as requisições:

import axios from 'axios';

export const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL || 'http://localhost:8080/api',
  headers: { 'Content-Type': 'application/json' }
});

2. Fluxo Relacional de Integração

A regra de negócio exige a seguinte sequência obrigatória de chamadas para o funcionamento correto:

A. Criar o Projeto

const res = await api.post('/projects', { name: "Meu App", description: "Descrição" });
const projectId = res.data.id; // Necessário para as etapas seguintes

B. Registrar Desenvolvedores e Iniciar a Semana Os Devs e Semanas devem pertencer a um projeto existente.

await api.post('/devs', { name: "Maria", projectId });
await api.post('/weeks', { numeroSemana: 1, projectId });

C. Criar Tarefas e Pontuar Vincule a Tarefa ao Projeto, Dev e Semana.

await api.post('/tasks', {
    title: "Tela de Login",
    devId, // ID retornado na criação do Dev
    weekId, // ID retornado na criação da Semana
    projectId,
    pontos: 5 
});

D. Exibir Dashboard (Métricas e Ranking) Chame a rota de métricas que já traz o array ordenado de devs pelo aproveitamento matemático.

const ranking = await api.get(`/metrics/project/${projectId}/ranking`);
console.log(ranking.data);

Voltar para o início ↺

Autor

Júlio Cézar | Juletopi	LinkedIn — Júlio Cézar P. Camargo Email — juliocezarpvh@hotmail.com Facebook — facebook.com/juhletopi Instagram — @juletopi
Portfolio — juletopi.github.io/JCPC_Portfolio

Voltar para o início ↺

---

Feito com ❤️ e ☕ por Juletopi.