DEV Community: Michel Versiani

Melhorando a rastreabilidade do sistema com um histórico de ações do usuário/sistema.

Michel Versiani — Mon, 06 Feb 2023 17:15:37 +0000

Introdução

Fala pessoal como andam as coisas?, espero que estejam todos bem, por aqui estou recuperando de um burnout mas a cada dia melhor.

Faz uns meses que eu queria criar esse artigo de hoje sobre um assunto que é muito importante no trabalho como pessoa desenvolvedora, e esse assunto é a criação de um histórico de ações do usuário e do sistema visando trazer mais rastreabilidade e segurança para nós e nossa aplicação.

Entendendo a importância de se ter uma boa rastreabilidade nas aplicações

Imagine o seguinte cenário, você trabalha em uma empresa que possui um SaaS focado na venda de produtos, na aplicação tem uma feature de desconto onde o usuário pode escolher um determinado produto de uma categoria e adicionar um desconto sobre ele, então em um belo dia na Black Friday o gerente de uma loja cliente pede para o funcionário responsável por administrar o sistema para adicionar um desconto de 5% sobre um determinado produto, mas , por falta de atenção infelizmente, o funcionário adiciona um desconto de 50%.

Algumas horas se passam e então ele percebe a falha que cometeu quando as vendas daquele produto começam a disparar de forma inacreditável, então quando ele vai checar os detalhes do produto no sistema acaba percebendo que adicionou a porcentagem de desconto errada, tenso não?

Sendo assim, o funcionário com medo da bronca que iria levar do chefe resolveu colocar a culpa no sistema, e adivinha ?, o gerente acreditou e ligou para o suporte da sua empresa.

Agora imagine só, como provaríamos que o erro foi do funcionário ao aplicar o desconto e não da aplicação que adicionou o desconto com valor errado?, precisaríamos de provas correto?, e é aí que entra a importância de se ter um bom sistema de histórico (por isso eu disse no inicio que é para nossa segurança também , porque tendo um sistema de histórico conseguimos comprovar quem foi o autor da falha).
Sei que para muitos esse assunto soa como sendo bem básico, e realmente é, mas acredite, muitos sistemas hoje em dia não contemplam essa feature.

Nesse artigo irei utilizar de exemplo a linguagem PHP juntamente com o Laravel, e mais especificamente, um projeto que estou desenvolvendo. Mas por se tratar de orientação a objetos conseguimos replicar em outras linguagens que suportem o paradigma.
Sem mais delongas bora botar a mão na massa!

Primeiramente, onde salvar o histórico?

Bom , nesse exemplo irei utilizar um banco de dados relacional, mas nada nos impede de salvar essas informações em um banco não relacional, ou até mesmo em um arquivo de log, o importante é de alguma forma conseguir salvar todas as ações necessárias para se ter uma boa rastreabilidade. Sendo assim fique a vontade para escolher onde irá salvar essas informações.

Quais ações mapear no histórico?

Vamos então começar partindo da seguinte pergunta, quais ações serão salvas em nosso histórico?

Pois bem, o mais importante de fato é salvar ações que são criticas no sistema e que também sejam passíveis de erros que possam acarretar em grandes problemas.

Seguindo esse nosso exemplo poderia ser a ação de adicionar um desconto, mas poderíamos ter outras ações, como por exemplo a ação de se realizar uma venda, alterar algum dado do produto, deletar um produto, e assim por diante.

Mas também nada impede de salvar todas as ações do usuário/sistema, eu particularmente prefiro salvar as ações criticas e que podem trazer alguma consequência (mas pense bem, pois a tabela de históricos ficaria lotada bem rapidinho, dificultando o “debug”).

É bom lembrar que quando eu digo usuário estou me referindo também ao sistema (talvez atores soaria melhor que usuários? lembrou daquela aula chatinha de UML da facul nééé?).

Montando nosso sistema de histórico

Bom , agora que enxergamos a importância de se ter um sistema de histórico, e quais ações devemos mapear, está na hora de botar a mão na massa e criar o nosso módulo de histórico.

Entidade/Modelo

Para a nossa entidade/modelo é importante termos o tipo da entidade (enum), que nesse caso seria o módulo em que foi registrado aquele histórico (product, sales, financial), uma coluna para salvar quem foi o responsável por aquela mudança (eu gosto de chamar de changed_by), e a ação que foi feita (enum). Também é indispensável ter colunas timestamp como created_at e updated_at para fins de rastreabilidade.

Estrutura do modelo

Seguindo a entidade da aplicação que irei utilizar como exemplo, temos as seguintes colunas:

