Features

A fim de facilitar o entendimento da aplicação, foi criado um diagrama mostrando o principal fluxo da API que será discutido posteriormente: 

Cadastro de Peças

Uma das elementos fundamentais do sistema são os serviços. Todo serviço obrigatoriamente é formado por um conjunto de peças ou itens mecânicos necessários para a realização daquele serviço: 

No processo de cadastro de peças, são incluídos diversos campos essenciais, tais como o nome da peça, fornecedor, fabricante, código de barras e observações pertinentes. Além destes, há o campo de quantidade, indicando a disponibilidade da peça em estoque, e o campo de valor, representando o custo que será adicionado ao orçamento final do cliente. 

Cadastro de Cliente

No que diz respeito ao fluxo comercial,a primeira etapa é verificar se o cliente que requisita algum serviço está registrado no sistema. Se não estiver, é necessário criar um novo cliente utilizando o método POST de 'Customers': 

A feature também conta com algumas validações adicionais, como o formato do CPF, por exemplo.

Cadastro de Veículo

Antes de iniciar uma vistoria, é necessário cadastrar o veículo do cliente que agendou o serviço, caso o veículo ainda não esteja registrado no sistema.

Ordem de Serviço

Se o cliente estiver de acordo com os valores do orçamento e os serviços a serem prestados, é iniciada uma Ordem de Serviço para dar início aos procedimentos de reparo do veículo.

A ordem de serviço gerada já estará pré-preenchida com os serviços definidos na vistoria. Caso seja necessário qualquer serviço adicional além do orçado com o cliente (e que não tenha sido identificado durante a vistoria), é obrigatório gerar um aditivo (com a permissão do cliente).

Resposta JSON

Aditivo de Serviço

Uma regra adicional da mecânica estipula que para qualquer serviço adicional não previsto na vistoria, é necessário criar um aditivo de serviço. Atualmente, essa funcionalidade ainda está em desenvolvimento. 

Arquitetura

A arquitetura deste projeto consiste em uma API Rest desenvolvida com o framework Nest.JS, utilizando o banco de dados MySQL e Docker para facilitar a implantação e o gerenciamento de contêineres. 

Banco de Dados

O banco de dados escolhido para a aplicação foi o MySQL, por ser um dos bancos mais antigos do mercado e pela sua ampla utilização na indústria de software. 

Abordagem Code First

Para desenvolver a API, foi adotada a abordagem "Code First", que se concentra na escrita do código-fonte para definir os modelos de dados e a lógica de negócios. A principal vantagem dessa abordagem é a agilidade no desenvolvimento, pois as alterações nos modelos e na lógica podem ser refletidas diretamente no banco de dados por meio das "migrations", que são scripts SQL gerados a partir das alterações no modelo via código.

Além disso, qualquer pessoa que tenha acesso ao projeto pode reproduzir exatamente a mesma estrutura do banco de dados e ter acesso a todas as modificações, pois as migrations também servem como um histórico das alterações no banco.

Modelo do Banco de Dados

Atualmente esse é o modelo do banco de dados mais recente da aplicação:

Nele podemos ver relações do tipo 'One-to-Many' e 'Many-to-many'. 

Visualização da API

Para visualizar a API, foi escolhida a utilização do Swagger, uma ferramenta que oferece uma interface intuitiva sem a necessidade de instalar ferramentas adicionais para testar e executar a aplicação. Além disso, o Swagger simplifica o processo de documentação, gerando automaticamente a documentação a partir do código-fonte da aplicação.

ORM

Para fazer a comunicação da aplicação com o banco de dados, o framework escolhido foi o Prisma. O critério de escolha se deu pelo fato do prisma ser um ORM moderno, por ter uma comunidade muito grande no Github e pela forma como ele escala rapidamente a aplicação, sem a necessidade de ajustes adicionais, utilizando o conceito de migrations.

Além disso, o Prisma oferece uma ferramenta de UI chamada Prisma Database, que permite visualizar os dados no banco de dados sem a necessidade de instalar uma ferramenta adicional.

