Registro de Atividades

O sistema utiliza o pacote spatie/laravel-activitylog para registrar atividades importantes realizadas pelos usuários. Esses registros permitem auditar, rastrear e monitorar ações executadas dentro do sistema, oferecendo transparência e histórico detalhado de alterações.

⚙️ Como funciona

Cada model que precisa registrar atividades deve utilizar a trait App\Traits\HasActivityLog. Essa trait encapsula a configuração padrão do pacote spatie/laravel-activitylog, além de permitir personalizações por meio da classe App\Support\ActivityDetails.

🧩 Estrutura

App\Traits\HasActivityLog

A trait HasActivityLog adiciona o comportamento de log às models.

Métodos principais

Método	Descrição
activityDetails()	Deve ser sobrescrito na model para retornar um objeto configurado de ActivityDetails.

Exemplo de uso na Model

use App\Traits\HasActivityLog;
use App\Support\ActivityDetails;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasActivityLog;

    public function activityDetails(): ActivityDetails
    {
        return ActivityDetails::make()
            ->label('Produto')
            ->recordTitle('name')
            ->logOnly(['name', 'price'])
            ->customLabels([
                'name' => 'Nome do Produto',
                'price' => 'Preço de Venda',
            ]);
    }
}

🧱 Classe App\Support\ActivityDetails

A classe ActivityDetails define como as atividades devem ser registradas e exibidas no sistema.

Principais propriedades

Propriedade	Tipo	Descrição
label	string	Nome descritivo do tipo de entidade (ex: “Cliente”, “Produto”). Aparece na coluna “Tipo” do recurso de atividades.
recordTitle	string	Nome do campo usado para identificar o registro (ex: name, document). Aparece na coluna “Entidade”.
logOnly	Collection	Lista de campos monitorados para log de alterações.
customLabels	array	Labels amigáveis para exibir os nomes dos campos nos logs.
model	Model	Instância da model associada.

Métodos mais usados

Método	Retorno	Descrição
make(?Model $model = null)	ActivityDetails	Cria uma nova instância.
label(string $label)	ActivityDetails	Define o nome legível da entidade.
recordTitle(string $recordTitle)	ActivityDetails	Define o atributo usado como título do registro.
logOnly(array/Collection $fields)	ActivityDetails	Define explicitamente quais campos serão registrados.
customLabels(array $labels)	ActivityDetails	Define rótulos personalizados para campos.

🪶 Logando eventos personalizados

Além das alterações automáticas de models, é possível registrar eventos manuais no log.

Exemplo

use App\Enums\ActivityEvent;
use App\Models\User;

$user = User::find(1);

activity()
    ->causedBy($user)
    ->performedOn($user)
    ->setEvent(ActivityEvent::LOGIN->value) // Utilize sempre o enum ActivityEvent
    ->log('Usuário fez login no sistema');

Neste exemplo:

• causedBy($user) → define quem executou a ação;
• performedOn($user) → define sobre qual entidade a ação ocorreu;
• setEvent() → define o tipo de evento (sempre vindo do enum ActivityEvent);
• log() → registra a descrição legível da ação.

Action Filament

Utilize a Action ActivityLink em Edit/View Pages ou como recordAction para redirecionar para a visualização dos logs dessa entidade.

🧠 Boas práticas

• Sempre utilize o enum ActivityEvent para manter consistência nos tipos de eventos.
• Defina claramente os campos relevantes na função activityDetails().
• Prefira labels amigáveis com customLabels() para tornar o log mais legível.
• Use o log manual (activity()->...) para registrar ações que não envolvem alterações diretas de models (ex: login, exportação, aprovação, etc.).