Stacker API

Documentacao tecnica oficial do projeto Stacker, uma API REST para gestao de usuarios, habilidades e projetos no contexto de marketplace freelancer.

1. Visao Geral

O Stacker foi estruturado em arquitetura em camadas com separacao clara de responsabilidades entre API, aplicacao, dominio e infraestrutura.

Objetivos principais do sistema:

• Cadastro e autenticacao de usuarios.
• Gestao de habilidades.
• Gestao completa do ciclo de vida de projetos (criacao, atualizacao, inicio, conclusao e cancelamento logico).
• Registro de comentarios em projetos.

Guia para QA e Front-end

Para validacao funcional, testes de contrato e integracao de telas/servicos cliente, consulte o guia dedicado:

• docs/API-Docs.md

Esse material complementar detalha payloads, respostas esperadas, cenarios de erro (400, 401, 404) e checklist de regressao.

2. Arquitetura e Organizacao da Solucao

A solution esta organizada em quatro camadas principais:

• Stacker.API: camada de entrada HTTP (controllers, DI, middleware, autenticacao e OpenAPI).
• Stacker.Application: casos de uso via CQRS com MediatR, handlers, validadores e view models.
• Stacker.Core: entidades de dominio, contratos (Repositories e Services) e enums.
• Stacker.Infrastructure: persistencia com Entity Framework Core, implementacoes de repositorios e servico de autenticacao JWT.

Padroes e abordagens adotadas

• CQRS (Command Query Responsibility Segregation) com MediatR.
• Repository Pattern para desacoplar acesso a dados da camada de aplicacao.
• Validacao em pipeline com FluentValidation + IPipelineBehavior (ValidationBehavior).
• Injecao de Dependencia nativa do ASP.NET Core.
• Tratamento centralizado de erro de validacao via middleware customizado em Program.cs.
• Estrategia hibrida de dados para performance: Dapper para leituras/escritas mais custosas e EF Core para operacoes leves e mapeamento.

3. Stack Tecnica

Runtime e framework

• .NET 10 (net10.0)
• ASP.NET Core Web API

Persistencia e banco

• Entity Framework Core 10
• Npgsql.EntityFrameworkCore.PostgreSQL 10
• Banco alvo: PostgreSQL (via DefaultConnection)

Mensageria interna e validacao

• MediatR.Extensions.Microsoft.DependencyInjection 11.1.0
• FluentValidation 12.1.1

Autenticacao e seguranca

• Microsoft.AspNetCore.Authentication.JwtBearer 10.0.5
• Tokens JWT assinados com HMAC-SHA256
• Hash de senha com SHA-256 (implementado em AuthService)

Documentacao e exploracao da API

• Microsoft.AspNetCore.OpenApi 10.0.3
• Scalar.AspNetCore 2.13.9

Bibliotecas adicionais presentes

• Dapper 2.1.72 (referenciada na camada Stacker.Infrastructure)

4. Features Implementadas

Usuarios

• Criar usuario (POST /api/users)
• Registrar usuario (POST /api/users/register)
• Login com emissao de JWT (POST /api/users/login)
• Listar usuarios ativos (GET /api/users)
• Buscar usuario por id (GET /api/users/{id})
• Atualizar usuario (PUT /api/users/{id})
• Excluir usuario com soft delete (DELETE /api/users/{id} -> Active = false)

Habilidades

• Criar habilidade
• Listar habilidades
• Buscar habilidade por id
• Atualizar habilidade
• Excluir habilidade (remoção fisica)

Projetos

• Criar projeto
• Listar projetos
• Buscar projeto por id
• Atualizar projeto
• Excluir projeto com cancelamento logico (Status = Cancelled)
• Iniciar projeto (POST /api/projects/{id}/start)
• Finalizar projeto (POST /api/projects/{id}/finish)
• Criar comentario em projeto (POST /api/projects/{id}/comments)

Regras de estado de projeto

Status em ProjectStatusEnum:

• Created
• InProgress
• Suspended
• Cancelled
• Finished

Transicoes de negocio implementadas na entidade Project:

• Start() apenas quando status atual for Created.
• Finish() apenas quando status atual for InProgress.
• Cancel() quando status atual for Created ou InProgress.

5. Endpoints HTTP

Base URL local configurada em launchSettings.json:

• HTTP: http://localhost:5172
• HTTPS: https://localhost:7184

Todos os exemplos abaixo usam http://localhost:5172 para facilitar testes locais.