Arquitetura de Código

A arquitetura de código escolhida foi a arquitetura 'Clean Architecture', que é um tipo de arquitetura bastante moderna, que foi idealizada pelo Uncle Bob. O objetivo dessa arquitetura é promover a separação de preocupações e a manutenção da independência entre as diferentes camadas da aplicação, divindido-as entre: Domínio, Aplicação, Infraestrutura e Apresentação. 

No projeto a Clean Architecture foi adaptada dessa forma:

Onde podemos visualizar as camadas de domínio, aplicação, infraestrutura e apresentação.

Domain

Na cama de domínio, no centro da arquitetura, estão as entidades. As entidades representam os conceitos centrais da aplicação, é a unidade básica do sistema. 

Além das entidades, também temos o mapeamento dessas entidades, que consiste na transformação da entidade em uma resposta para o cliente.

Infrastructure

Como o próprio nome já diz, na infraestrutura alocamos tudo aquilo que é essencial para a estrutura do sistema, como as configurações do banco, os módulos da aplicação, os repositórios e tudo aquilo que é compartilhado para toda a API. 

Application

Para a camada de aplicação estão as regras de negócio e tudo aquilo que é responsável para a lógica do sistema. Na cama de aplicação estão presentes os casos de uso, os handlers, os DTOs e as regras de negócio chamadas de rules. 

Presentation

E para a cama de apresentação, está presente tudo aquilo que faz a ligação dos dados entre servidor e cliente, que no caso da API, são os Controllers, responsáveis por forneceer os endpoints da aplicação. 

Mapeamento de Entidades

Para que os dados sensíveis da aplicação não fiquem visíveis para o cliente, utilizou-se uma técnica simples de mapeamento de entidades em associação com os DTOs, que são classes usadas para transportar dados entre processos, entre a camada de apresentação e a camada de serviço da API, encapsulando os dados e protegendo as informações confidenciais no momento da transferência dessas informações. 

src\core\domain\mapping\vehicle\response-vehicle.mapper.ts. Visualize aqui.

Máscaras de Validação

Além do mapeamento de entidades, para os DTOs do tipo 'Request', que são aqueles responsáveis por fazer a mediação das solicitações de escrita, utilizou-se uma bilbioteca nativa do Nest.JS chamada 'class-validator', responsável por facilitar a validação de dados sem a necessidade de funções adicionais. 

src\core\application\dtos\vehicle\request-vehicle.dto.ts. Visualize aqui.

Além do uso nativo dessas validações em relação as propriedades, também foi utilizado o uso de Regex para validação, por exemplo, de placas de veículos no formato Mercosul e formato de CPF: 

src\core\infrastructure\shared\constants.ts. Visualize aqui.

Os detalhes dos caracteres usados na expressão regular estão dentro de uma arquivo chamado 'constants' onde reúne todas as constantes que podem ser reaproveitadas na aplicação, evitando assim duplicidade de código. 

Repository Pattern

Um dos Design Patterns utilizado na aplicação foi o Repository Pattern, que consiste em separar as camadas de acesso dos dados e a lógica de negócios, proporcionando uma abstração na fonte dos dados, fazendo que a camada da lógica de negócios seja independente das outras camadas.

Para o projeto em questão, foi utilizado uma classe abstrata, usando os conceitos de Generics. Onde essa classe consiste em abstrair métodos genéricos que serão utilizados por todas as entidades da API. Esses métodos consistem nas aplicações básicas como Create, Read, Update e Delete.

src\core\infrastructure\repositories\igeneric-repository.ts. Visualize aqui.

O objetivo de se utilizar o Repository Pattern vai além do simples fato de reduzir a duplicidade de código, ele oculta os detalhes de como os dados são persistidos e recuperados, sem que a lógica de negócios conheça os detalhes da implementação, tornando assim o código mais flexível.

Para a invocação do repositório, cada entidade herda as configurações da classe abstrata genérica, que também é o lugar de criar algum método específico daquela entidade em questão:

src\core\infrastructure\repositories\vehicle\vehicle.repository.ts. Visualize aqui.

E para a implementação, que é onde de fato ocorre a lógica de acesso ao banco de dados, foi criada uma outra classe com os detalhes dessa aplicação: 

src\core\infrastructure\repositories\vehicle\vehicle.prisma.repository.ts. Visualize aqui.

CQRS (Command Query Responsibility Segregation)

Um outro padrão de arquitetura utilizado foi o CQRS, que consiste em separar as interações com o banco de dados em operações de leitura e escrita, os chamados 'commands' e 'queries'. 

Por padrão, o Nest.JS coloca toda as invocações do banco em uma única classe, na qual recebe o nome de 'services'. Essa mesma classe além de reunir todas as operações ao banco em um único local, faz isso também de forma direta, sem nenhum meio de transporte que possa desaclopar esse acesso.

No entanto, o padão CQRS é mais recomendado em APIs robustas e de grande porte, como podemos ver na própria documentação do Nest:

"Embora esse padrão geralmente seja suficiente para aplicações de pequeno e médio porte (modelo tradicional), pode não ser a melhor escolha para aplicações maiores e mais complexas. Nesses casos, o modelo CQRS (Command and Query Responsibility Segregation) pode ser mais apropriado e escalável (dependendo dos requisitos da aplicação)." — Nest.JS Documentation

Por mais que o projeto em questão seja uma API de pequeno porte, a escolha em utilizar esse padrão foi simplesmente para experimentar e simular como funcionaria a arquitetura do Nest.JS em relação a grandes solicitações e acessos por parte da API.

Na aplicação, os commands e queries foram alocados na camada de aplicação, no diretório de casos de uso, que são as lógicas de negócios da API. Para operações de escrita os métodos foram organizados em commands e os métodos de leitura em queries:

Todos os métodos, seja de escrita ou de leitura, devem fazer parte de uma única classe, para evitar um acoplamento desnecessário. Logo abaixo há um exemplo de um método de escrita, nesse caso um create, responsável por criar um novo cliente no banco: 

src\core\application\use-cases\custumer\commands\create-customer.command.ts. Visualize aqui.

E logo abaixo um exemplo de uma query, que é um consulta que retorna um cliente a partir de um ID especificado: 

src\core\application\use-cases\custumer\queries\get-one-customer.query.ts. Visualize aqui.

Tanto os commands, quanto as queries possuem um decorator padrão (@CommandHandler e @QueryHandler) que são responsáveis por marcar aquela classe como um comando de escrita e leitura, que depois será importado em algum módulo.

Com a utilização do CQRS o Controller fica muito mais limpo e legível, sem a necessidade de quaquer linha adicional de código, uma vez que a lógica da aplicação não se encontra mais no Controller, que fica apenas responsável por ser uma meio necessário para se chegar até os comandos da aplicação. Com isso também ocultamos da camada de apresentação quais são os repositórios ou métodos responsáveis pelo acesso ao banco de dados, tornando nosso construtor limpo de qualquer refeência de repositório, tendo apenas as depedências padrão do CQRS, o CommandBus e QueryBus que chamam os métodos específicos:

src\core\presentation\controllers\customers.controller.ts. Visualize aqui.

Centralização das Mensagens de Retorno

Todas as mensagens de retorno da API, sejam de erros, validações ou mensagens de sucesso, se concentram em um único lugar, a fim de evitar essas escritas dentro dos casos de uso, ocasionando assim uma escrita 'hard-code'. Dessa forma conseguimos reaproveitar as mensagens e caso necessite de modificação, podemos simplismente modificar a mensagem em um único local para refletir a mudança para toda a aplicação. Além disso, a organização centralizada simplifica a manutenção do código, pois as alterações necessárias podem ser feitas de maneira global. 

src\core\infrastructure\shared\messages.ts. Visualize aqui.

Método Paginado e Corpo de Resposta

