Funcionalidades Principais

Conheça todos os recursos e funcionalidades incluídos no Filament Core Starter Kit.

Visão Geral

O Starter Kit vem com três módulos principais pré-configurados:

• 👥 People Management - Gestão de pessoas físicas e jurídicas
• 📄 Invoices - Sistema completo de faturamento
• 💬 Communications - Envio de mensagens multicanal

Módulo: People Management

Gestão de Pessoas

Gerenciamento unificado de pessoas físicas e jurídicas.

Campos Principais:

• Informações Básicas: Nome, tipo (individual/company), status
• Documentos: CPF, CNPJ, Passport, RG
• Contatos: Email, telefone, celular, website
• Endereços: Múltiplos endereços com geolocalização
• Papéis: Cliente, Fornecedor, Aluno, Instrutor (extensível)

Exemplo de Uso:

use App\Models\Person;

// Criar pessoa física
$person = Person::create([
    'name' => 'João Silva',
    'type' => 'individual',
    'status' => 'active',
]);

// Adicionar documento
$person->document()->create([
    'type' => 'cpf',
    'number' => '123.456.789-00',
    'verified' => true,
]);

// Adicionar contato
$person->contact()->create([
    'primary_email' => 'joao@example.com',
    'phone' => '+55 11 99999-9999',
]);

Validação de Documentos

Validação automática de CPF, CNPJ e outros documentos.

use App\Services\DocumentValidatorService;

$validator = new DocumentValidatorService();

// Validar CPF
if ($validator->validateCPF('123.456.789-00')) {
    // CPF válido
}

// Validar CNPJ
if ($validator->validateCNPJ('12.345.678/0001-90')) {
    // CNPJ válido
}

Eventos Disparados

// Quando pessoa é criada
event(new PersonCreated($person));

// Quando pessoa é atualizada
event(new PersonUpdated($person));

// Quando pessoa é deletada
event(new PersonDeleted($person));

Resource no Filament

Formulário:

• Tab "Dados Principais": Nome, tipo, status
• Tab "Documentos": CPF/CNPJ, RG, Passaporte
• Tab "Contatos": Emails, telefones
• Tab "Endereços": Múltiplos endereços
• Tab "Papéis": Cliente, Fornecedor, etc.

Tabela:

• Filtros: Por tipo, status, papel
• Busca: Nome, documento, email
• Ações em massa: Ativar, desativar, exportar
• Exportação: Excel, CSV, PDF

Módulo: Invoices

Sistema de Faturamento

Criação e gerenciamento completo de faturas.

Componentes:

• Cabeçalho: Número, data, cliente, status
• Itens: Produtos/serviços com quantidade e preço
• Impostos: Cálculo automático de ICMS, PIS, COFINS
• Totais: Subtotal, impostos, descontos, total
• Pagamento: Status, método, data de vencimento

Exemplo de Criação:

use App\Models\Invoice;
use App\Models\InvoiceItem;

// Criar fatura
$invoice = Invoice::create([
    'person_id' => $person->id,
    'number' => 'INV-2024-001',
    'issue_date' => now(),
    'due_date' => now()->addDays(30),
    'status' => 'pending',
]);

// Adicionar itens
$invoice->items()->create([
    'description' => 'Consultoria em Laravel',
    'quantity' => 10,
    'unit_price' => 150.00,
    'total' => 1500.00,
]);

// Calcular totais
$invoice->calculateTotals();

Cálculo de Impostos

Cálculo automático baseado em regras configuráveis.

use App\Services\TaxCalculatorService;

$calculator = new TaxCalculatorService();

$taxes = $calculator->calculate($invoice);

/*
Array resultado:
[
    'icms' => [
        'rate' => 18.00,
        'value' => 270.00
    ],
    'pis' => [
        'rate' => 1.65,
        'value' => 24.75
    ],
    'cofins' => [
        'rate' => 7.60,
        'value' => 114.00
    ],
    'total' => 408.75
]
*/

Numeração Automática

Sistema inteligente de numeração sequencial.

// Configurar em config/filament-core.php
'invoices' => [
    'prefix' => 'INV',
    'format' => '{PREFIX}-{YEAR}-{NUMBER}',
    'start_number' => 1,
    'padding' => 4,
],

