Arquitetura do Sistema

Descrição

Esta seção irá abordar a arquitetura selecionada para o Backend e Frontend, além dos dados relativos ao deploy.

Sumário

• Arquitetura do Sistema
  • Descrição
  • Sumário
  • GitFlow
    • Instalação do Git
    • Git Branching Model
    • Padrões de Commit
    • Code Review
    • Git Hands On
  • Arquitetura Geral da Aplicação
  • Deploy
    • Recipes API
    • Diagrama de Deploy
  • Backend
    • Definições de Tecnologias
    • Módulos do Sistema
    • Diagrama de Fluxo
  • Frontend
    • Definições de Tecnologias
    • Módulos do Sistema
    • Diagramas de Componentes
    • Diagrama do Sistema

GitFlow

Nas seções abaixo será ensinado a instalação do Git em sua máquina de acordo com seu sistema operacional. Também, iremos discorrer a respeito do Gitflow adotado para o projeto e seu fluxo de desenvolvimento.

Instalação do Git

Download

Faça o download e instale o Git a partir deste link, selecionando seu sistema operacional.

Ao final da instalação, abra o Git Bash (caso esteja usando Windows) ou um terminal, e digite git –version. Ao retornar a versão do Git, significa que a instalação foi bem sucedida.

Nota: Usuários de Linux e Mac já possuem o Git nativamente. Para verificar, abra um terminal e digite git –version. Caso retorne a versão do Git, significa que o mesmo está devidamente instalado em sua máquina.

Configuração Git e GitLab

Abaixo será ensinado algumas configurações iniciais do Git.

Configurações Iniciais

Caso esteja utilizando o Git pela primeira vez, rode os comandos abaixo para configurar, respectivamente, seu nome e seu email. Substitua os valores entre aspas pelos seus dados.

git config --global user.name "YOUR_FULL_NAME"

git config --global user.email "YOUR_EMAIL"

Git Branching Model

Utilizaremos o modelo de gestão de branches tradicional, realizando algumas adaptações baseadas no Trunked Based Development. As alterações que faremos são:

