### Configure Environment and Database (Bash)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/README.md

Instructions for setting up the Laravel environment by copying the example .env file, generating an application key, and managing the PostgreSQL database using Laravel Sail. Includes commands for starting the database, running migrations, and seeding data.

```bash
cp .env.example .env

./vendor/bin/sail up -d
./vendor/bin/sail artisan migrate --seed
```

--------------------------------

### Clone Repository and Install Dependencies (Bash)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/README.md

This snippet demonstrates how to clone the LabSIS SaaS KIT V4 repository using Git and install both PHP (Composer) and JavaScript (NPM) dependencies.

```bash
git clone git@github.com:iurygdeoliveira/labSIS-SaaS-KIT-V4.git
cd labSIS-SaaS-KIT-V4

composer install
npm install
```

--------------------------------

### Compile Frontend Assets (Bash)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/README.md

This command compiles the frontend assets (CSS and JavaScript) for the LabSIS SaaS KIT V4 project using Vite, a build tool that provides a fast development experience.

```bash
./vendor/bin/sail npm run build
```

--------------------------------

### Exibir Widget na Listagem de Recursos do Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/widgets-filament.md

Configura a página de listagem de recursos para exibir widgets no cabeçalho. Neste exemplo, o widget `UsersStats` é adicionado à página `ListUsers`.

```PHP
use App\Filament\Resources\Users\Widgets\UsersStats;
use Filament\Resources\Pages\ListRecords;

class ListUsers extends ListRecords
{
    protected function getHeaderWidgets(): array
    {
        return [
            UsersStats::class,
        ];
    }
}
```

--------------------------------

### Usar Cores em Componentes Filament (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/cores-filament.md

Demonstra como aplicar as cores registradas em componentes do Filament, como Actions e Forms, utilizando os nomes definidos (ex: 'primary', 'success').

```PHP
<?php

use Filament\Actions\Action;
use Filament\Forms\Components\Toggle;

// Exemplo em Action
Action::make('salvar')
    ->color('primary');

// Exemplo em Toggle
Toggle::make('is_active')
    ->onColor('success');
```

--------------------------------

### Configurar Brisk Theme no Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/customizando-layout.md

Demonstra como configurar o plugin Brisk Theme no painel Filament, incluindo a opção de desabilitar a fonte sugerida.

```PHP
// Para usar a fonte padrão do Brisk Theme
->plugin(BriskTheme::make())

// Para manter a configuração atual (sem fonte sugerida)
->plugin(BriskTheme::make()->withoutSuggestedFont())
```

--------------------------------

### Registrar Cores no AppServiceProvider (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/cores-filament.md

Centraliza o registro de cores no `AppServiceProvider` utilizando o método `configFilamentColors()`. Define cores padrão e customizadas em formato hexadecimal para uso no Filament.

```PHP
<?php

// app/Providers/AppServiceProvider.php
private function configFilamentColors(): void
{
    FilamentColor::register([
        'danger' => Color::hex('#D93223'),
        'warning' => Color::hex('#F28907'),
        'success' => Color::hex('#52a0fa'),
        'primary' => Color::hex('#014029'),
        'secondary' => Color::hex('#F2F2F0'),
    ]);
}
```

--------------------------------

### Estrutura de Classes: Typed Properties e Constructor Property Promotion

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Utilize typed properties em vez de docblocks para definir propriedades de classe. Use constructor property promotion quando todas as propriedades puderem ser promovidas para simplificar o construtor.

```PHP
<?php

class Usuario {
    // Constructor property promotion
    public function __construct(
        public string $nome,
        public int $idade
    ) {}
}

```

--------------------------------

### Recompilar Assets com Vite

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/customizando-layout.md

Instruções para recompilar os assets do frontend usando o Vite após fazer alterações em arquivos CSS customizados.

```Bash
npm run dev
# ou para produção
npm run build
```

--------------------------------

### Definir Paleta de Cores no Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/customizando-layout.md

Mostra como configurar a paleta de cores do painel Filament, definindo cores primárias e secundárias através do método `colors()` no AppServiceProvider.

```PHP
public function boot(): void
{
    // ... outras configurações
    $this->configFilamentColors();
}

// ... outras configurações

private function configFilamentColors(): void
{
    Filament::colors([
        'primary' => '#014029',
        'danger' => '#D93223',
    ]);
}
```

```PHP
// Alteração sugerida
Filament::colors([
    'primary' => '#2563eb', // Novo tom de azul
    'danger' => '#D93223',
    // ...
])
```

--------------------------------

### Ajustar Colunas Responsivas para Widgets no Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/widgets-filament.md

Define a quantidade de colunas que os widgets ocuparão em diferentes tamanhos de tela, permitindo um layout responsivo. O exemplo configura 2 colunas em telas pequenas, 3 em médias e 5 em telas grandes.

