📚 Spring-Uniflow

Plataforma colaborativa para gerenciamento de atividades e grupos com autenticação segura via JWT, notificações em tempo real, controle granular de permissões e perfis de usuários especializados.

🎯 Badges

📋 Visão Geral

O Spring-Uniflow é uma solução enterprise para gerenciamento colaborativo de atividades educacionais, integrando funcionalidades avançadas de segurança, autorização granular e comunicação em tempo real. Ideal para instituições que necessitam de uma plataforma robusta para coordenar grupos, atividades e pagamentos.

✨ Destaques Principais

🔐 Autenticação JWT - Segurança de ponta com tokens JWT e refresh token
👥 Perfis Especializados - Estudantes, Professores e Administradores com permissões distintas
🔔 Notificações em Tempo Real - Sistema de notificações para grupos e broadcast
📊 Controle de Permissões Granular - Autorização baseada em authorities específicas
💳 Gestão de Pagamentos - Integração com sistema de assinaturas e pagamentos
📚 Gerenciamento de Atividades - Criação, entrega e avaliação de atividades
🏫 Estrutura Educacional - Disciplinas, turmas, subgrupos e membros com papéis
📖 Documentação Swagger/OpenAPI - API completamente documentada
🛡️ Validação Robusta - Validação em cascata de dados de entrada

🚀 Tecnologias

Backend

Java 21 - Linguagem principal
Spring Boot 3.5.0 - Framework web e IoT
Spring Security - Autenticação e autorização
Spring Data JPA - Camada de persistência
JWT (Auth0) - Gerenciamento de tokens
Jakarta Validation - Validação de beans
Lombok - Redução de boilerplate

Integrações & Ferramentas

PostgreSQL - Banco de dados relacional
H2 Database - Banco em memória para testes
SpringDoc OpenAPI 3.0 - Documentação automática da API
Jackson Databind - Serialização JSON avançada
JUnit 5 - Framework de testes unitários
Mockito - Mock objects para testes
Maven - Gerenciador de dependências
Docker & Docker Compose - Containerização

🔧 Configuração

Pré-requisitos

Java 21 ou superior
Maven 3.8 ou superior
PostgreSQL 15 ou superior
Docker 20.10+ (opcional, para containerização)
Git para versionamento

Variáveis de Ambiente

Configure as seguintes variáveis no arquivo .env ou application.properties:

# Banco de Dados PostgreSQL
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/uniflow
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=sua_senha_aqui
SPRING_JPA_HIBERNATE_DDL_AUTO=update

# Segurança - JWT
JWT_SECRET_KEY=sua_chave_secreta_super_segura_aqui_com_minimo_32_caracteres
JWT_EXPIRATION_TIME=3600000
JWT_REFRESH_EXPIRATION_TIME=86400000

# Aplicação
SERVER_PORT=8080
SERVER_SERVLET_CONTEXT_PATH=/api
SPRING_APPLICATION_NAME=uniflow

# Swagger/OpenAPI
SPRINGDOC_SWAGGER_UI_ENABLED=true
SPRINGDOC_API_DOCS_PATH=/v3/api-docs

Instalação Local

Clone o repositório

git clone https://github.com/RaphaelMun1z/Spring-Uniflow.git
cd Spring-Uniflow

Configure o banco de dados PostgreSQL

# Criar banco de dados
createdb uniflow

# Ou via psql
psql -U postgres -c "CREATE DATABASE uniflow;"

Configure as variáveis de ambiente

# Copie o arquivo de exemplo (se existir)
cp .env.example .env

# Edite com suas credenciais
nano .env

Instale as dependências e compile
```
mvn clean install
```
Execute a aplicação
```
mvn spring-boot:run
```

Verifique a disponibilidade

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

# Documentação Swagger:
# http://localhost:8080/swagger-ui.html

Docker Compose

Crie o arquivo docker-compose.yml na raiz do projeto:

version: '3.9'

services:
  postgres:
    image: postgres:15-alpine
    container_name: uniflow-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: uniflow
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - uniflow-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: uniflow-app
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/uniflow
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: postgres
      JWT_SECRET_KEY: ${JWT_SECRET_KEY:-sua-chave-secreta-padrao-aqui}
      SPRING_JPA_HIBERNATE_DDL_AUTO: update
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - uniflow-network
    restart: unless-stopped