Recurso	Metodo	Rota	Descricao	Codigos principais
Users	GET	/api/users	Lista usuarios ativos	200
Users	GET	/api/users/{id}	Detalhe de usuario	200, 404
Users	POST	/api/users	Cria usuario	201, 400
Users	PUT	/api/users/{id}	Atualiza usuario	204, 400, 404
Users	DELETE	/api/users/{id}	Soft delete de usuario	204, 404
Users	POST	/api/users/login	Autentica e retorna token	200, 400, 401
Users	POST	/api/users/register	Cadastro de usuario (alias de criacao)	201, 400
Skills	GET	/api/skills	Lista habilidades	200
Skills	GET	/api/skills/{id}	Detalhe de habilidade	200, 404
Skills	POST	/api/skills	Cria habilidade	201, 400
Skills	PUT	/api/skills/{id}	Atualiza habilidade	204, 400, 404
Skills	DELETE	/api/skills/{id}	Exclui habilidade	204, 404
Projects	GET	/api/projects	Lista projetos	200
Projects	GET	/api/projects/{id}	Detalhe de projeto	200, 404
Projects	POST	/api/projects	Cria projeto	201, 400, 404
Projects	PUT	/api/projects/{id}	Atualiza projeto	204, 400, 404
Projects	DELETE	/api/projects/{id}	Cancela projeto	204, 404
Projects	POST	/api/projects/{id}/comments	Cria comentario no projeto	204, 400, 404
Projects	POST	/api/projects/{id}/start	Inicia projeto	204, 404
Projects	POST	/api/projects/{id}/finish	Finaliza projeto	204, 404

6. Exemplos de Uso da API

6.1 Criar usuario

curl -X POST "http://localhost:5172/api/users/register" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Maria Silva",
    "email": "maria.silva@empresa.com",
    "birthDate": "1995-04-10T00:00:00",
    "password": "SenhaForte@123",
    "role": "Freelancer"
  }'

6.2 Login

curl -X POST "http://localhost:5172/api/users/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria.silva@empresa.com",
    "password": "SenhaForte@123"
  }'

Exemplo de resposta de sucesso (200):

{
  "email": "maria.silva@empresa.com",
  "token": "<jwt-token>"
}

6.3 Criar habilidade

curl -X POST "http://localhost:5172/api/skills" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "ASP.NET Core"
  }'

6.4 Criar projeto

curl -X POST "http://localhost:5172/api/projects" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API de Marketplace Freelancer",
    "description": "Implementacao de backend para gestao de projetos e contratacoes.",
    "idClient": 1,
    "idFreelancer": 2,
    "totalCost": 12500.00
  }'

6.5 Iniciar e finalizar projeto

curl -X POST "http://localhost:5172/api/projects/1/start"
curl -X POST "http://localhost:5172/api/projects/1/finish"

6.6 Comentar em projeto

curl -X POST "http://localhost:5172/api/projects/1/comments" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Entrega parcial validada. Prosseguir para a proxima etapa.",
    "idUser": 1
  }'

7. Validacoes de Entrada

Validacoes sao aplicadas por comando via FluentValidation e executadas automaticamente no pipeline do MediatR.

Principais regras:

• Usuario: nome obrigatorio e max. 100, email valido, idade minima 18 anos, senha forte, role obrigatoria.
• Projeto: titulo obrigatorio e max. 50, descricao obrigatoria e max. 500, cliente/freelancer validos, custo > 0.
• Skill: descricao obrigatoria e max. 100.
• Comentario: conteudo obrigatorio e max. 500, projeto e usuario validos.

Formato de erro de validacao (400) retornado pela API:

{
  "title": "Falha na validacao",
  "status": 400,
  "detail": "Um ou mais campos estao invalidos.",
  "errors": {
    "Email": ["Informe um e-mail valido."]
  }
}

8. Configuracao de Ambiente

Arquivo: Stacker.API/appsettings.Development.json

Campos obrigatorios:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=...;Port=5432;Database=...;Username=...;Password=..."
  },
  "Jwt": {
    "Key": "sua-chave-secreta-com-tamanho-adequado",
    "Issuer": "stacker-api",
    "Audience": "stacker-clients"
  }
}

9. Como Executar

Pre-requisitos

• SDK .NET 10
• PostgreSQL disponivel

Execucao local

dotnet restore
dotnet run --project Stacker.API

Com o profile padrao de desenvolvimento, a API fica disponivel em:

• http://localhost:5172
• https://localhost:7184

10. Documentacao OpenAPI

Em ambiente de desenvolvimento, a aplicacao expõe especificacao OpenAPI e interface de referencia via Scalar.

• OpenAPI: endpoint mapeado por app.MapOpenApi()
• API Reference: endpoint mapeado por app.MapScalarApiReference()

11. Observacoes Tecnicas

• A API gera JWT no login; a configuracao de autenticacao JWT esta registrada globalmente em Program.cs.
• Exclusao de usuarios e projetos e logica (soft/cancelamento), preservando historico operacional.
• Estrutura pronta para evolucao com testes, versionamento de API e observabilidade.