```PHP
protected function getColumns(): int|array
{
    return [
        'sm' => 2,
        'md' => 3,
        'xl' => 5,
    ];
}
```

--------------------------------

### RedirectToProperPanelMiddleware - PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/login-unificado.md

Este middleware redireciona usuários autenticados para o painel correto (admin ou user) com base em suas permissões. Se o usuário não puder acessar o painel atual, ele calcula e redireciona para o painel apropriado.

```PHP
$panel = Filament::getCurrentPanel();

if ($panel && $panel->getId() === 'auth') {
    if ($user->canAccessPanel(Filament::getPanel('admin'))) {
        return redirect()->to('/admin');
    }
    if ($user->canAccessPanel(Filament::getPanel('user'))) {
        return redirect()->to('/user');
    }
}

if (! $user->canAccessPanel($panel)) {
    if ($user->canAccessPanel(Filament::getPanel('admin'))) {
        return redirect()->to('/admin');
    }
    if ($user->canAccessPanel(Filament::getPanel('user'))) {
        return redirect()->to('/user');
    }
}
```

--------------------------------

### Notificações Pós-Operação CRUD em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Exemplos de como usar a `NotificationsTrait` para exibir mensagens de sucesso ou perigo após operações CRUD (Create, Read, Update, Delete) no Filament.

```php
// Após criar um registro
$this->notifySuccess('Registro criado com sucesso.');

// Após atualizar um registro
$this->notifySuccess('Registro atualizado com sucesso.');

// Após deletar um registro
$this->notifySuccess('Registro excluído com sucesso.');

// Após operação com erro
$this->notifyDanger('Não foi possível completar a operação.');
```

--------------------------------

### Uso de Type-Hinting em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Recomenda-se o uso de type-hinting para classes e tipos de dados em PHP para melhorar a legibilidade e a manutenção do código. Isso ajuda a garantir que as funções recebam os tipos de dados corretos.

```PHP
<?php

class Exemplo {
    public function processar(string $nome, int $idade): void {
        // Lógica do método
    }
}

```

--------------------------------

### Configuração do Disco S3 para MinIO Privado

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/gestao-de-midia.md

Configura o disco 's3' no arquivo `config/filesystems.php` para usar o MinIO com um bucket privado. Define credenciais, endpoint, modo path-style e visibilidade privada, garantindo a compatibilidade com a assinatura SigV4 e evitando a reescrita do host em URLs temporárias.

```php
's3' => [
    'driver' => 's3',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'bucket' => env('AWS_BUCKET', 'labsis'),
    'url' => env('AWS_URL'),
    'endpoint' => env('AWS_ENDPOINT', env('AWS_URL')),
    // Removido 'temporary_url' para não trocar host após assinar
    'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', true),
    'visibility' => 'private',
    'throw' => false,
    'report' => false,
    'options' => [
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
        'signature_version' => 'v4',
    ],
],

```

--------------------------------

### Notificações de Validação e Permissão em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Demonstra o uso da `NotificationsTrait` para fornecer feedback sobre validações de dados, permissões de usuário e operações bem-sucedidas com avisos.

```php
// Usuário sem permissão
$this->notifyDanger('Acesso negado.', 'Você não tem permissão para esta ação.');

// Dados inválidos
$this->notifyWarning('Dados inválidos.', 'Verifique as informações inseridas.');

// Operação bem-sucedida com aviso
$this->notifySuccess('Operação concluída.', 'Algumas configurações foram ajustadas automaticamente.');
```

--------------------------------

### Verificação de Configuração de Cores para Notificações em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Orientações para resolver problemas onde as notificações não exibem as cores corretas, focando na configuração do tema do Filament e possíveis sobrescritas de CSS.

```php
// Verifique se o tema do Filament está configurado corretamente
// As cores são baseadas no sistema de cores do Filament
// Verifique se não há CSS customizado sobrescrevendo as cores
```

--------------------------------

### Visualização de Suspensão de Usuário (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/suspensao-usuarios.md

Configura a visualização detalhada das informações de suspensão de um usuário em abas, utilizando o FilamentPHP. Inclui o status de suspensão, data e motivo, com formatação e ícones específicos.