volumes:
  postgres_data:
    driver: local

networks:
  uniflow-network:
    driver: bridge

Para executar com Docker Compose:

# Construir e iniciar todos os serviços
docker-compose up -d

# Verificar logs
docker-compose logs -f app

# Parar os serviços
docker-compose down

📚 API Endpoints

🔐 Autenticação

Método	Endpoint	Descrição	Autenticação
`POST`	`/auth/signin`	Login com credenciais	❌
`POST`	`/auth/signup`	Registrar novo usuário	❌
`PUT`	`/auth/refresh/{email}`	Renovar token JWT	❌
`POST`	`/auth/forgot-password`	Solicitar redefinição de senha	❌
`POST`	`/auth/reset-password`	Redefinir senha com token	❌

👤 Perfil do Usuário

Método	Endpoint	Descrição	Autenticação
`GET`	`/api/me`	Obter perfil do usuário logado	✅
`PATCH`	`/api/me`	Atualizar perfil pessoal	✅
`GET`	`/api/me/assinaturas`	Listar assinaturas do usuário	✅
`GET`	`/api/me/pagamentos`	Histórico de pagamentos	✅
`GET`	`/api/me/grupos`	Listar grupos do usuário	✅

👥 Gerenciamento de Assinantes

Método	Endpoint	Descrição	Autenticação
`GET`	`/api/assinantes/{id}`	Obter perfil público de assinante	✅
`GET`	`/api/assinantes`	Listar todos os assinantes	✅ ADMIN

💳 Pagamentos e Assinaturas

Método	Endpoint	Descrição	Autenticação
`POST`	`/api/pagamentos`	Processar novo pagamento	✅
`POST`	`/api/pagamentos/registrar-externo`	Registrar pagamento externo	✅ ADMIN
`GET`	`/api/pagamentos/assinantes/{id}`	Histórico de pagamentos	✅ ADMIN

📚 Grupos e Disciplinas

Método	Endpoint	Descrição	Autenticação
`POST`	`/api/grupos`	Criar novo grupo	✅
`GET`	`/api/grupos`	Listar todos os grupos	✅
`GET`	`/api/grupos/{id}`	Detalhes do grupo	✅
`PATCH`	`/api/grupos/{id}`	Editar grupo	✅
`DELETE`	`/api/grupos/{id}`	Excluir grupo	✅
`POST`	`/api/grupos/{id}/convite`	Entrar em grupo com convite	✅
`POST`	`/api/disciplinas`	Criar disciplina	✅ ADMIN
`GET`	`/api/disciplinas`	Listar disciplinas	✅
`PUT`	`/api/disciplinas/{id}`	Atualizar disciplina	✅ ADMIN

🎓 Turmas e Atividades Avaliativas

Método	Endpoint	Descrição	Autenticação
`POST`	`/api/turmas/{id}/atividades-avaliativas`	Criar atividade avaliativa	✅ PROFESSOR
`POST`	`/api/turmas/{id}/subgrupos`	Criar subgrupo de turma	✅ PROFESSOR
`PATCH`	`/api/turmas/{id}/membros/{membroId}`	Alterar papel do membro	✅ PROFESSOR

📝 Entrega e Avaliação de Atividades

Método	Endpoint	Descrição	Autenticação
`GET`	`/api/atividades-entrega/{id}`	Detalhes da entrega	✅
`PATCH`	`/api/atividades-entrega/{id}`	Entregar atividade	✅ ESTUDANTE
`POST`	`/api/atividades-entrega/{id}/avaliar`	Avaliar entrega	✅ PROFESSOR

🔔 Notificações

Método	Endpoint	Descrição	Autenticação
`POST`	`/api/notificacoes/enviar-para-grupo`	Enviar notificação para grupo	✅ ADMIN
`POST`	`/api/notificacoes/enviar-broadcast`	Enviar notificação broadcast	✅ ADMIN
`GET`	`/api/notificacoes`	Listar notificações	✅ ADMIN