O tipo do corpo de resposta padrão utilizado na API é o JSON, encapsulado através de uma propriedade 'data', que contém toda a resposta da solicitação, assim como duas propriedades adicionais. A primeira dela é 'failed', que pode ser true ou false dependendo da resposta e 'error' que mostra o erro caso aconteça alguma falha. Isso proporciona uma estrutura consistente para os dados retornados, facilitando o processamento por parte dos consumidores da API: 

Já para o método de GET da forma paginado, além das propriedades padrão, o mesmo conta também com algumas propriedades únicas encapsuladas dentro do objeto 'pagination': 

Entre elas:

• total: quantidade total de registros;

• lastPage: última página;

• currentPage: página atual;

• perPage: quantidade de registros por página;

• prev: página anterior;

• next: próxima página.

Segurança

CORS (Cross-origin Resource Sharing)

Foi utilizado o conceito de CORS para aumentar a segurança da aplicação utilizando dependências nativas do Nest.JS. Essa abordagem ajuda a proteger a aplicação contra solicitações maliciosas vindas de domínios não autorizados, garantindo assim a integridade e segurança dos dados manipulados pela aplicação.

Como projeto de teste, na API todos os domínios estão sendo autorizados.

Limitação de Taxa

Uma boa estratégia aliada na segurança junto com o CORS é a utilização da limitação da taxa de acesso, para controlar o tráfego da rede e evitar sobrecargas no servidor, garantindo uma boa experiência aos consumidores da API.

Para limitar o tráfego da rede em uma possível massa de fluxo foi utilizado a biblioteca 'throttler', que é uma biblioteca padrão do Nest.JS.

src\app.module.ts. Visualize aqui 

No projeto em questão foi utilizado a configuração padrão que permite uma quantidade máxima de 10 solicitações em 60000 milissegundos.

JWT Token

Para autenticação e autorização da API, foi utilizado uma padrão bastante utilizado no mercado que é o JWT (Jason Web Tokens), que define uma maneira compacta e segura de transmitir informações entre partes como um objeto JSON.

No contexto deste projeto, o JWT token desempenha um papel fundamental na segurança e autenticação dos usuários. Quando um usuário realiza o login com suas credenciais, um token JWT é gerado e assinado com uma chave secreta única. Esse token é então enviado de volta ao cliente e deve ser incluído em todas as solicitações subsequentes como uma forma de autenticação.

Hash Senha

Para ocultar a senha no banco de dados, foi utilizado uma biblioteca node chamada 'bcrypt', que não é nativa do Nest.JS, mas é bastante utilizada pela comunidade. Ela é responsável por esconder informações sensíveis do usuário, como as senhas, por exemplo.

Como Executar a Aplicação

Inicie um Container Docker

Com o Docker instalado, execute o seguinte comando para fazer o download da imagem da aplicação:

docker pull antonioscript/automative-repair-api:16

Em seguida, basta executar a aplicação: 

docker run -p 3000:3000 antonioscript/automative-repair-api:16

Execute a API Localmente

Para executar a aplicação, primeiramente é preciso instalar as dependências do Nest.JS:

npm install @nestjs/common

Após isso, executar o comando de migração para criar as tabelas do modelo no banco de dados:

npx prisma migrate dev --name nameMigration

E por fim, executar o arquivo seed para popular o banco de dados:

npx prisma db seed

Depois disso, basta inserir o comando para iniciar a aplicação:

npm run start:dev

E acessar através do link: http://localhost:3000/api 

Observação: Caso não tenha o MySQL instalado, é possível alterar o tipo do banco de dados no arquivo .env e no Schema do Prisma. Ajuste o nome mysql para PostgreSQL, MariaDB, ou qualquer outro servidor passando as informações do host e as credenciais: 

DATABASE_URL="mysql://root:admin@localhost:3306/automative_repair_db"

.env

E no campo de URL, no aquivo schema.prisma altere o provedor:

datasource db {

  provider = "mysql"

  url      = env("DATABASE_URL")

}

prisma\schema.prisma