```php
use Filament\Infolists\Components\TextEntry;
use Filament\Schemas\Components\Tabs;
use Filament\Support\Icons\Heroicon;

class UserInfolist
{
    public static function configure(Schema $schema): Schema
    {
        return $schema
            ->components([
                Tabs::make('User Details')
                    ->tabs([
                        // ... outras abas
                        
                        Tab::make('Suspensão')
                            ->icon(Heroicon::NoSymbol)
                            ->schema([
                                TextEntry::make('is_suspended')
                                    ->label('Status')
                                    ->formatStateUsing(fn (?bool $state): string => 
                                        $state ? __('Suspenso') : __('Autorizado')
                                    )
                                    ->badge()
                                    ->color(fn (?bool $state): string => 
                                        $state ? 'danger' : 'success'
                                    )
                                    ->icon(fn (?bool $state): string => 
                                        $state ? 'heroicon-c-no-symbol' : 'heroicon-c-check'
                                    ),
                                TextEntry::make('suspended_at')
                                    ->label('Suspenso em')
                                    ->dateTime('d-m-Y H:i')
                                    ->placeholder('-'),
                                TextEntry::make('suspension_reason')
                                    ->label('Motivo da suspensão')
                                    ->placeholder('-'),
                            ]),
                    ])->persistTabInQueryString(),
            ]);
    }
}
```

--------------------------------

### Exemplo de Notificação de Sucesso com NotificationsTrait

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Mostra como usar o método `notifySuccess` da `NotificationsTrait` para exibir notificações de sucesso, com opções para título, corpo e duração.

```php
// Notificação básica de sucesso
$this->notifySuccess('Usuário atualizado com sucesso.');

// Com corpo de texto
$this->notifySuccess(
    'Usuário atualizado com sucesso.',
    'As alterações foram salvas no banco de dados.'
);

// Com duração personalizada (15 segundos)
$this->notifySuccess(
    'Usuário atualizado com sucesso.',
    'As alterações foram salvas no banco de dados.',
    15
);
```

--------------------------------

### Widget de Estatísticas de Usuários com #[Computed] no Livewire

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/livewire-computed.md

Implementa um widget de estatísticas de visão geral para a listagem de usuários no Filament. Utiliza o atributo #[Computed] no método `summary()` para calcular métricas de usuários (total, suspensos, verificados) apenas uma vez por renderização, otimizando consultas ao banco de dados.

```PHP
use App\Models\User;
use Filament\Widgets\StatsOverviewWidget as BaseWidget;
use Filament\Widgets\StatsOverviewWidget\Stat;
use Livewire\Attributes\Computed;

class UsersStats extends BaseWidget
{
    #[Computed]
    protected function summary(): array
    {
        $totalUsers = User::query()->count();
        $suspendedUsers = User::query()->where('is_suspended', true)->count();
        $verifiedUsers = User::query()->whereNotNull('email_verified_at')->count();

        return [
            'total' => $totalUsers,
            'suspended' => $suspendedUsers,
            'verified' => $verifiedUsers,
        ];
    }

    protected function getStats(): array
    {
        $summary = $this->summary; // memoizado no mesmo render

        return [
            Stat::make('Usuários', (string) $summary['total'])
                ->icon('heroicon-c-user-group'),
            Stat::make('Suspensos', (string) $summary['suspended'])
                ->color('danger')
                ->icon('heroicon-c-no-symbol'),
            Stat::make('Verificados', (string) $summary['verified'])
                ->color('success')
                ->icon('heroicon-c-check-badge'),
        ];
    }
}
```

--------------------------------

### Exemplo de Notificação de Aviso com NotificationsTrait

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Demonstra como utilizar o método `notifyWarning` da `NotificationsTrait` para exibir notificações de aviso, com customização de título, corpo e duração.

```php
// Aviso simples
$this->notifyWarning('Atenção aos dados inseridos.');

// Com corpo e duração personalizada
$this->notifyWarning(
    'Atenção aos dados inseridos.',
    'Alguns campos podem estar incompletos.',
    12
);
```

--------------------------------

### Registro de Widget no Filament com Livewire

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/livewire-computed.md

Registra o widget `UsersStats` para ser exibido no cabeçalho da página de listagem de usuários no Filament. Este código define quais widgets serão renderizados na interface.

```PHP
use App\Filament\Resources\Users\Widgets\UsersStats;
use Filament\Resources\Pages\ListRecords;

class ListUsers extends ListRecords
{
    protected function getHeaderWidgets(): array
    {
        return [
            UsersStats::class,
        ];
    }
}
```

--------------------------------

### Geração de Recursos Filament com Flag --view

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Ao gerar recursos com Filament v4 ou v3, utilize a flag `--view` para evitar perguntas interativas no terminal e gerar automaticamente as views.

```Shell
php artisan make:filament-resource Post --view
```

--------------------------------

### Convenções de Configuração Laravel

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Arquivos de configuração devem usar kebab-case. Chaves de configuração devem ser snake_case. Configurações de serviço devem ser adicionadas em `config/services.php`.

```PHP
// config/services.php

return [
    'google_maps' => [
        'api_key' => env('GOOGLE_MAPS_API_KEY'),
    ],
];

// Em outro arquivo de config, ex: config/pdf_generator.php
return [
    'chrome_path' => env('CHROME_PATH'),
];

```

--------------------------------

### Carregar CSS Customizado no Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/customizando-layout.md

