**Documentação e Fluxo do Front-End:**

Após clonar o projeto, podemos observar que o front-end é composto pela pasta 'client', e dentro dela temos várias outras pastas que constituem ele. Vejamos cada uma delas separadamente e o que elas armazenam:


Começando pela pasta do ***'storybook'***, que é o nosso 'repositório' para armazenamento e documentação dos nossos componentes, é formada por três arquivos de configuração e importação dos componentes dentro do storybook.


A segunda pasta é a ***'dist'***, criada logo após a compilação do projeto, nela temos algumas outras pastas que podem guardar informações de coisas terceiras que podem compor o projeto, como css, fonts e imagens.


A terceira pasta é a ***'nodemodules'***, também gerada depois de rodarmos o primeiro comando no front-end que é o 'npm install' nela conterá todos os pacotes usados no projeto do front-end.


A quarta pasta é a ***'public'***, nela contém algumas imagens de ícones utilizados no sistema e também o arquivo de *index.html* que serve para testar e habilitar o javascript do projeto do front-end. Ela é a origem da aplicação, é o primeiro arquivo enviado pelo servidor.


A quinta pasta é a ***'src'***, a principal pasta do projeto, dentro dela contém várias outras pastas que veremos a seguir:


Vamos ver sobre a primeira que é *'assets/images'* nela contém algumas imagens e logomarcas utilizadas no sistema, tem também alguns arquivos do tipo SVG que significa *Scalable Vector Graphics*, são “imagens” que não perdem qualidade indiferentemente do tamanho que é exibido na tela pois é um vetor.


A segunda pasta é a ***'components'***, nela estão todos os nossos componentes criados através do BootstrapVue para atender a demanda de nossas telas, alguns foram separados por pastas, como *Button* que possui vários tipos de componentes de botões e o *Form* que possui várias caixas de texto ou mais precisamente de entrada de dados. Os outros fora das pastas são mais específicos em questão de usabilidade. Padronizamos os nomes destes componentes todos em inglês, portanto quando for preciso criar algum novo já sabemos o padrão utilizado para renomeá-los.


A terceira pasta é a ***'config'***, nela temos dois arquivos, o primeiro é o *'api.ts'*, responsável por fazer a configuração do token e do login do sistema e o arquivo *'permissions.ts'*, responsável por configurar as permissões de ação do CRUD em cada uma das funcionalidades do sistema.


A quarta pasta é a de ***'constants'***, esta pasta foi criada para armazenar todos os nossos arquivos de Enums que serão usados. Mais especificamente, são arquivos de dados que já vem carregados nos campos de entrada como opções. Temos eles tanto no projeto do back-end como no de front-end. E como usamos o typescript no projeto do front, a extensão destes arquivos serão sempre *.ts*. Padronizamos os nomes destes arquivos todos em inglês, portanto quando for preciso criar algum outro já sabemos o padrão dos nomes.


A quinta pasta é a de ***'helpers'*** que possui arquivos de ajuda como formatação de datas, de máscaras para campos que exigem, de notificação, navegação e validação.


A sexta pasta é a de ***'layouts'***, ela possui um arquivo *.vue* capaz de agrupar toda a tela que é renderizada quando o front-end é executado.


A sétima pasta chama-se ***'models'***, nela contém todas as classes modelos de entidades e interfaces do sistema, assim como temos essa pasta no back-end, temos no front-end também. Observe que nela temos algumas pastas e outros arquivos soltos, cada uma das pastas corresponde a uma funcionalidade, portanto os nomes delas podem ser em Português mesmo, já os arquivos que irão compor, dependendo da especificidade, terão o nome em inglês. E os outros arquivos soltos, também são classes e interfaces isoladas, que são utilizadas pelas entidades.


A oitava pasta é a de ***'router'***, nela temos três arquivos, o primeiro é o *'index.ts'* que possui configurações de autenticação, o segundo é o *'routes.ts'*, formado pelos *imports* de cada tela criada no sistema, lá na pasta de *'views'* que veremos mais adiante, por se tratar de um arquivo de rotas, todas essas telas tem que ser declaradas nele. E por terceiro, o arquivo *'sidebar.ts'* que contém uma classe e uma interface que montam o menu lateral do sistema.


A nona pasta chama-se ***'rules'***, ela possui um único arquivo que é sobre validações de códigos, cpf e cnpj, usado no sistema.


A décima pasta é uma das mais importantes, é a de ***'service'***, responsável por fazer a comunicação do front-end com o back-end. Nela contém um arquivo de serviço para cada entidade ou funcionalidade do sistema, com a url do endpoint a ser acessado no back-end ele consegue fazer esta comunicação. E também possui os métodos ou operações de CRUD responsáveis por 'casar' com os mesmos lá no backend. E os nomes de cada arquivo criado é no padrão inglês, acompanhado da palavra 'Service'.