Podemos utilizar as informações acima para criar uma migration para a tabela histories.

Ações que serão rastreadas

Dentro de nosso modelo teremos as seguintes ações que serão rastreadas:

Nessa aplicação que estou utilizando como exemplo até então as ações que criam histórico são relacionadas a produtos, pois são as mais críticas do sistema, por isso só tenho elas dentro do model de History. Mas no futuro irei adicionar ações relacionadas a autenticação, edição de permissões e pagamentos.

No PHP, antes da versão 8 onde foi introduzido o tipo enum nós costumávamos utilizar constantes como uma forma de representar um enum, mas na versão 8 > já é possível criar os enums como criamos em C#, por exemplo.
Então se você estiver utilizando o PHP 8 >, pode substituir as constantes por enums 🙂 , não substituí ainda por falta de tempo (ou vergonha na cara, ainda não me decidi rs…).

Segue o código da Model:

Acima podemos observar também os enums mapeando as entidades que utilizarão o histórico (Dê uma olhada nas constantes terminadas em ENTITY), para podermos saber qual módulo é dono de qual registro.

Relacionamentos e função para criação do histórico

Por fim, temos os relacionamentos de History com User e Company, também temos uma função para criação do histórico chamada createChange, onde recebemos como parâmetro o id da ação ocorrida, e um array com os dados para serem salvos na tabela.
Mais para frente utilizaremos essa função para criar os registros de histórico através da nossa classe de Serviços.

Código da entidade History:

<?php

namespace App\Models;

use App\Models\Scopes\FilterTenant;
use App\Traits\UsesLoggedEntityId;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Support\Collection;

/**
 * @property int $entity_id
 * @property string $entity_type
 * @property string $metadata
 * @property int $changed_by_id
 * @property int $company_id
 * @property int $action_id
 */
class History extends Model
{
        /* Para esse exemplo , ignore essas 2 traits.*/
    use HasFactory;
    use UsesLoggedEntityId;

    const PRODUCT_ENTITY = 'product';
    const BRAND_ENTITY = 'brand';
    const CATEGORY_ENTITY = 'category';

    const PRODUCT_CREATED = 1;
    const PRODUCT_UPDATED = 2;
    const PRODUCT_DELETED = 3;
    const PRODUCT_SOLD = 4;
    const ADDED_QUANTITY = 5;

    protected $fillable = [
        'entity_id',
        'entity_type',
        'company_id',
        'action_id',
        'metadata',
        'changed_by_id',
    ];

        /* Um scope global que eu utilizo para sempre filtrar as queries por tenantId, pode ignorar tb... */
    protected static function booted(): void
    {
        static::addGlobalScope(new FilterTenant());
    }

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function company(): BelongsTo
    {
        return $this->belongsTo(Company::class);
    }

    public function createChange(int $actionId, array $data): void
    {
        $this->entity_id = $data['entityId'];
        $this->entity_type = $data['entityType'];
        $this->metadata = $data['metadata'];
        $this->changed_by_id = $data['changedById'];
        $this->company_id = self::getLoggedCompanyId();
        $this->action_id = $actionId;
        $this->save();
    }
}

Agora que temos nosso Modelo criado está na hora de criarmos a classe de serviço para podermos utilizá-la nos módulos que salvarão no histórico.

Classe de serviço e sua utilização nos módulos

Para quem nunca ouviu falar de classes de serviços vou explicar bem brevemente, trata de uma classe que é utilizada para fazer a separação da regra de negócio na nossa aplicação, assim ao invés de termos as regras de negócio em um controller por exemplo, delegamos essa função para a classe de serviços, e o controlador fica com o papel de ser um orquestrador, lidando somente com requisições HTTP e delegando processamento relacionado a regras de negócios ao serviço. Caso tenha interesse fiz um artigo explicando um pouco sobre.

Criando o HistoryService

Muito bem, para começarmos podemos criar uma pasta chamada Services dentro de App, e logo após criamos uma pasta para a entidade History.

Dentro da pasta Services/History criamos uma classe PHP chamada HistoryService, e então criamos uma função chamada createHistory, recebendo como parâmetro o id da ação e um array de parâmetros.

Dentro da função createHistory faremos o seguinte:

Criaremos uma nova instância da model History.
Na instância criada chamaremos a função createChange passando como parâmetro o actionId e o array de parâmetros.
Chamaremos o método save do History para persistir no banco.

O código ficará assim:

<?php

namespace App\Services\History;

use App\Models\History;