Demonstra como vincular um arquivo CSS customizado (`theme.css`) ao painel Filament através do método `viteTheme()` no AdminPanelProvider.

```PHP
->viteTheme('resources/css/filament/admin/theme.css')
```

--------------------------------

### Configurar Autenticação Multi-Fator no Painel (Filament PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/autenticacao-2fa.md

Habilita e configura a autenticação de dois fatores (2FA) com códigos de recuperação no painel administrativo do Filament.

```php
// app/Providers/Filament/AdminPanelProvider.php

use Filament\Auth\MultiFactor\App\AppAuthentication;

public function panel(Panel $panel): Panel
{
    return $panel
        // ... outras configurações
        ->multiFactorAuthentication(
            AppAuthentication::make()
                ->recoverable() // Habilita códigos de recuperação
        )
        // ... outras configurações
}
```

--------------------------------

### Exemplo de Uso da NotificationsTrait no afterSave

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Apresenta um exemplo prático de como a `NotificationsTrait` é usada dentro do método `afterSave` em uma classe Filament para notificar o usuário sobre ações realizadas, como a prevenção de auto-suspensão.

```php
protected function afterSave(): void
{
    // ... lógica de sincronização ...

    // Previne auto-suspensão
    if ($this->record->getKey() === Auth::id() && $this->record->is_suspended) {
        $this->record->forceFill([
            'is_suspended' => false,
            'suspended_at' => null,
        ])->save();

        // Notificação de perigo com corpo explicativo
        $this->notifyDanger(
            'Você não pode suspender a si mesmo.',
            'Alteração revertida automaticamente.'
        );

        $this->redirect($this->getResource()::getUrl('index'));
        return;
    }

    // Notificação de sucesso
    $this->notifySuccess('Usuário atualizado com sucesso.');
    $this->redirect($this->getResource()::getUrl('index'));
}
```

--------------------------------

### Post-Login Redirect Logic - PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/login-unificado.md

Define a lógica de redirecionamento após a autenticação bem-sucedida. O usuário é redirecionado para o painel '/admin' ou '/user' com base em sua função (role). Se nenhuma função conhecida for encontrada, o usuário é redirecionado para a rota 'home'.

```PHP
// Arquivo: app/Http/Responses/LoginResponse.php
// O código específico para o redirecionamento pós-login não foi fornecido no trecho, mas a descrição indica a funcionalidade.
```

--------------------------------

### User Model for Filament Avatar and 2FA

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/edicao-perfil.md

Integrates Filament user contracts and Spatie Media Library for avatar handling, including saving to S3/MinIO and defining necessary fillable properties.

```php
use FilamentModels\Contracts\FilamentUser;
use Filament\Models\Contracts\HasAvatar;
use Filament\Auth\MultiFactor\App\Contracts\HasAppAuthentication;
use Filament\Auth\MultiFactor\App\Contracts\HasAppAuthenticationRecovery;

class User extends Authenticatable implements FilamentUser, HasAppAuthentication, HasAppAuthenticationRecovery, HasAvatar, HasMedia
{
    use InteractsWithMedia;

    public function registerMediaCollections(): void
    {
        $this->addMediaCollection('avatar')
            ->useDisk('s3')
            ->singleFile();
    }

    public function registerMediaConversions(?\Spatie\MediaLibrary\MediaCollections\Models\Media $media = null): void
    {
        // Intentionally empty: avatar is saved as 256x256
    }

    public function getFilamentAvatarUrl(): ?string
    {
        $media = $this->getFirstMedia('avatar');
        if ($media) {
            return $media->getUrl();
        }

        return null;
    }
}
```

```php
protected $fillable = [
    'uuid',
    'name',
    'email',
    'password',
    'avatar_url', // Field for avatar
    'email_verified_at',
    'is_suspended',
    'suspended_at',
    'suspension_reason',
    'remember_token',
    'app_authentication_secret', // Field for 2FA
    'app_authentication_recovery_codes', // Field for recovery codes
];
```

--------------------------------

### Formatação de Comentários em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Exemplos de formatação correta para comentários de linha única e de bloco em PHP.

```PHP
// Linha única com espaço após //

/*
 * Bloco multi-linha começa com *
 * e cada linha subsequente também.
 */
$variable = "value"; // Comentário no final da linha
```

--------------------------------

### Configuração UserPanelProvider em Laravel

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/login-unificado.md

Configura o painel para usuários comuns, herdando as configurações base e descobrindo recursos, páginas e widgets específicos do namespace 'App\Filament\User\Resources'.

```PHP
$panel = parent::panel($panel)
    ->discoverResources(in: app_path('Filament/User/Resources'), for: 'App\Filament\User\Resources')
    ->discoverPages(in: app_path('Filament/User/Pages'), for: 'App\Filament\User\Pages')
    ->pages([
        Dashboard::class,
    ])
    ->discoverWidgets(in: app_path('Filament/User/Widgets'), for: 'App\Filament\User\Widgets')
    ->widgets([
        AccountWidget::class,
        FilamentInfoWidget::class,
    ]);
```