⚙️ Administração

Método	Endpoint	Descrição	Autenticação
`GET`	`/api/admin/usuarios`	Listar usuários do sistema	✅ ADMIN
`GET`	`/api/admin/planos`	Listar planos de assinatura	✅ ADMIN
`POST`	`/api/admin/planos`	Criar novo plano	✅ ADMIN
`PUT`	`/api/admin/planos/{id}`	Atualizar plano	✅ ADMIN
`DELETE`	`/api/admin/planos/{id}`	Deletar plano	✅ ADMIN

📖 Exemplo de Uso

1️⃣ Registrar novo usuário

curl -X POST http://localhost:8080/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "João Silva",
    "email": "joao@example.com",
    "senha": "SenhaSegura@123",
    "tipoUsuario": "ESTUDANTE"
  }'

Resposta (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nome": "João Silva",
  "email": "joao@example.com",
  "tipoUsuario": "ESTUDANTE",
  "dataCriacao": "2024-01-15T10:30:00Z"
}

2️⃣ Fazer login e obter token JWT

curl -X POST http://localhost:8080/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao@example.com",
    "senha": "SenhaSegura@123"
  }'

Resposta (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tipo": "Bearer",
  "expiracao": 3600
}

3️⃣ Criar um novo grupo (autenticado)

curl -X POST http://localhost:8080/api/grupos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "nome": "Projeto IA 2024",
    "descricao": "Grupo de estudo em Inteligência Artificial",
    "disciplinaId": "disc-001"
  }'

Resposta (201 Created):

{
  "id": "grupo-001",
  "nome": "Projeto IA 2024",
  "descricao": "Grupo de estudo em Inteligência Artificial",
  "criador": "João Silva",
  "dataCriacao": "2024-01-15T11:00:00Z",
  "membros": 1
}

4️⃣ Obter perfil do usuário autenticado

curl -X GET http://localhost:8080/api/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Resposta (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nome": "João Silva",
  "email": "joao@example.com",
  "tipoUsuario": "ESTUDANTE",
  "dataCriacao": "2024-01-15T10:30:00Z",
  "ultimaAtualizacao": "2024-01-15T10:30:00Z"
}

5️⃣ Renovar token de acesso

curl -X PUT http://localhost:8080/auth/refresh/joao@example.com \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Resposta (200 OK):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tipo": "Bearer",
  "expiracao": 3600
}

🏗️ Arquitetura

Estrutura de Pastas

Spring-Uniflow/
├── src/
│   ├── main/
│   │   ├── java/io/github/raphaelmuniz/uniflow/
│   │   │   ├── controllers/           # Endpoints REST
│   │   │   │   ├── autorizacao/       # Autenticação e autorização
│   │   │   │   ├── usuario/           # Gerenciamento de usuários
│   │   │   │   ├── grupo/             # Grupos, turmas e disciplinas
│   │   │   │   ├── atividade/         # Atividades e entregas
│   │   │   │   ├── assinatura/        # Assinaturas e pagamentos
│   │   │   │   └── notificacao/       # Notificações
│   │   │   ├── services/              # Lógica de negócio
│   │   │   ├── entities/              # Modelos JPA
│   │   │   ├── dto/                   # DTOs (Request/Response)
│   │   │   ├── repositories/          # Acesso a dados
│   │   │   ├── config/                # Configurações (Security, etc)
│   │   │   ├── security/              # Implementações de segurança
│   │   │   ├── exceptions/            # Exceções customizadas
│   │   │   └── UnifloApplication.java # Classe principal
│   │   └── resources/
│   │       ├── application.properties # Configurações padrão
│   │       └── application-prod.properties # Configurações produção
│   └── test/
│       └── java/                      # Testes unitários e de integração
├── pom.xml                            # Dependências Maven
├── docker-compose.yml                 # Orquestração de containers
├── Dockerfile                         # Imagem Docker da aplicação
└── README.md                          # Este arquivo

Padrões Utilizados

MVC Pattern - Separação entre Controllers, Services e Repositories
DTO Pattern - Transferência de dados entre camadas
Repository Pattern - Abstração de acesso a dados via Spring Data JPA
Dependency Injection - Injeção de dependências com Spring
Security by Design - JWT, roles e authorities desde a concepção