class HistoryService
{
    public function createHistory(int $actionId, array $params): void
    {
        $history = new History();
        $history->createChange($actionId, $params);
        $history->save();
    }
}

Utilizando o HistoryService nos módulos da nossa aplicação

Enfim chegamos a parte final desse processo, utilizar a classe de serviço dentro dos módulos da nossa aplicação, criando assim os registros no nosso histórico. Nesse exemplo utilizarei a classe de serviço responsável por importar produtos de uma planilha para o nosso sistema.

Deixei somente as funções que mostrarão o uso do History , e o resto só comentei oque cada uma faz para vocês não ficarem voando:

/**
   * @throws FailedToImportProducts|AttachmentInvalid
 */
 public function importProducts(UploadedFile $importedFile): void
 {
        $this->setImportedProductsFile($importedFile);
        $this->validateFile();
        try {
            DB::beginTransaction();
            $this->createProductsBasedOnImport();
            DB::commit();
        } 
        catch(CustomException $e) {
            DB::rollBack();
            throw $e;
        }
        catch(\Throwable $e) {
            DB::rollBack();
            throw new FailedToImportProducts($e);
        }
  }

Nessa função fazemos o seguinte:

Seto o arquivo importado em uma propriedade, para ser utilizado em outras funções de processamento.
Valido se o tipo do arquivo enviado é uma planilha CSV ou XLSX, e também o tamanho do arquivo.
Chamamos a função createProductsBasedOnImport para começar o processo de criar os produtos da planilha importada.

private function createProductsBasedOnImport(): void
{
        $products = $this->convertSpreadsheetToCollection();
        $importedProducts = $products->map(function (array $product) {
            return ImportedProduct::create()->fromArray($product);
        });
        $this->storeImportedProducts($importedProducts);
}

Agora, na função de criar os produtos fazemos o seguinte:

Criamos uma Collection apartir da planilha, facilitando as operações que serão feitas mais pra frente.
Pegamos cada produto da Collection e criamos um objeto usando Factory, para facilitar mais uma vez as operações a seguir.
Chamamos a função storeImportedProducts, que é responsável por salvar no banco de dados os produtos importados passando como parâmetro uma coleção dos objetos que criamos com a Factory.

Então finalmente chegamos na cereja do bolo, onde faremos o seguinte:

    private function storeImportedProducts(Collection $products): void
  {
        $products->each(function (ImportedProduct $product) {
            $createdProduct = Product::create()->fromRequest($product->toCollection());
            $this->createImportedProductHistory($createdProduct);
        });
  }

Para cada produto da coleção, criamos um produto na nossa tabela Products.
Para cada produto salvo na tabela products, chamamos a função que criará o histórico de produto importado.

private function createImportedProductHistory(Product &$product): void
    {
        $historyService = new HistoryService();
        $params = [
            'entityId' => $product->getId(),
            'entityType' => History::PRODUCT_ENTITY,
            'changedById' => self::getChangedBy(),
            'metadata' => $this->createHistoryMetaData($product)
        ];

        $historyService->createHistory(History::PRODUCT_UPDATED, $params);
   }

Criamos uma instância do HistoryService para ser utilizado.
Criamos um Array com os parâmetros necessários no histórico, e no metadata chamamos uma função que retornara todos os dados que precisamos do produto para ser utilizado futuramente se necessário.
Chamamos a função createHistory, passando como parâmetro a ação e o array de parâmetros.

    private function createHistoryMetaData(Product &$product): string
  {
        return collect([
            'entityId' => $product->id,
            'productName' => $product->name,
            'initialQuantity' => $product->quantity,
            'categoryId' => $product->category_id ?? null,
            'brandId' => $product->brand_id ?? null,
            'minimumQuantity' => $product->minimum_quantity
        ])->toJson();
  }

E dessa forma acabamos de utilizar o nosso sistema de histórico 🙂.

Bom, espero que de alguma forma esse artigo tenha sido útil para você, se gostou compartilhe com aquele amigo que ainda não sabe da importância de se ter um histórico, e críticas construtivas são bem vindas!

Tem um jeito melhor de resolver tal problema?, comenta aí embaixo, vamos compartilhar conhecimento! 😀, é isso aí pessoal uma ótima semana a todos, e até a proxima 👋🏿.

Classe de serviços Centralizada VS Separada por Ações

Michel Versiani — Sat, 07 May 2022 22:06:34 +0000

Overview