--------------------------------

### Executar Comandos de Commit

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Sequência de comandos para formatar código, adicionar alterações ao staging area, criar um commit com uma mensagem e enviar para o repositório remoto.

```bash
./vendor/bin/pint --parallel
git add .
git commit -m "mensagem do commit"
git push
```

--------------------------------

### Verificação de Ícones e CSS para Notificações em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Passos para solucionar problemas de ícones quebrados ou não carregados em notificações, incluindo a verificação da instalação do Heroicon e possíveis conflitos de CSS.

```php
// Verifique se o Heroicon está instalado e configurado
// Os ícones usados são padrão do Heroicon, certifique-se de que estão disponíveis
// Verifique se não há conflitos de CSS
```

--------------------------------

### Filament Media Infolist Action

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/gestao-de-midia.md

Defines an action for the Filament infolist to open media files. It resolves the appropriate label, icon, and media URL based on the record, only displaying the action for supported media types.

```php
MediaAction::make('open')
    ->label(fn ($record) => self::resolveMediaActionConfig($record)['label'])
    ->icon(fn ($record) => self::resolveMediaActionConfig($record)['icon'])
    ->media(fn ($record) => self::resolveMediaActionConfig($record)['media'] ?? '#')
    ->visible(fn ($record): bool => self::resolveMediaActionConfig($record)['media'] !== null)
```

--------------------------------

### Exemplo de Notificação de Perigo com NotificationsTrait

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Ilustra o uso do método `notifyDanger` da `NotificationsTrait` para exibir notificações de erro ou perigo, incluindo opções para persistência.

```php
// Notificação de erro
$this->notifyDanger('Operação não permitida.');

// Com corpo explicativo
$this->notifyDanger(
    'Operação não permitida.',
    'Você não pode suspender a si mesmo. Alteração revertida.'
);

// Persistente (não desaparece automaticamente)
$this->notifyDanger(
    'Erro crítico detectado.',
    'Verifique as configurações do sistema.',
    0,
    true
);
```

--------------------------------

### Criar Widget de Estatísticas de Usuários no Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/widgets-filament.md

Define um widget de estatísticas para exibir métricas de usuários, como total, suspensos e verificados. Utiliza o `StatsOverviewWidget` e o atributo `#[Computed]` do Livewire para otimizar a recuperação de dados.

```PHP
use App\Models\User;
use Filament\Widgets\StatsOverviewWidget as BaseWidget;
use Filament\Widgets\StatsOverviewWidget\Stat;
use Livewire\Attributes\Computed;

class UsersStats extends BaseWidget
{
    #[Computed]
    protected function summary(): array
    {
        $totalUsers = User::query()->count();
        $suspendedUsers = User::query()->where('is_suspended', true)->count();
        $verifiedUsers = User::query()->whereNotNull('email_verified_at')->count();

        return [
            'total' => $totalUsers,
            'suspended' => $suspendedUsers,
            'verified' => $verifiedUsers,
        ];
    }

    protected function getStats(): array
    {
        $summary = $this->summary; // memoizado no mesmo render

        return [
            Stat::make('Usuários', (string) $summary['total'])
                ->icon('heroicon-c-user-group'),
            Stat::make('Suspensos', (string) $summary['suspended'])
                ->color('danger')
                ->icon('heroicon-c-no-symbol'),
            Stat::make('Verificados', (string) $summary['verified'])
                ->color('success')
                ->icon('heroicon-c-check-badge'),
        ];
    }
}
```

--------------------------------

### Uso de Atributos em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Em vez de anotações de PHPDoc, prefira o uso de atributos em PHP para maior legibilidade e para seguir as abordagens recomendadas nas versões mais recentes da linguagem.

```PHP
<?php

use Attribute;

#[Attribute]
class MeuAtributo {
    // Definição do atributo
}

#[MeuAtributo]
class ClasseComAtributo {
    // Classe que utiliza o atributo
}

```

--------------------------------

### Verificação de Chamada de Método para Notificações em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Instruções para garantir que o método `send()` da `NotificationsTrait` está sendo chamado corretamente, mesmo que a trait o faça automaticamente, e sugestões para depuração de JavaScript e carregamento do Filament.

```php
// Certifique-se de que o método send() está sendo chamado
// A trait já faz isso automaticamente, mas verifique se não há erros de JavaScript
// Verifique se o Filament está carregando corretamente
```

--------------------------------

### Configuração AdminPanelProvider em Laravel

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/login-unificado.md

Configura o painel de administrador, herdando as configurações base e descobrindo recursos, páginas e widgets específicos do namespace 'App\Filament\Resources'.

