Report Handlers

Um report handler define um relatório disponível na plataforma: seus filtros, formatos de exportação, permissão mínima e a lógica de execução. Cada handler implementa App\Contracts\ReportContract e é registrado por um módulo através do método reportHandlers() do contrato de módulo. Relatórios do próprio core também implementam esse contrato.

Nome do método × nome da interface

O método do contrato de módulo chama-se reportHandlers(), mas as classes que ele retorna implementam a interface ReportContract (não existe ReportHandlerContract).

Registro

public function reportHandlers(): array
{
    return [ExposureComplianceReport::class];
}

A interface ReportContract

Método	Retorno	Descrição
type()	ReportType	Tipo do relatório — valor do enum App\Enums\ReportType
module()	?string	Identifier do módulo dono, ou null para relatórios do core
feature()	?string	Sub-recurso do qual o relatório depende, ou null se sempre disponível
name()	string	Nome de exibição
description()	string	Descrição curta
minimumRole()	UserRole	Perfil mínimo para executar (enum App\Enums\UserRole)
availableFilters()	array<string, array{label: string, type: string}>	Filtros que o relatório aceita
supportedFormats()	list<ReportFormat>	Formatos de exportação suportados (enum App\Enums\ReportFormat)
execute(ReportFilters $filters, User $user)	ReportResult	Executa o relatório e devolve o resultado

O execute() recebe um App\DataObjects\ReportFilters e o usuário solicitante, e devolve um App\DataObjects\ReportResult. O relatório declara seus próprios filtros e formatos — não há um conjunto fixo de formatos imposto pelo core.

Formatos variam por relatório

Não presuma que todo relatório exporta CSV/XLSX/PDF. O conjunto real vem de supportedFormats() de cada handler. Em v0.8.7, os relatórios do core exportam apenas os formatos que declaram individualmente.

Exporters

A conversão de um ReportResult para arquivo é responsabilidade de exporters que implementam App\Contracts\ReportExporterContract:

interface ReportExporterContract
{
    public function export(ReportResult $result, string $filename): string;
}

O export() recebe o resultado e um nome de arquivo, e devolve o caminho do arquivo gerado. Cada formato de ReportFormat tem seu exporter correspondente.

Fluxo de execução

1. O usuário solicita um relatório; o core verifica minimumRole() e, quando aplicável, se o módulo/sub-recurso (module()/feature()) está habilitado para o site.
2. Os filtros informados são validados contra availableFilters() e empacotados em ReportFilters.
3. execute() produz um ReportResult.
4. Um exporter (ReportExporterContract) converte o resultado para o formato escolhido dentre os supportedFormats().

Próximos passos

• Contrato de Módulo — Como reportHandlers() se registra
• Relatórios — Os relatórios sob a ótica do usuário
• Alert Handlers — O contrato irmão para alertas