Fala pessoal , espero que esteja tudo bem com vocês. Estou fazendo esse post para tentar mostrar um pouco sobre duas abordagens quando utilizando Serviços como uma forma de separar a lógica de negócios do controller , assim , deixando o controller somente com a responsabilidade de orquestrar todo fluxo , como deveria ser.

Porque eu decidi abordar tal assunto?

Você pode estar se perguntando , porque diabos você vai abordar esse assunto? , e bom , tudo surgiu quando eu aprendi sobre as classes de Serviço, e como elas nos ajudam a separar a responsabilidade de aplicar uma lógica de negócios fora do nosso Controller.

Da forma que aprendi , uma classe de serviço tinha centralizado todos os métodos e funções que condiziam com aquela entidade.

Ex : o método searchAvailableHotels estar na mesma classe de Serviço que o método getHotelRoomDetails , pois ambos fazem parte da regra de negócios da entidade Hotel , que utiliza um HotelService.

Porém , a medida em que a aplicação for crescendo , mais e mais métodos serão criados dentro desse serviço. E assim tornando difícil se localizar no workflow, no meio de tantas funções.

Sendo assim , lembrei que em algumas linguagens como TypeScript, os devs costumam criar várias classes de serviços, separando seus módulos por pastas , e sendo cada classe de serviço de um módulo específico performando sua principal ação.

Também me lembrei que no Framework Laravel existe algo semelhante ,uma abordagem chamada Actions, que se assemelha a uma classe Job , onde a classe tem um construtor para inicializar as dependências necessárias , e um método execute, que executa a ação imposta sobre aquela action.

Para saber mais sobre actions acesse esse post do Freek , demonstrando como se utiliza as tão famosas actions.

Sendo assim, decidi abordar esse assunto, por conta dessa “dor” que tive com as classes de Serviço. Então sem mais delongas irei falar um pouco sobre cada abordagem , e quando utiliza-las (na minha visão :p).

Centralizada

Uma classe de serviço centralizada geralmente é criada com uma separação por entidades. Então se tenho as entidades Hotel e Guest na minha aplicação , eu deveria ter uma classe HotelService , e GuestService para lidar com a aplicação das regras de negócios.

Prós

Todas as funções relacionadas as regras de negócio de uma determinada entidade ficam centralizadas em um local específico , tornando assim mais fácil de debugar o código , e de seguir um workflow.

Contras

Ao mesmo tempo , as funções estando centralizadas em uma só classe, dependendo da aplicação pode se tornar maçante , por conter inúmeras linhas de código, tornando assim fácil de se perder , e correndo um maior risco de ter efeitos colaterais ( um exemplo prático seria a mudança em uma variavel declarada no escopo da classe , e que é modificada por uma ou duas funções em um determinado workflow, podendo gerar erros).

Separadas por ações

Uma classe de Serviços separada por ações , geralmente é separada por módulos assim como na centralizada , porém , a grande diferença é que agora , para cada fluxo ou ação , criamos uma classe de serviço especifico.

Então agora , se antes tinhamos uma classe HotelService , contendo várias funções relacionadas a entidade Hotel , utilizando essa abordagem teremos uma classe de serviço para cada ação da entidade Hotel.
Um exemplo seriam os serviços SearchAvailableHotels e GetHotelRoomDetails.

Prós

Maior abstração/separação de responsabilidades.
Classes menores e com maior facilidade de se localizar.
Uncle Bob ficaria feliz por saber que estaríamos seguindo a letra S do Solid , o princípio da responsabilidade única.

Contras

Dependendo do sistema e da complexidade teríamos muitas classes , tornando não o código , mas a estruturação um pouco mais complexa , tendo em vista que teremos várias classes de serviço em um módulo. Mas mesmo assim , em sistemas complexos eu ainda prefiro essa abordagem.
Não vale a pena utilizar em sistemas menores que não possuem tantas funções relacionadas a regra de negócio da entidade.

Conclusão

Então quando devemos utilizar uma abordagem ou outra? , e a resposta é bem comum na nossa área... DEPENDE!.
Se na sua visão , a sua aplicação não irá precisar de implementar mais métodos e verificações no futuro , e que não há a chance de se tornar um projeto complexo , utilize a abordagem de Serviço centralizado. Senão , se você sabe que a aplicação irá crescer junto com o número de features requisitadas por seus clientes , se tornando algo complexo , recomendo utilizar a abordagem de serviços separados por ações/fluxos.

Espero que tenham gostado desse post , e principalmente espero que ele seja útil para alguém. Falei algo errado? , pensa de um modo diferente ou conhece uma abordagem melhor? , comenta aí :) , Um grande abrç a todos , e até a proxima!