```PHP
$panel = parent::panel($panel)
    ->default()
    ->bootUsing(fn () => FilamentComponentsConfigurator::configure())
    ->discoverResources(in: app_path('Filament/Resources'), for: 'App\Filament\Resources')
    ->discoverPages(in: app_path('Filament/Pages'), for: 'App\Filament\Pages')
    ->pages([
        Dashboard::class,
    ])
    ->discoverWidgets(in: app_path('Filament/Widgets'), for: 'App\Filament\Widgets')
    ->widgets([
        AccountWidget::class,
        FilamentInfoWidget::class,
        DependencyWidget::class,
    ]);
```

--------------------------------

### Configure Filament Edit Profile Plugin

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/edicao-perfil.md

Sets up the Filament Edit Profile plugin with custom navigation labels, icons, and options for avatar, email, and 2FA forms.

```php
->plugin(
    FilamentEditProfilePlugin::make()
        ->setNavigationLabel('Editar Perfil')
        ->setNavigationGroup('Configurações')
        ->setIcon('heroicon-s-adjustments-horizontal')
        ->shouldShowAvatarForm(
            value: true,
                directory: 'avatar',
            rules: 'mimes:png,jpg,jpeg|max:1024'
        )
        ->shouldShowEmailForm()
        ->shouldShowDeleteAccountForm(false)
        ->shouldShowMultiFactorAuthentication()
)
```

--------------------------------

### Convenções de Comandos Artisan Laravel

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Comandos Artisan devem ter nomes em kebab-case. É importante fornecer feedback ao usuário e mostrar o progresso para loops longos. O output deve ser exibido antes do processamento.

```PHP
<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class DeleteOldRecords extends Command {
    protected $signature = 'delete:old-records';
    protected $description = 'Deleta registros antigos.';

    public function handle() {
        $this->comment('Iniciando a exclusão de registros antigos...');
        // Lógica para excluir registros
        $this->info('Registros antigos excluídos com sucesso!');
    }
}

```

--------------------------------

### Implementar NotificationsTrait em Classes Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Demonstra como usar a trait `NotificationsTrait` em classes do Filament, como `EditRecord`, para habilitar funcionalidades de notificação.

```php
<?php

namespace App\Filament\Resources\Users\Pages;

use App\Trait\Filament\NotificationsTrait;
use Filament\Resources\Pages\EditRecord;

class EditUser extends EditRecord
{
    use NotificationsTrait;

    // ... resto da classe
}
```

--------------------------------

### Panel Access Authorization (canAccessPanel) - PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/login-unificado.md

Implementa a lógica de autorização de acesso aos painéis no modelo User. Permite acesso ao painel 'auth', bloqueia usuários suspensos, exige verificação de e-mail para painéis de aplicação e autoriza acesso aos painéis 'admin' e 'user' com base nas roles.

```PHP
if ($panel->getId() === 'auth') {
    return true;
}

if ($this->isSuspended()) {
    return false;
}

if (! $this->hasVerifiedEmail()) {
    return false;
}
```

--------------------------------

### Controle de Acesso para Usuários Suspensos (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/suspensao-usuarios.md

Define a lógica para impedir que usuários suspensos acessem o painel da aplicação. O método `canAccessPanel` retorna `false` se o usuário estiver suspenso.

```php
public function canAccessPanel(Panel $panel): bool
{
    if ($this->isSuspended()) {
        return false;
    }
    return true;
}
```

--------------------------------

### User Seeder and Factory States (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/roles-e-permissions.md

Defines how users and their roles are seeded into the database and provides factory states for creating users with specific roles. Ensures default admin and user accounts are available.

```php
database/seeders/UserSeeder.php: cria as roles (`Admin`, `User`) e assegura um usuário administrador e um usuário padrão, ambos com senha `mudar123`.
```

```php
database/factories/UserFactory.php: fornece states (`admin()` e `user()`) para criar usuários já com suas respectivas roles.
```

--------------------------------

### Configuração BasePanelProvider em Laravel

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/login-unificado.md

Centraliza configurações comuns para múltiplos painéis Filament, incluindo aparência, tema, autenticação multi-fator e middlewares essenciais. Define o ID, caminho, tema, e plugins compartilhados.

```PHP
return $panel
    ->id($this->getPanelId())
    ->path($this->getPanelPath())
    ->spa()
    ->databaseTransactions()
    ->darkMode(false)
    ->defaultThemeMode(ThemeMode::Light)
    ->multiFactorAuthentication(AppAuthentication::make()->recoverable())
    ->colors([
        'primary' => '#014029',
        // ... demais cores
    ])
    ->viteTheme('resources/css/filament/admin/theme.css')
    ->sidebarWidth('15rem')
    ->maxContentWidth(Width::Full)
    ->middleware([
        // middlewares comuns + de acesso/redirect
    ])
    ->authMiddleware([
        Authenticate::class,
    ]);
```