• Não utilizaremos branches de hotfix/*, visto que na AGES não há situações onde um ajuste do produto entregue será integrado antes do final da sprint corrente;
• Integração da branch de release/* com a branch de develop/*, com o propósito de unificar suas funcionalidades;
• Substituição da branch de feature por um modelo voltado a tarefa, reduzindo seu ciclo de vida e seu número de commits. Esta branch será deletada após o merge.

O desenvolvimento nos repositórios frontend e backend deverá seguir o fluxo descrito abaixo:

• Uma branch master com o código atualmente em produção;
• Uma branch develop com o código em desenvolvimento, com funcionalidades finalizadas mas ainda em fase de testes para validação. Esta sempre será a branch mais atualizada; *feature branches para tasks relacionadas às user stories a serem desenvolvidas. Uma branch de task deve ser nomeada com o número único da task, seguida da breve descrição da task (por exemplo, feature/t01-login ou feature/t05-dropdown-list-login);
• Quando uma feature é finalizada, um PR da branch feature/ relacionada é aberto com destino à branch develop.

O código da develop é integrado com a master ao final da sprint, após validação dos stakeholders do que foi desenvolvido.

Dessa forma, o fluxo usual de trabalho é o seguinte:

1. Antes de iniciar o desenvolvimento de uma task, fazer checkout para a branch develop e pegar as últimas atualizações (pull);
2. Criar uma branch para a task com o ID da task (feature/tXX-YYYYY);
3. "Enviar" a branch para o remoto (git push -u origin feature/tXX-YYYYY);
4. Desenvolver, commitar mudanças e atualizar o remoto (push);
5. Voltar para o item 4 até finalizar a task;
6. Abrir um PR com destino à branch develop;
7. Mover o card da task no Trello para a lista Code Review e avisar no Discord (canal #code-review) que a task está pronta para review;

Padrões de Commit

Quando realizar um commit, tente manter o seguinte padrão nas mensagens:

• Título: número da task e breve descrição da mudança.;
• Se preciso, adicione um descrição mais longa da mudança, do porquê ela se faz necessária ou do porquê foi feito dessa forma; essa descrição longa deve estar separada do título por uma linha em branco;
• Se mais de uma pessoa participou das mudanças do commit: indique a co-autoria conforme exemplo abaixo, também separada por uma linha em branco da descrição longa (o Git precisa de um formato bem específico nessa parte, com uma pessoa por linha; não é preciso adicionar uma linha para a pessoa que está fazendo o commit, porque o Git já pega isso automaticamente).

Exemplo de mensagem de commit e descrição:

#01: Desenvolvimento da tela de login

Criada tela de login e definida rotas, a construção do componente de seleção do perfil não faz parte dessa task.

Co-authored-by: Marcos Silva <[email protected]>

Code Review

Após o desenvolvimento de uma task, um pull/merge request (PR) deve ser aberto com destino à branch develop do repositório relativo à task. Todos os PRs são revisados por pelo menos dois AGES III, que se responsabilizam por garantir a qualidade do que foi desenvolvido e que os artefatos e estruturas se adequem aos padrões definidos neste documento.

Os AGES III se comprometem a revisar os PRs o mais rápido possível, garantindo que PRs abertos até dois dias antes de uma entrega serão integrados (se cumprirem todas as regras do code review).

Git Hands On

Esta seção é dedicada ao teste da configuração do seu ambiente, bem como a prática do Gitflow do projeto. O hands on consiste em atualizar o README do repositório da Wiki com o seu nome e seu nível AGES, além de, ao final, submeter seu primeiro Pull Request.

Passo 1: Clonar o repositório da Wiki

Efetue o clone do repositorio da Wiki via HTTPS e abra o projeto com um editor de texto. Link: https://tools.ages.pucrs.br/ficai-4.0/ficai-4.0-wiki

Passo 2: Criando uma branch nova

A partir da branch main, crie uma nova branch seguindo o comando abaixo:

git checkout -b seuPrimeiroNome-handson

Passo 3: Editando o README.md

Abra o arquivo README.md e atualize a tabela de membros com seu nome e seu nível AGES.

Passo 4: Commit em suas mudanças

Efetue o commit das suas mudanças rodando os comandos abaixo

git add .
git commit -m “Add my name to the table”

Passo 5: Submetendo um pull request

Após efetuar o commit, rode o comando abaixo para enviar suas modificações para o repositório remoto:

git push origin seuPrimeiroNome-handson

Nota: Provavelmente, ao efetuar o push, o GitLab irá requisitar suas credenciais.

Após efetuar, vá no painel do GitLab, procure pelo repositório Ficai-4.0 Wiki e, no menu lateral procure por Merge Request. Na opção “Select source branch” selecione a branch que você criou e clique em “Compare branches and continue”.

Dentro do merge request, mantenha as informações padrão, porém, na opção Reviewer, marque um dos AGES III para fazer a revisão. Após isso, clique em “Create merge request” e aguarde a aprovação.

Com este fluxo completo e bem sucedido, significa que seu ambiente está devidamente configurado para utilizar os repositórios do FICAI 4.0.

Arquitetura Geral da Aplicação

TBD

Deploy

Recipes API

TBD

Diagrama de Deploy

TBD

Backend

Definições de Tecnologias

• Java
• Spring Boot
• PostgreSQL

Dependências

• Spring Boot Starter Data JPA
• Spring Boot Starter Validation
• Spring Boot Starter Web
• PostgreSQL JDBC Driver
• Springdoc Openapi UI

Diagrama de Fluxo

Abaixo uma imagem representando o fluxo de interação entre as camadas do projeto:

• Controller: A camada de Controllers faz o "primeiro contato" com as requisições, enviando às camada mais internas da aplicação apenas as informações relevantes para completar a requisição. Além disso, essa é a camada que irá enviar a resposta ao cliente, seja ela positiva ou negativa;
• DTOS: Esta camada agrega e encapsula dados para transferência entre camadas do projeto. DTO é bastante utilizado também quando não queremos expor todos os dados da nossa camada de persistência mas precisamos exibir ao nosso cliente estes mesmos dados;
• Service: Camada responsável por guardar e abstrair as regras de negócio, para que a camada que guarda as entidades da aplicação seja "leve" e objetiva. Em particular, ela contém lógica de validação;
• Repository: Repositório encapsula o conjunto de objetos persistidos em um armazenamento de dados e as operações realizadas sobre eles;
• Mapper: Camada de acesso à dados que realiza transferências bidirecionais de dados entre um armazenamento de dados persistente (camada de modelos/entidades) e uma representação em memória dos dados (a camada de domínio, geralmente DTO's);
• Entities: Responsável por armazenar as entidades que representam as tabelas do banco de dados.

Módulos do Sistema

Abaixo, um diagrama representando os módulos do Backend, que interagem conforme o fluxo descrito na seção anterior.

Estratégia de Verificação e Validação

A estratégia de verificação e validação prevista para o projeto do backend irá contemplar o teste de forma unitária das três principais camadas da aplicação. São elas: repository, service e controller. Nas sessões a seguir será discorrido sobre alguns detalhes da codificação dos testes.

Model e DTO

Camadas que mantém, respectivamente, as entidades da aplicação e suas réplicas com informações uteis a serem expostas ao mundo externo. Não há necessidade de testar seus getters and setters, ao menos que haja lógica dentro deles ou métodos auxiliares.

Repository

Camada que mantém contato direto com a base de dados da aplicação e utiliza dos métodos proporcionados pelo framework JPA para efetuar suas operações. Por ser um framework muito difundido entre os desenvolvedores, não será necessário testar seus métodos nativos, porém, o JPA permite a criação de novas queries, que deverão, sim, ser unitariamente testadas.

Service

A camada de serviço contempla a aplicação das regras de negócio previstas no escopo do projeto. Nesta camada, deve ser testada todas as condições que um método pode conter, abrangendo exceções, retornos bem sucedidos ou qualquer comportamento retornado por ele. Sempre que possível, fazer o uso de mocks, pois, a camada de serviço integra todas as outras camadas, sem haver a necessidade de testa-las de novo.

Controller

Camada que expõem as rotas da aplicação. Devemos verificar estas rotas avaliando os possíveis códigos de status que um método pode retornar e cobrindo-os através de testes unitários.

Frontend

Definições de Tecnologias

• Angular
• TypeScript

Módulos do Sistema

TBD

Diagramas de Componentes

Diagrama do Sistema