🔐 Segurança

Recursos Implementados

🔐 Autenticação JWT - Tokens assinados com chave privada segura
🔄 Refresh Token - Renovação segura de tokens de acesso
👮 Autorização Granular - Controle baseado em roles (ADMIN, PROFESSOR, ESTUDANTE) e authorities específicas
🛡️ Spring Security - Framework robusto de segurança
🔒 Criptografia de Senhas - Uso de algoritmos seguros (BCrypt)
📝 Validação de Entrada - Jakarta Validation em todos os DTOs
🚫 CORS Configurável - Proteção contra requisições não autorizadas
🔑 Controle de Acesso - @PreAuthorize em endpoints sensíveis
📋 Auditoria - Rastreamento de ações críticas (criação, atualização, exclusão)
🌐 HTTPS Ready - Suporte para comunicação segura

Boas Práticas Implementadas

Senhas armazenadas com hash seguro
Tokens com expiração configurável
Separação clara de responsabilidades de segurança
Validação em múltiplas camadas
Tratamento de erros sem exposição de dados sensíveis

🧪 Testes

Executar Testes Unitários

# Rodar todos os testes
mvn test

# Rodar testes de uma classe específica
mvn test -Dtest=NomeTestClass

# Rodar com cobertura de código
mvn test jacoco:report

# Gerar relatório de cobertura
mvn jacoco:report

Executar Testes de Integração

# Com banco de dados H2 em memória
mvn verify

# Com PostgreSQL real (requer DB ativa)
mvn verify -Dspring.profiles.active=integration

Dependências de Teste

JUnit 5 - Framework de testes
Mockito - Criação de mocks para isolamento de testes
Hamcrest - Matchers para assertions mais legíveis
Spring Boot Test - Suporte para testes de integração

🐛 Troubleshooting

Problema: Erro de Conexão com PostgreSQL

Sintoma: org.postgresql.util.PSQLException: Connection to localhost:5432 refused

Solução:

# Verificar se PostgreSQL está rodando
sudo systemctl status postgresql

# Iniciar PostgreSQL se necessário
sudo systemctl start postgresql

# Verificar se banco de dados existe
psql -U postgres -l | grep uniflow

# Se não existir, criar:
psql -U postgres -c "CREATE DATABASE uniflow;"

Problema: Erro de Chave JWT Inválida

Sintoma: JWT signature does not match locally computed signature ou JWT claims set cannot be parsed

Solução:

# Garantir que JWT_SECRET_KEY está definida corretamente
# Mínimo 32 caracteres recomendado
export JWT_SECRET_KEY="sua-chave-super-segura-com-minimo-32-caracteres"

# Reiniciar a aplicação
mvn spring-boot:run

Problema: Acesso Negado em Endpoints

Sintoma: 403 Forbidden ao fazer requisições autenticadas

Solução:

Verificar se token JWT está correto no header Authorization: Bearer {token}

Verificar se o usuário tem as authorities necessárias:

# Ver authorities do usuário
curl -X GET http://localhost:8080/api/me \
  -H "Authorization: Bearer {seu-token}"

Verificar permissões no banco de dados

Problema: Build Maven Falha

Sintoma: [ERROR] Failed to execute goal... durante mvn clean install

Solução:

# Limpar cache Maven
mvn clean

# Forçar download de dependências
mvn dependency:resolve-plugins

# Tentar build novamente
mvn clean install -U

Problema: Porta 8080 já Está em Uso

Sintoma: Address already in use: bind

Solução:

# Encontrar processo usando porta 8080
lsof -i :8080

# Matar processo (Unix/Linux/Mac)
kill -9 <PID>

# Ou usar porta diferente
mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

Problema: Docker Container Falha ao Iniciar

Sintoma: docker-compose up retorna erro

Solução:

# Verificar logs
docker-compose logs app

# Parar e remover containers
docker-compose down -v

# Reconstruir imagem
docker-compose build --no-cache

# Iniciar novamente
docker-compose up -d

📝 Contribuição