--------------------------------

### API Routing com Nomes de Recursos e kebab-case

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

As rotas de API devem usar nomes de recursos no plural e seguir a convenção kebab-case para os endpoints.

```PHP
use Illuminate\Support\Facades\Route;

Route::prefix('api/error-occurrences')->group(function () {
    Route::get('/', [App\Http\Controllers\ErrorOccurrenceController::class, 'index']);
    Route::post('/', [App\Http\Controllers\ErrorOccurrenceController::class, 'store']);
});
```

--------------------------------

### Registro de Service Provider no Laravel 11+

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

No Laravel 11+, novos Service Providers devem ser registrados no arquivo `bootstrap/providers.php`, em vez do tradicional `config/app.php`.

```PHP
// bootstrap/providers.php
return [
    // ... outros providers
    App\Providers\MyCustomServiceProvider::class,
];
```

--------------------------------

### Configuração AuthPanelProvider em Laravel

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/login-unificado.md

Define o painel de autenticação ('auth') para login, registro, recuperação de senha e verificação de e-mail. Utiliza uma página de login customizada para lidar com contas suspensas.

```PHP
return $panel
    ->id('auth')
    ->path('')
    ->viteTheme('resources/css/filament/admin/theme.css')
    ->authGuard('web')
    ->login(AppFilamentPagesAuthLogin::class)
    ->registration()
    ->passwordReset()
    ->emailVerification()
    ->emailChangeVerification();
```

--------------------------------

### Formato Conventional Commits

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Estrutura padrão para mensagens de commit, incluindo tipo, escopo opcional, descrição curta e um corpo detalhado com as alterações realizadas.

```git
<tipo>(<escopo>): <descrição>

<corpo do commit com as alterações realizadas>
```

--------------------------------

### Estrutura de Classes: Nullable Syntax

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Use a sintaxe nullable curta (`?Type`) em vez de `Type|null` para definir propriedades ou parâmetros que podem ser nulos.

```PHP
<?php

class Produto {
    public function __construct(
        public ?string $descricao = null
    ) {}
}

```

--------------------------------

### Modelo User com Lógica de Suspensão (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/suspensao-usuarios.md

Modifica o modelo 'User' para incluir os campos de suspensão, define os casts para os tipos de dados corretos e implementa métodos para verificar o status de suspensão e controlar o acesso ao painel do Filament.

```php
class User extends Authenticatable implements FilamentUser, HasAvatar
{
    protected $fillable = [
        'uuid',
        'name',
        'email',
        'password',
        'avatar_url',
        'email_verified_at',
        'is_suspended',           // Campo de suspensão
        'suspended_at',           // Data da suspensão
        'suspension_reason',      // Motivo da suspensão
        'remember_token',
    ];

    protected function casts(): array
    {
        return [
            'password' => 'hashed',
            'is_suspended' => 'boolean',           // Cast para boolean
            'suspended_at' => 'datetime:d/m/Y H:i', // Cast para datetime
            // ... outros casts
        ];
    }

    // Método para verificar se o usuário está suspenso
    public function isSuspended(): bool
    {
        return $this->is_suspended;
    }

    // Controle de acesso ao painel
    public function canAccessPanel(Panel $panel): bool
    {
        if (! $this->hasVerifiedEmail()) {
            return false;
        }

        if ($this->isSuspended()) {
            return false;
        }

        return true;
    }
}
```

--------------------------------

### Configure S3 Filesystem Disk (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/edicao-perfil.md

Defines the S3 filesystem disk configuration, primarily for MinIO integration. It specifies the driver, access credentials, region, bucket, URL, and endpoint settings. The visibility is set to 'private' by default.

```php
's3' => [
    'driver' => 's3',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'bucket' => env('AWS_BUCKET', 'labsis'),
    'url' => env('AWS_URL'),
    'endpoint' => env('AWS_ENDPOINT', env('AWS_URL')),
    'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', true),
    'visibility' => 'private',
    'throw' => false,
    'report' => false,
    'options' => [
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
        'signature_version' => 'v4',
    ],
],
```

--------------------------------

### Uso de Notificações Persistentes em PHP

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/notifications-trait.md

Conselhos sobre o uso do parâmetro `persistent` em notificações, explicando que elas devem ser fechadas manualmente pelo usuário e sugerindo durações longas como alternativa.

```php
// Use o parâmetro persistent com cuidado
// Notificações persistentes devem ser fechadas manualmente pelo usuário
// Para notificações importantes mas não críticas, use duração longa em vez de persistente
```

--------------------------------

### Registro de Alias de Middleware no Laravel 11+

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Para registrar um alias de middleware no Laravel 11+, utilize o arquivo `bootstrap/app.php`. O `app/Http/Kernel.php` não é mais o local para essa configuração.