A décima primeira pasta é a da ***'store'***, nela temos a primeira pasta chamada *'actions'* onde estão todos os arquivos das funcionalidades que guardam as operações de CRUD exportadas, para serem
utilizadas. A segunda pasta é a de *'modules'*, que também possui um arquivo para cada funcionalidade, onde este arquivo é o responsável por fazer a comunicação entre a *'view'*(telas) que veremos daqui a pouco e a classe de serviço que acabamos de ver acima, correspondendo a cada uma das funcionalidades, contendo as actions dos métodos de CRUD. Observamos que os nomes dentro de cada pasta seguem o padrão do inglês.


A próxima pasta é a ***'stories'***, responsável por toda a construção dos componentes no storybook, dentro dela temos uma nova pasta correspondente a cada componente e dentro dessas pastas temos dois arquivos, um *.stories.ts*, onde renderizamos o componente e declaramos as suas propriedades, e o outro arquivo que é o de *notes* que é do tipo markdown, onde documentamos os componentes, com as suas propriedades, tipos, valores default e descrição. Os desenvolvedores escrevem várias histórias por componente que descrevem todos os estados "interessantes" que um componente pode suportar.


A outra pasta é a de ***'style'***, ou estilo, responsável por guardar todos os arquivos *.css* e *.scss* utilizados no sistema.


A penúltima pasta é a de ***'utils'***, que guarda três arquivos de grande utilidade, o primeiro é o *mask.ts* que possui as máscaras de cpf e cnpj utilizadas no sistema, o segundo é o *permission.ts*, responsável por fazer a verificação de permissão ao usuário logado. E o terceiro que é o *token.ts*, que faz toda a manipulação do token quando o usuário faz login e logout no sistema.


E agora a última pasta dentro de *'src'* é a ***'views'***, esta é outra pasta de grande importância dentro do sistema, dentro dela existem várias outras pastas, cada uma responsável por uma funcionalidade ou entidade do sistema. Geralmente dentro de cada uma possuímos um arquivo de listagem da respectiva funcionalidade e um arquivo de formulário, que são as duas telas fundamentais que cada uma das funcionalidades possuem. Além destes dois arquivos, podemos encontrar também uma pasta chamada *'components'* nela estarão os componentes que foram criados para compor as respectivas views. Aí você pode se perguntar: *'Mas vimos uma pasta anteriormente que é composta somente de componentes, por quê temos outra?'* A resposta é simples, na pasta que vimos anteriormente estão os componentes genéricos, que são utilizados em vários lugares do sistema, e os que estão dentro das pastas em *views*, são os **específicos**, criados e utilizados somente dentro daquela respectiva view. Observe na figura abaixo, que tanto os nomes das pastas quanto o dos arquivos que compõem ela, são criados no inglês, este é o padrão que usamos.


Ainda dentro da pasta 'src' temos os seguintes arquivos:


O *App.vue* guarda o componente de rotas que é utilizado por todo o sistema. O próximo, *main.ts* é o responsável por fazer a importação e declaração de todos os componentes que são criados, já deixando claro aqui que todos usam um padrão no nome que já sabemos que é a lingua inglesa, e também o prefixo 'soi' acompanhado de '-' antes do nome, podemos ver um exemplo na imagem a seguir:


Então é através desse nome que criamos para o componente é que ele poderá ser chamado nas views usando o formato de <>(tags).

Depois os próximos arquivos que temos são de alguns pacotes utilizados no sistema.

___________________________________________________

Agora voltando à raíz do projeto do front-end, temos a última pasta a ser vista que é a de ***'tests'***, nela temos outras duas pastas que são dois tipos de testes que o front-end pode executar, o *'e2e'* que é uma metodologia utilizada para testar se o fluxo de um aplicativo está sendo executado conforme o projeto do início ao fim. E o *unit*, mais conhecido como de unidade, consiste em validar dados válidos e inválidos via I/O (entrada/saída) sendo aplicado por desenvolvedores ou analistas de teste.


No mais vemos alguns outros arquivos aleatórios que compõem o desenvolvimento e execução do projeto.


Vamos dar ênfase do arquivo *.env*, responsável por endereçar a API e fazer a cominicação entre os dois projetos, às vezes dependendo de como você irá rodar o projeto, se é no modo local ou no modo de homologação será preciso alterar o endereço da Api.


**Agora vamos por a mão na massa?**

**Como criar uma funcionalidade do zero no front-end para conversar com a API que já está pronta?**

Primeira coisa que precisamos fazer é criar as *Views*, então se for uma funcionalidade nova, você poderá criar uma pasta com o nome desta funcionalidade e depois dentro dela os dois respectivos arquivos de listagem e formulário, o de listagem terá o nome referente a *'nomeDaEntidad.vue'*, e o de formulário
*'nomeDaEntidadeForm.vue'*, observe que este tem a palavra 'form' no final já para destacar que será a view de formulário.

Depois das views criadas, vamos declarar elas dentro do arquivo *routes.ts* que está no seguinte caminho: *MetraCloud/client/src/router/routes.ts*, fazendo o *import* da entidade e depois dentro da constante routes, fazemos a declaração. Observe o exemplo da entidade de Usuários:


Observe que nesse momento temos que saber quais são as reais permissões de acesso desta funcionalidade, se vai ter permissão somente de leitura, de criação ou de edição, ou se terá todas. E também os usuários que poderão logar no sistema e ter acesso a esta funcionalidade, podemos ver isso em 'roles'.

O próximo passo agora é definir a classe e a interface de modelo que é basicamente igual a que temos no backend, lá na pasta *models*, seguindo o caminho *MetraCloud/client/src/models/nomeDaPasta/nomeDaFuncionalidade.ts*, conforme mostra a figura:


Se você passar e observar cada uma das classes, vai ver que todas seguem um padrão de ter a declaração da interface primeiro com os atributos e seus tipos, depois a declaração das classes também com os seus atributos atribuídos como públicos e os tipos de cada um. Então, não tem segredo, só ir seguindo mesmo o padrão dos outros arquivos.

Agora vamos começar a construir a parte de comunicação com o back-end primeiramente com a classe de serviço. Seguindo no caminho *MetraCloud/client/src/service/nomeDaPasta/nomeDaEntidadeService.ts* pode-se criar o arquivo da classe de serviço, seguindo o padrão das outras, nela irá conter os métodos das operações de CRUD equivalente aos que estão no back-end. Segue uma prévia na imagem abaixo:


O passo seguinte é ir até a pasta da *store* seguindo o caminho *MetraCloud/client/src/store*, dentro da pasta *actions* iremos criar a action da funcionalidade que estamos desenvolvendo, nela conterá a declaração de todos os métodos e operações que construímos na classe de serviço anteriormente, veja o exemplo:


Logo após vamos criar dentro da outra pasta que é a *modules*, o módulo que irá fazer a ligação da view com a classe de serviço, podem olhar nos outros arquivos também iguais a este, pois seguirá o mesmo padrão. Nele conterá alguns *imports* dos métodos que acabamos de declarar na action, e logo abaixo dentro da classe, os métodos das actions, mutations e get's.


E pelo fim desse fluxo, iremos agora para a implementação das views, primeiro implementamos a tela de listagem de usuários cadastrados que recebe o nome de *'nomeDaEntidade.vue'*, e depois a de formulário que recebe o nome de *'nomeDaEntidadeForm.vue'*. Ambas são arquivos do tipo *vue* e por isso tem na sua construção, primeiramente a parte de *html* que é o que vai ser renderizado na página, depois a parte de *script* que conterá todos os eventos desta página que será feito em typescript, e por último a parte de *style* que conterá as propriedades do css necessárias para a aplicabilidade dos estilos na página.


Lembramos que toda a parte de html podemos usar os nossos componentes genéricos para facilitar e agilizar o nosso desenvolvimento.

**E agora como é formado um componente?**

**E como faço para utiliza-lo?**

Vamos lá, um componente é inteiramente formado pelos mesmos elementos que compõem uma view, template, script e style. Vejamos um exemplo do componente de botão que é bem simples:


Na imagem acima temos a parte do html que é a tag template envolvendo um botão que usamos lá do BootstrapVue, dentro da tag do botão temos uma classe que possivelmente é aplicada algum css, e as propriedades que ele vai possuir, como *type* que é o tipo do botão, *variant* que é a propriedade de cor, *disabled* que vai dizer se o botão está desabilitado ou não, e *click*, usualmente acompanhado do @ antes da palavra, este vai ser o responsável por chamar o evento do click que o botão irá emitir. Logo depois temos a tag de span que tratá dentro dela mais uma propriedade que é o *icon* responsável pelo ícone do botão. Agora veremos a parte de script:


Então temos a classe Button, e dentro dela a declaração das nossas propriedades utilizadas no botão, com os seus respectivos tipos e valores default.

Agora veremos a parte de aplicabilidade de estilos css em style:


Temos duas classes, a *'btn'* que é do botão e *'content'* que é da tag span, ambas aplicam estilos para essas tags através das propriedades do css.

Observe que então definimos um componente de botão genérico sem atribuição de valores para nenhuma de suas propriedades.

Agora chegou a hora de atribuirmos valores as suas propriedades e juntamente com isso fazer a chamada do componente dentro da view:


Então conforme vimos o jeito como chamamos um componente é escrevendo conforme declaramos na criação dele, dentro de tags, nesse caso <soi-button />. E as propriedades dentro da tag agora recebem valores, então *label* está recebendo o nome de *Cancelar*, *icon* que é a propriedade de ícone, recebendo o valor de *times* que é o ícone de 'x', a propriedade *variant* recebendo o valor de *danger* que corresponde a cor vermelha dentro do BootstrapVue e a última propriedade usada é a de *@click*, recebendo o evento *showModal* definido como false para eventualmente quando clicado, esse botão fechará alguma modal.

E assim, finalizamos os conceitos de pastas, o fluxo de criação da parte do front-end e a construção e utilização dos componentes.

Sugestões de melhorias serão sempre bem vindas, e caso haja alguma dúvida, esta poderá ser sanada com algum integrante da equipe Cloud.

Bom trabalho!