TaskForgeAPI

TaskForgeAPI is a RESTful web service built with Spring Boot and Kotlin, designed for task management. It allows authenticated users to create, view, update, and delete tasks, organize them into categories, track status changes with defined transitions, and maintain an audit log of all modifications. The API supports filtering, pagination, optimistic locking for concurrency control, and soft deletion to preserve data integrity.

Features

• Task Management: Create, read, update, and delete tasks with attributes like title, description, due date, status, and category.
• Status Transitions: Enforced state machine for task statuses (TODO → DOING → DONE).
• Categories: Organize tasks into user-defined categories.
• Authentication: JWT-based authentication for secure access.
• Auditing: Event logs for all task changes.
• Filtering and Pagination: Efficient querying with filters and page-based results.
• Concurrency Control: Optimistic locking to handle concurrent updates.
• Soft Deletion: Preserve data integrity by marking tasks as deleted instead of removing them.

Technologies

• Backend: Spring Boot 4.0.4, Kotlin 2.2.21
• Database: PostgreSQL with Flyway for migrations
• Security: Spring Security with JWT
• Documentation: SpringDoc OpenAPI (disabled in config)
• Testing: JUnit 5, TestContainers, H2
• Containerization: Docker

Getting Started

Prerequisites

• Java 17
• Maven 3.6+
• Docker and Docker Compose
• PostgreSQL (or use Docker)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd TaskForgeAPI

2. Configure environment variables (create a .env file or set them):

   • SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/taskforge
   • SPRING_DATASOURCE_USERNAME=your_username
   • SPRING_DATASOURCE_PASSWORD=your_password
   • JWT_SECRET=your_jwt_secret
   • JWT_EXPIRATION_SECONDS=3600
   • SPRING_APP_ADMIN_USER=admin
   • SPRING_APP_ADMIN_PASSWORD=admin_password

3. Run with Docker Compose:

   docker-compose up -d

   This will start PostgreSQL and the app.

Running the Application

• Build and run locally:

  mvn clean install
  mvn spring-boot:run

• The API will be available at http://localhost:8080.

API Endpoints

• Authentication: POST /auth/login
• Tasks: GET/POST/PATCH/DELETE /tasks, PATCH /tasks/{id}/status, GET /tasks/{id}/logs
• Categories: GET/POST/PATCH/DELETE /categories

Refer to the code or generated OpenAPI docs for full details.

Project Structure

• controller/: REST controllers
• service/: Business logic implementations
• repository/: Data access layer
• model/: JPA entities
• dto/: Data transfer objects and mappers
• security/: Authentication and authorization
• config/: Application configurations
• exception/: Custom exceptions

Future Improvements

• OpenAPI Documentation: Enable and enhance OpenAPI documentation for better API discoverability and client generation.
• CI/CD Workflow: Implement a fully functional CI/CD pipeline using GitHub Actions or similar, with automated testing, building, and deployment to a hosted cloud environment (e.g., AWS, Azure, or Heroku) if made publicly available.
• User Roles: Implement role-based access control (e.g., admin, user) to allow features like managing other users' tasks or global categories.

---

TaskForgeAPI

TaskForgeAPI é um serviço web RESTful construído com Spring Boot e Kotlin, projetado para gerenciamento de tarefas. Ele permite que usuários autenticados criem, visualizem, atualizem e excluam tarefas, organizem-nas em categorias, rastreiem mudanças de status com transições definidas e mantenham um log de auditoria de todas as modificações. A API suporta filtragem, paginação, bloqueio otimista para controle de concorrência e exclusão suave para preservar a integridade dos dados.

Funcionalidades

• Gerenciamento de Tarefas: Criar, ler, atualizar e excluir tarefas com atributos como título, descrição, data de vencimento, status e categoria.
• Transições de Status: Máquina de estados imposta para status de tarefas (TODO → DOING → DONE).
• Categorias: Organizar tarefas em categorias definidas pelo usuário.
• Autenticação: Autenticação baseada em JWT para acesso seguro.
• Auditoria: Logs de eventos para todas as mudanças de tarefas.
• Filtragem e Paginação: Consultas eficientes com filtros e resultados baseados em páginas.
• Controle de Concorrência: Bloqueio otimista para lidar com atualizações simultâneas.
• Exclusão Suave: Preservar a integridade dos dados marcando tarefas como excluídas em vez de removê-las.

Tecnologias

• Backend: Spring Boot 4.0.4, Kotlin 2.2.21
• Banco de Dados: PostgreSQL com Flyway para migrações
• Segurança: Spring Security com JWT
• Documentação: SpringDoc OpenAPI (desabilitado na configuração)
• Testes: JUnit 5, TestContainers, H2
• Containerização: Docker

Começando

Pré-requisitos

• Java 17
• Maven 3.6+
• Docker e Docker Compose
• PostgreSQL (ou use Docker)

Instalação

1. Clone o repositório:

   git clone <repository-url>
   cd TaskForgeAPI

2. Configure variáveis de ambiente (crie um arquivo .env ou defina-as):

   • SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/taskforge
   • SPRING_DATASOURCE_USERNAME=seu_usuario
   • SPRING_DATASOURCE_PASSWORD=sua_senha
   • JWT_SECRET=seu_jwt_secret
   • JWT_EXPIRATION_SECONDS=3600
   • SPRING_APP_ADMIN_USER=admin
   • SPRING_APP_ADMIN_PASSWORD=senha_admin

3. Execute com Docker Compose:

   docker-compose up -d

   Isso iniciará PostgreSQL e a aplicação.

Executando a Aplicação

• Construa e execute localmente:

  mvn clean install
  mvn spring-boot:run

• A API estará disponível em http://localhost:8080.

Endpoints da API

• Autenticação: POST /auth/login
• Tarefas: GET/POST/PATCH/DELETE /tasks, PATCH /tasks/{id}/status, GET /tasks/{id}/logs
• Categorias: GET/POST/PATCH/DELETE /categories

Consulte o código ou a documentação OpenAPI gerada para detalhes completos.

Estrutura do Projeto

• controller/: Controladores REST
• service/: Implementações de lógica de negócio
• repository/: Camada de acesso a dados
• model/: Entidades JPA
• dto/: Objetos de transferência de dados e mapeadores
• security/: Autenticação e autorização
• config/: Configurações da aplicação
• exception/: Exceções personalizadas

Melhorias Futuras

• Documentação OpenAPI: Habilitar e aprimorar a documentação OpenAPI para melhor descoberta da API e geração de clientes.
• Fluxo de Trabalho CI/CD: Implementar um pipeline CI/CD totalmente funcional usando GitHub Actions ou similar, com testes automatizados, construção e implantação automática em um ambiente de nuvem hospedado (ex.: AWS, Azure ou Heroku) se tornado disponível publicamente.
• Funções de Usuário: Implementar controle de acesso baseado em funções (ex.: admin, usuário) para permitir recursos como gerenciar tarefas de outros usuários ou categorias globais.