```PHP
// bootstrap/app.php
use App\Http\Middleware\MyCustomMiddleware;

$app->routeMiddleware([
    'custom' => MyCustomMiddleware::class,
]);
```

--------------------------------

### Configure Signed URL Generator for Media Library

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/gestao-de-midia.md

Sets the URL generator for the Spatie Media Library to use a custom class for generating signed URLs. This ensures that all media URLs returned are temporary and signed, enhancing security.

```php
'url_generator' => App\Support\MediaLibrary\SignedUrlGenerator::class,
```

--------------------------------

### Exemplo de Migração sem Método Down()

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Em Laravel, migrations devem conter apenas o método `up()` e não o método `down()`, conforme a nova abordagem.

```PHP
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up()
    {
        Schema::create('products', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->text('description')->nullable();
            $table->timestamps();
        });
    }

    // O método down() não é mais necessário ou recomendado.
```

--------------------------------

### Ajustar Largura da Barra Lateral no Filament

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/customizando-layout.md

Explica como modificar a largura da barra de navegação lateral do painel Filament usando o método `sidebarWidth()` no AdminPanelProvider.

```PHP
->sidebarWidth('15rem') // Largura atual
```

```PHP
// Alteração sugerida
->sidebarWidth('18rem') // Nova largura
```

--------------------------------

### PHP: Implementa `canDelete` computado em `EditUser`

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/livewire-computed.md

Define um método computado `canDelete` em `EditUser` para verificar se o usuário logado é diferente do registro atual. Esta checagem é usada para controlar a exibição da ação de deletar.

```php
use Illuminate\Support\Facades\Auth;
use Livewire\Attributes\Computed;

class EditUser extends EditRecord
{
    #[Computed]
    public function canDelete(): bool
    {
        return $this->record?->getKey() !== Auth::id();
    }

    protected function getHeaderActions(): array
    {
        $actions = [
            $this->getBackButtonAction(),
            ViewAction::make(),
        ];

        if ($this->canDelete) {
            $actions[] = DeleteAction::make()
                ->successNotification(Notification::make())
                ->after(fn () => $this->notifySuccess('Usuário excluído com sucesso.'));
        }

        return $actions;
    }
}
```

--------------------------------

### Filament Edit Profile Configuration Options

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/edicao-perfil.md

Defines customizable options for the Filament Edit Profile plugin, including supported locales, default disk for uploads, and visibility settings.

```php
<?php

return [
    'locales' => [
        'pt_BR' => '🇧🇷 Português',
        'en' => '🇺🇸 Inglês',
        'es' => '🇪🇸 Espanhol',
    ],
    'locale_column' => 'locale',
    'theme_color_column' => 'theme_color',
    'avatar_column' => 'avatar_url',
    'disk' => 's3', // MinIO (S3)
    'visibility' => 'private', // Signed URLs when needed
];
```

--------------------------------

### Estrutura de Controle Blade com Indentação

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/GEMINI.md

Templates Blade devem ser indentados com 4 espaços e não devem conter espaços extras após as estruturas de controle.

```Blade
@if($user->isAdmin())
    <p>Bem-vindo, Administrador!</p>
@else
    <p>Bem-vindo, Usuário!</p>
@endif
```

--------------------------------

### Exibição do Status de Suspensão na Tabela do Filament (PHP)

Source: https://github.com/iurygdeoliveira/labsis-saas-kit-v4/blob/main/docs/suspensao-usuarios.md

Configura a tabela de usuários no Filament para exibir o status de suspensão ('Suspenso' ou 'Autorizado') usando badges coloridos e ícones correspondentes, com base no campo 'is_suspended' do modelo User.

```php
use FilamentTablesColumnsTextColumn;

class UsersTable
{
    public static function configure(Table $table): Table
    {
        return $table
            ->columns([
                ImageColumn::make('avatar_url')
                    ->label('Avatar')
                    ->circular()
                    ->defaultImageUrl(fn (User $record): string => $record->getFilamentAvatarUrl())
                    ->extraImgAttributes(['alt' => 'Avatar do usuário']),
                TextColumn::make('name'),
                TextColumn::make('email')
                    ->label('Email address'),
                TextColumn::make('is_suspended')
                    ->label('Status')
                    ->formatStateUsing(fn (User $record): string => 
                        $record->is_suspended ? __('Suspenso') : __('Autorizado')
                    )
                    ->badge()
                    ->color(fn (User $record): string => 
                        $record->is_suspended ? 'danger' : 'success'
                    )
                    ->icon(fn (User $record): string => 
                        $record->is_suspended ? 'heroicon-c-no-symbol' : 'heroicon-c-check'
                    )
                    ->alignCenter(),
            ]);
    }
}
```