// Resultado: INV-2024-0001, INV-2024-0002, etc.

Status de Fatura

Estados possíveis:

• draft - Rascunho (editável)
• pending - Pendente de pagamento
• paid - Paga
• overdue - Vencida
• cancelled - Cancelada

Transições automáticas:

// Automaticamente marca como overdue se passou da data
// Executar diariamente via schedule:
protected function schedule(Schedule $schedule)
{
    $schedule->command('invoices:check-overdue')->daily();
}

Eventos Disparados

event(new InvoiceCreated($invoice));
event(new InvoiceUpdated($invoice));
event(new InvoicePaid($invoice));
event(new InvoiceCancelled($invoice));

Resource no Filament

Formulário:

• Section "Informações": Cliente, datas, status
• Repeater "Itens": Descrição, quantidade, valor
• Section "Totais": Cálculos automáticos
• Section "Impostos": Detalhamento de tributos

Widgets:

• Total de faturas emitidas
• Valor total faturado
• Faturas pendentes
• Gráfico mensal de faturamento

Módulo: Communications

Envio de Mensagens Multicanal

Sistema unificado para Email, SMS e WhatsApp.

Canais Suportados:

• ✉️ Email: Via SMTP, Mailgun, SES, SendGrid
• 📱 SMS: Twilio, Zenvia, Total Voice
• 💬 WhatsApp: Twilio WhatsApp API

Exemplo de Envio:

use App\Models\Communication;

// Enviar email
Communication::create([
    'person_id' => $person->id,
    'channel' => 'email',
    'subject' => 'Bem-vindo!',
    'message' => 'Olá, seja bem-vindo ao sistema.',
    'status' => 'pending',
])->send();

// Enviar SMS
Communication::create([
    'person_id' => $person->id,
    'channel' => 'sms',
    'message' => 'Seu código de verificação é: 123456',
])->send();

// Enviar WhatsApp
Communication::create([
    'person_id' => $person->id,
    'channel' => 'whatsapp',
    'message' => 'Sua fatura foi gerada!',
])->send();

Templates de Mensagens

Crie templates reutilizáveis com placeholders.

use App\Models\MessageTemplate;

// Criar template
$template = MessageTemplate::create([
    'name' => 'Boas-vindas',
    'channel' => 'email',
    'subject' => 'Bem-vindo, {{name}}!',
    'body' => 'Olá {{name}}, obrigado por se cadastrar em {{app_name}}.',
]);

// Usar template
$communication = Communication::fromTemplate($template, $person, [
    'name' => $person->name,
    'app_name' => config('app.name'),
]);

Histórico de Comunicações

Rastreamento completo de todas as mensagens enviadas.

// Ver histórico de uma pessoa
$history = Communication::where('person_id', $person->id)
    ->orderBy('sent_at', 'desc')
    ->get();

// Filtrar por canal
$emails = $person->communications()
    ->where('channel', 'email')
    ->get();

// Buscar por status
$failed = Communication::where('status', 'failed')->get();

Eventos Disparados

event(new CommunicationSent($communication));
event(new CommunicationFailed($communication));
event(new CommunicationDelivered($communication));

Resource no Filament

Formulário:

• Destinatário (pessoa)
• Canal (email/sms/whatsapp)
• Template (opcional)
• Assunto e mensagem
• Anexos (apenas email)

Tabela:

• Filtros: Canal, status, data
• Busca: Destinatário, assunto
• Ações: Reenviar, duplicar

Autenticação e Autorização

Sistema de Usuários

Baseado no Laravel Breeze + Filament Shield.

Recursos:

• Login/Logout
• Registro (opcional)
• Recuperação de senha
• Verificação de email
• Autenticação de dois fatores (opcional)

Exemplo:

use App\Models\User;

// Criar usuário
$user = User::create([
    'name' => 'Admin',
    'email' => 'admin@example.com',
    'password' => bcrypt('password'),
]);

// Atribuir papel
$user->assignRole('super-admin');

Roles e Permissions

Sistema de permissões baseado em Spatie Laravel Permission.

Papéis padrão:

• super-admin - Acesso total
• admin - Administrador
• manager - Gerente
• user - Usuário comum

Criar permissões customizadas:

use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;