Contribuições são bem-vindas! Siga este guia para contribuir:

1. Fork o Repositório

# Clique no botão "Fork" no GitHub
# Ou clone seu fork
git clone https://github.com/SEU-USERNAME/Spring-Uniflow.git
cd Spring-Uniflow

2. Criar Branch para Feature

# Atualizar branch main local
git checkout main
git pull upstream main

# Criar nova branch para sua feature
git checkout -b feature/descricao-da-feature

# Exemplo de nomes válidos:
# feature/novo-endpoint-usuarios
# bugfix/corrigir-validacao-jwt
# docs/melhorar-documentacao-api

3. Fazer Mudanças

# Editar arquivos necessários
# Manter commits atômicos e com mensagens descritivas

git add .
git commit -m "Adicionar nova funcionalidade X

- Descrição detalhada da mudança
- Por que esta mudança é necessária
- Como testar"

4. Push e Criar Pull Request

# Push para seu fork
git push origin feature/descricao-da-feature

# Ir para GitHub e criar Pull Request
# Descrever mudanças, relacionar issues se houver
# Esperar review da comunidade

5. Padrões de Código

Use Java 21 com features modernas
Siga Google Java Style Guide
Adicione Javadoc para métodos públicos
Escreva testes unitários para novas funcionalidades
Use lombok para reduzir boilerplate
Mantenha cobertura de código > 80%

6. Antes de Submeter PR

# Rodar testes
mvn clean test

# Verificar cobertura
mvn jacoco:report

# Formatar código
mvn spotless:apply

# Build final
mvn clean package

📞 Suporte e Contato

Documentação

📖 Documentação Swagger - Disponível localmente
📚 Spring Boot Documentation
🔐 Spring Security Guide

Reporte de Issues

🐛 Issues do Projeto
Descrever comportamento esperado vs observado
Incluir stack trace e versões do ambiente

Comunidade

💬 Discussões no GitHub Discussions
🤝 Pull Requests são sempre bem-vindos
📧 Entre em contato via issues para dúvidas maiores

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.mvn/wrapper		.mvn/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
hs_err_pid13772.log		hs_err_pid13772.log
hs_err_pid9900.log		hs_err_pid9900.log
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml
replay_pid13772.log		replay_pid13772.log
replay_pid9900.log		replay_pid9900.log

Folders and files

Latest commit

History

Repository files navigation

📚 Spring-Uniflow

🎯 Badges

📋 Visão Geral

✨ Destaques Principais

🚀 Tecnologias

Backend

Integrações & Ferramentas

🔧 Configuração

Pré-requisitos

Variáveis de Ambiente

Instalação Local

Docker Compose

📚 API Endpoints

🔐 Autenticação

👤 Perfil do Usuário

👥 Gerenciamento de Assinantes

💳 Pagamentos e Assinaturas

📚 Grupos e Disciplinas

🎓 Turmas e Atividades Avaliativas

📝 Entrega e Avaliação de Atividades

🔔 Notificações

⚙️ Administração

📖 Exemplo de Uso

1️⃣ Registrar novo usuário

2️⃣ Fazer login e obter token JWT

3️⃣ Criar um novo grupo (autenticado)

4️⃣ Obter perfil do usuário autenticado

5️⃣ Renovar token de acesso

🏗️ Arquitetura

Estrutura de Pastas

Padrões Utilizados

🔐 Segurança

Recursos Implementados

Boas Práticas Implementadas

🧪 Testes

Executar Testes Unitários

Executar Testes de Integração

Dependências de Teste

🐛 Troubleshooting

Problema: Erro de Conexão com PostgreSQL

Problema: Erro de Chave JWT Inválida

Problema: Acesso Negado em Endpoints

Problema: Build Maven Falha

Problema: Porta 8080 já Está em Uso

Problema: Docker Container Falha ao Iniciar

📝 Contribuição

1. Fork o Repositório

2. Criar Branch para Feature

3. Fazer Mudanças

4. Push e Criar Pull Request

5. Padrões de Código

6. Antes de Submeter PR

📞 Suporte e Contato

Documentação

Reporte de Issues

Comunidade

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages