Guia de Contribuição - ecosif-auth¶

Boas-vindas!¶

Obrigado por considerar contribuir com o projeto ecosif-auth! Este documento fornece diretrizes para contribuições.

Como Contribuir¶

1. Reportar Problemas (Issues)¶

Antes de criar uma issue: - Verifique se o problema já foi reportado - Certifique-se de que está usando a versão mais recente - Colete informações relevantes (logs, versão, ambiente)

Ao criar uma issue, inclua: - Descrição clara do problema - Passos para reproduzir - Comportamento esperado vs. atual - Logs relevantes (sem informações sensíveis) - Ambiente (OS, Java version, etc.)

2. Sugerir Melhorias¶

Para sugerir melhorias: - Abra uma issue com label "enhancement" - Descreva o problema que a melhoria resolveria - Explique como a melhoria funcionaria - Inclua exemplos de uso se aplicável

3. Contribuir com Código¶

Processo¶

Fork o repositório
Crie uma branch para sua feature/contribution:
```
git checkout -b feature/minha-feature
```
Faça suas alterações seguindo os padrões do projeto
Teste suas alterações

Commit suas alterações seguindo as convenções:

git commit -m "feat: adiciona nova funcionalidade X"

Push para sua branch:
```
git push origin feature/minha-feature
```
Abra um Pull Request

Padrões de Código¶

Convenções de Nomenclatura¶

Classes: PascalCase (ex: AuthController)
Métodos: camelCase (ex: authenticateUser)
Variáveis: camelCase (ex: userService)
Constantes: UPPER_SNAKE_CASE (ex: DEFAULT_TIMEOUT)
Packages: lowercase (ex: io.ecosif.auth.controller)

Estrutura de Packages¶

io.ecosif.auth
├── controller      # Controllers REST
├── service         # Lógica de negócio
├── repository      # Acesso a dados
├── model           # Entidades JPA
├── dto             # Data Transfer Objects
├── config          # Configurações
├── jwt             # Componentes JWT
├── oauth2          # Componentes OAuth2
├── exception       # Exceções customizadas
└── util            # Utilitários

Anotações Spring¶

Use @Service para serviços de negócio
Use @Repository para repositórios
Use @RestController para controllers REST
Use @Component apenas quando necessário

Validação¶

Valide DTOs de entrada usando Bean Validation (@Valid, @NotBlank, etc.)
Valide lógica de negócio nos Services
Retorne códigos HTTP apropriados

Tratamento de Exceções¶

Use exceções customizadas quando apropriado
Sempre trate exceções no GlobalExceptionHandler
Não exponha detalhes internos em mensagens de erro

Logs¶

Use @Slf4j do Lombok para logging
Use níveis apropriados:
ERROR: Erros que impedem operação
WARN: Situações anômalas mas recuperáveis
INFO: Informações importantes do fluxo
DEBUG: Informações detalhadas para debugging
Não logue informações sensíveis (senhas, tokens)

Documentação¶

Documente endpoints com Swagger (@Operation, @ApiResponses)
Documente métodos públicos com JavaDoc
Mantenha README e documentação atualizados

Testes¶

Tipos de Testes¶

Unitários: Teste classes isoladamente
Integração: Teste interação entre componentes
API: Teste endpoints REST

Convenções¶

Use JUnit 5
Use Mockito para mocks
Teste casos de sucesso e falha
Nomeie testes de forma descritiva: should_ReturnUser_When_UsernameExists

Exemplo de Teste Unitário¶

@ExtendWith(MockitoExtension.class)
class UserServiceImplTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserServiceImpl userService;

    @Test
    void should_ReturnUser_When_UsernameExists() {
        // Given
        String username = "test@example.com";
        User expectedUser = new User();
        expectedUser.setUsername(username);

        when(userRepository.findByUsername(username))
            .thenReturn(expectedUser);

        // When
        User result = userService.findUserByUsername(username);

        // Then
        assertThat(result).isNotNull();
        assertThat(result.getUsername()).isEqualTo(username);
        verify(userRepository).findByUsername(username);
    }
}

Exemplo de Teste de API¶

@SpringBootTest
@AutoConfigureMockMvc
class AuthControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void should_ReturnToken_When_ValidCredentials() throws Exception {
        // Given
        LoginRequest request = new LoginRequest();
        request.setUsername("test@example.com");
        request.setPassword("password");

        // When & Then
        mockMvc.perform(post("/api/auth/signin")
                .contentType(MediaType.APPLICATION_JSON)
                .content(asJsonString(request)))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.accessToken").exists());
    }
}

Convenções de Commit¶

Seguimos o padrão Conventional Commits:

<tipo>(<escopo>): <descrição curta>

[corpo opcional]

[rodapé opcional]

Tipos: - feat: Nova funcionalidade - fix: Correção de bug - docs: Documentação - style: Formatação (não afeta código) - refactor: Refatoração - test: Testes - chore: Tarefas de manutenção

Exemplos:

feat(auth): adiciona suporte a refresh token
fix(jwt): corrige validação de token expirado
docs(api): atualiza documentação do endpoint /api/auth/signin
refactor(service): extrai lógica de validação para método separado
test(controller): adiciona testes para AuthController

4. Review de Código¶

Todos os Pull Requests são revisados. Antes de solicitar review, certifique-se de:

✅ Código segue os padrões do projeto
✅ Testes foram adicionados/atualizados
✅ Testes passam localmente
✅ Documentação foi atualizada
✅ Commits seguem as convenções
✅ Não há conflitos com a branch principal

5. Perguntas e Suporte¶

Para perguntas: - Abra uma issue com label "question" - Entre em contato com a equipe de desenvolvimento - Consulte a documentação em /docs

Ambiente de Desenvolvimento¶

Pré-requisitos¶

Java 17+
Maven 3.6+
PostgreSQL 13+
Docker (opcional, para testes)

Configuração Inicial¶

Clone o repositório
Configure as variáveis de ambiente (veja configuracoes.md)
Execute migrações do Flyway
Execute a aplicação:
```
mvn spring-boot:run
```

Recursos Adicionais¶

Código de Conduta¶

Este projeto segue um Código de Conduta. Ao participar, você concorda em manter este código.

Seja respeitoso e inclusivo
Aceite críticas construtivas
Foque no que é melhor para a comunidade
Mostre empatia com outros membros da comunidade

Agradecimentos¶

Obrigado por contribuir com o ecosif-auth! 🎉