// Criar permissão
Permission::create(['name' => 'view invoices']);
Permission::create(['name' => 'create invoices']);
Permission::create(['name' => 'edit invoices']);
Permission::create(['name' => 'delete invoices']);

// Criar papel e atribuir permissões
$role = Role::create(['name' => 'accountant']);
$role->givePermissionTo(['view invoices', 'create invoices']);

// Atribuir papel a usuário
$user->assignRole('accountant');

Verificar permissões:

if ($user->can('edit invoices')) {
    // Usuário pode editar faturas
}

if ($user->hasRole('super-admin')) {
    // É super admin
}

Políticas (Policies)

Controle fino de autorização por recurso.

// app/Policies/InvoicePolicy.php
class InvoicePolicy
{
    public function viewAny(User $user): bool
    {
        return $user->can('view invoices');
    }

    public function create(User $user): bool
    {
        return $user->can('create invoices');
    }

    public function update(User $user, Invoice $invoice): bool
    {
        // Apenas o criador ou admin pode editar
        return $user->id === $invoice->created_by
            || $user->hasRole('super-admin');
    }
}

Dashboard e Widgets

Widgets Incluídos

Stats Overview:

• Total de pessoas cadastradas
• Faturas emitidas este mês
• Valor total faturado
• Mensagens enviadas

Charts:

• Gráfico de faturamento mensal
• Evolução de cadastros
• Taxa de conversão

Recent Activities:

• Últimas pessoas cadastradas
• Faturas recentes
• Comunicações enviadas

Criar Widget Customizado

php artisan make:filament-widget RevenueChart

// app/Filament/Widgets/RevenueChart.php
class RevenueChart extends LineChartWidget
{
    protected static ?string $heading = 'Faturamento Mensal';

    protected function getData(): array
    {
        return [
            'datasets' => [
                [
                    'label' => 'Receita',
                    'data' => [0, 1500, 3000, 4500, 6000, 7500],
                ],
            ],
            'labels' => ['Jan', 'Fev', 'Mar', 'Abr', 'Mai', 'Jun'],
        ];
    }
}

Importação e Exportação

Exportar Dados

Exportação nativa do Filament para Excel, CSV, PDF.

// Em qualquer Resource
use Filament\Actions\ExportAction;

public static function table(Table $table): Table
{
    return $table
        ->headerActions([
            ExportAction::make()
                ->exporter(PersonExporter::class),
        ]);
}

Importar Dados

php artisan make:filament-importer PersonImporter

// app/Filament/Imports/PersonImporter.php
class PersonImporter extends Importer
{
    protected static ?string $model = Person::class;

    public static function getColumns(): array
    {
        return [
            ImportColumn::make('name')->requiredMapping(),
            ImportColumn::make('type')->requiredMapping(),
            ImportColumn::make('email'),
        ];
    }
}

Auditoria e Logs

Activity Log

Rastreamento automático de todas as ações.

use Spatie\Activitylog\Traits\LogsActivity;

class Invoice extends Model
{
    use LogsActivity;

    protected static $logAttributes = ['*'];
    protected static $logOnlyDirty = true;
}

Ver logs:

$logs = Activity::forSubject($invoice)->get();

foreach ($logs as $log) {
    echo $log->description; // "updated"
    echo $log->causer->name; // "Admin"
    print_r($log->changes()); // Array de mudanças
}

Notificações

Notificações do Filament

Sistema nativo de notificações do Filament.

use Filament\Notifications\Notification;

// Notificação de sucesso
Notification::make()
    ->title('Fatura criada!')
    ->success()
    ->send();

// Notificação de erro
Notification::make()
    ->title('Erro ao processar')
    ->danger()
    ->body('Verifique os dados e tente novamente.')
    ->send();

// Notificação para usuário específico
Notification::make()
    ->title('Nova fatura atribuída a você')
    ->sendToDatabase($user);

Próximos Passos

1. 🔧 Aprenda a Estender o Sistema
2. 🏗️ Entenda a Estrutura do Projeto
3. ⚙️ Configure Variáveis de Ambiente
4. 🚢 Prepare o Deploy em Produção

Recursos Úteis

• Documentação Filament - Resources
• Documentação Laravel - Events
• Spatie Laravel Permission