Diretrizes

Convenções de Nomenclatura

Interfaces

• Prefixe todas as interfaces com I.
• Exemplo: IProject, ICreateProject

Objetos de Valor

• Use substantivos para objetos de valor, já que eles representam conceitos concretos.
• Exemplo: ProjectAssociation, RiseProjectPayload

Casos de Uso

• Use a convenção de verbo + substantivo para representar ações.
• Exemplo: CreateProject, UpdateStatus

Classes e Serviços

• As implementações de casos de uso ou serviços devem espelhar a interface que implementam ou estendem, sem o prefixo I.
• Exemplo: CreateProjectService para a interface ICreateProject.

Entidades vs Objetos de Valor

• Entidades representam conceitos com identidade que evoluem ao longo do tempo. Use substantivos concretos para seus nomes.
• Objetos de Valor são imutáveis e representam conceitos de domínio sem identidade. Use nomes claros e descritivos para objetos de valor, especialmente quando encapsulam múltiplas propriedades.

Manipulação de Eventos no Kafka

Utilizamos o decorator @EventPattern('events') para escutar eventos que chegam no tópico events do Kafka. Como o Kafka não faz filtragem nativa de mensagens por tipo de evento, a filtragem deve ser feita dentro da lógica do consumidor, utilizando if ou outro mecanismo de validação interno para separar os tipos de evento.

Exemplo:

@EventPattern('events')
handleEvent(@Payload() message) {
  // Lógica para lidar com o evento
  // A variável message que chega no parâmetro do método ja esta serializada caso seja um objeto JSON valido, caso contrario assume o tipo string 
  if (message.type === 'ProjectCreated') {
    // Manipula evento de criação de projeto
  } else if (message.type === 'StatusUpdated') {
    // Manipula evento de atualização de status
  }
}

Autenticação e Autorização

Implementamos a autorização de rotas validando tokens do Keycloak localmente. Os tokens são decodificados e verificados utilizando a chave pública do Keycloak, evitando chamadas constantes ao servidor Keycloak.

Monitoramento de Saúde do Sistema

Endpoints de monitoramento de saúde, como /api/health, estão localizados na camada de infraestrutura, mas a lógica do controlador pode residir na camada de apresentação. Esse endpoint fornece feedback em tempo real sobre componentes do sistema (ex.: Kafka, banco de dados).

Testes Unitários

• Para pastas, arquivos de testes dentro da pasta */test de mesmo nível do código.
• Para controladores, os testes devem verificar o status das respostas, objetos de entrada e saída.
• Para serviços, mockar dependências (ex.: produtores Kafka, serviços de banco de dados) para isolar e testar a lógica de negócios.
• Utilize jest.spyOn para testar se métodos foram chamados e para verificar as saídas.

Configuração e Variáveis de Ambiente

A pasta config contém todas as configurações relacionadas ao ambiente, incluindo strings de conexão, chaves de API e tópicos do Kafka. As variáveis de ambiente são gerenciadas usando o EnvService, garantindo fácil acesso e gerenciamento das configurações externas.

Seguindo este guia, os desenvolvedores manterão padrões de código consistentes, resultando em uma base de código escalável e de fácil manutenção. Este guideline evoluirá conforme o projeto cresce, mas seus princípios principais asseguram uma arquitetura limpa e boas práticas sólidas.