Access Control - Solicitação de Acesso a Módulos

Implementação da user story de Solicitação de Acesso para o teste técnico Java Pleno da Supera. O projeto expõe uma API REST protegida por JWT, aplica todas as regras de negócio descritas no enunciado e entrega infraestrutura dockerizada com balanceamento via Nginx e três instâncias da aplicação.

Ambiente em produção

• API: https://cordeirops.dpdns.org/swagger-ui/index.html
• Frontend: https://accesscontrol-frontend.vercel.app/requests

Sumário

1. Arquitetura da Solução
2. Tecnologias e Versões
3. Pré-requisitos
4. Configuração de Ambiente
5. Execução com Docker Compose
6. Execução Local
7. Testes, Cobertura e Relatório JaCoCo
8. Credenciais de Teste
9. Exemplos de Requisições
10. Regras de Negócio Implementadas

Arquitetura da Solução

Visão Geral

• Nginx distribui requisições HTTP entre três instâncias idênticas (app1, app2, app3).
• PostgreSQL 17 recebe as migrações Flyway (estrutura + seeds de usuários e módulos).
• Spring Boot 3.5 provê autenticação JWT, validações e exposição da API REST.
• Swagger acessível via http://localhost/swagger-ui.html através do proxy Nginx.

Diagramas C4

Nível 1: Diagrama de Contexto

Visão macro do sistema e seus atores externos.

Nível 2: Diagrama de Container

Detalha a infraestrutura Docker, balanceamento de carga e comunicação entre containers conforme compose.yaml e nginx.conf.

Nível 3: Diagrama de Componentes

Detalha a estrutura interna da API Spring Boot, mapeando Controllers, Services, Repositories, Validações e Camada de Segurança implementados.

Legenda dos Diagramas

• Nível 1 (Contexto): Mostra o sistema e seus atores externos (usuários, sistemas externos).
• Nível 2 (Container): Detalha a infraestrutura Docker, containers e comunicação entre serviços.
• Nível 3 (Componentes): Expõe a arquitetura interna da aplicação Spring Boot, camadas de segurança, serviços, repositórios e validações.

Tecnologias e Versões

Tecnologia	Versão
Java	21
Spring Boot	3.5.7
Spring Data JPA / Validation / Security	3.5.x
PostgreSQL	17
Flyway	10.x
Docker / Docker Compose	26+ / 2.22+
Nginx	1.27 (alpine)
JWT (auth0 java-jwt)	4.4.0
Instancio	3.7.1
H2 (somente testes)	2.2.224
JUnit 5 / Mockito	5.x / 5.x
JaCoCo	0.8.12

Pré-requisitos

• Docker e Docker Compose instalados.
• Java 21 + Maven 3.9 (caso opte por execução local).
• Arquivo .env na raiz contendo:

  POSTGRES_DATABASE=accesscontrol
  POSTGRES_USER=postgres
  POSTGRES_PASSWORD=postgres
  JWT_SECRET=sua_chave_super_secreta

Gerando o JWT_SECRET

• Linux / Ubuntu

  openssl rand -base64 64 | tr -d '\n'; echo

  Copie o valor exibido acima para a variável JWT_SECRET.

• Windows (PowerShell)

  [Convert]::ToBase64String((New-Object System.Security.Cryptography.HMACSHA256).Key)

  O valor retornado pode ser reutilizado no .env ou em um secret do ambiente.

Configuração de Ambiente

1. Clone o repositório.
2. Crie o .env conforme acima.
3. (Opcional) Ajuste portas no compose.yaml.

Execução com Docker Compose

docker compose up --build

Serviços expostos:

• Nginx (proxy + Swagger): http://localhost
• Aplicações (acesso direto): http://localhost:8080 (caso queira bypass do proxy)
• PostgreSQL: localhost:5432

Health checks:

• http://localhost/actuator/health (via proxy)

Para encerrar e limpar:

docker compose down -v

Execução Local

1. Suba o PostgreSQL localmente (docker ou instalador).
2. Exporte as mesmas variáveis do .env ou configure no application.yml.
3. Execute:

   ./mvnw spring-boot:run

4. Acesse http://localhost:8080/swagger-ui.html.

Testes, Cobertura e Relatório JaCoCo

Executar toda a suíte com H2 in-memory:

./mvnw clean test

• Cobertura mínima configurada: 90% (plugin JaCoCo falha o build abaixo disso).
• Relatórios:
  • HTML: target/site/jacoco/index.html
  • PDF: docs/jacoco-report.pdf (gerado automaticamente após os testes)

Gerar Relatório PDF

O relatório PDF é gerado automaticamente após executar os testes via Maven (mvn verify ou mvn test seguido de mvn jacoco:report).

Para gerar manualmente:

Windows (PowerShell):

.\generate-pdf-report.ps1

Linux/Mac ou Windows (Maven):

./mvnw jacoco:report
./mvnw exec:java -Dexec.mainClass=com.cordeirops.accesscontrol.util.HtmlToPdfConverter

O PDF será gerado/atualizado em docs/jacoco-report.pdf com a cobertura atualizada.

Credenciais de Teste

Departamento	E-mail	Senha
TI	admin.ti@company.com.br	123456
Financeiro	ana.fin@company.com.br	123456
RH	carlos.rh@company.com.br	123456
Operações	joao.ops@company.com.br	123456

Todos os usuários são criados via migrações Flyway (V2__insert_inital_data.sql).

Exemplos de Requisições

Login

curl -X POST http://localhost/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin.ti@company.com.br","password":"123456"}'

Refresh token

curl -X POST http://localhost/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<token obtido no login>"}'

Criar solicitação

curl -X POST http://localhost/access-requests \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "moduleIds":[3,4],
        "justification":"Necessito dos módulos para análises financeiras semanais detalhadas.",
        "urgent":false
      }'

Cancelar solicitação

curl -X POST http://localhost/access-requests/1/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Atividade encerrada"}'

Todas as rotas estão documentadas em /swagger-ui.html.

Regras de Negócio Implementadas

• Autenticação: JWT com expiração de 15 minutos, passwords com BCrypt e SecurityFilter garantindo autorização em todos os endpoints. Refresh tokens persistidos (72h) são emitidos no login e rotacionados via /auth/refresh.
• Solicitação:
  • 1–3 módulos, justificativa 20–500 caracteres, sem textos genéricos (validador customizado).
  • Verificação automática de solicitações pendentes e acessos ativos (renovação respeita exceções).
  • Protocolo único SOL-YYYYMMDD-NNNN.
  • Histórico de alterações persistido (AccessRequestHistory) e vínculo de renovações via parentRequest.
  • Módulos incompatíveis checados tanto entre os solicitados quanto contra os já ativos do usuário.
  • Limite de módulos ativos (5 ou 10 para TI) contabilizando apenas novos módulos.
• Consulta e Detalhes:
  • Filtros por texto, status, período, urgência e paginação (10 itens).
  • Resposta inclui módulos, status, datas, motivo de negação, expiração e histórico completo.
• Renovação:
  • Apenas para solicitações ativas com <30 dias para expirar, criando novo protocolo vinculado.
• Cancelamento:
  • Somente solicitações ativas, exige motivo (10–200 caracteres), revoga acesso e registra histórico.
• Listagem de Módulos:
  • Retorna nome, descrição, departamentos permitidos, flag ativo e lista de incompatibilidades.

Frontend

O código-fonte do frontend React utilizado neste projeto está disponível em https://github.com/cordeirops/accesscontrol-frontend (veja o README.md do repositório para instruções específicas).

---