eCosif — Autenticação

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

  1. Fork o repositório
  2. Crie uma branch para sua feature/contribution: bash git checkout -b feature/minha-feature
  3. Faça suas alterações seguindo os padrões do projeto
  4. Teste suas alterações
  5. Commit suas alterações seguindo as convenções: bash git commit -m "feat: adiciona nova funcionalidade X"
  6. Push para sua branch: bash git push origin feature/minha-feature
  7. Abra um Pull Request

Padrões de Código

Convenções de Nomenclatura
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
Validação
Tratamento de Exceções
Logs
Documentação

Testes

Tipos de Testes
Convenções
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:

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

Configuração Inicial

  1. Clone o repositório
  2. Configure as variáveis de ambiente (veja configuracoes.md)
  3. Execute migrações do Flyway
  4. Execute a aplicação: bash 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.

Agradecimentos

Obrigado por contribuir com o ecosif-auth! 🎉