Contratos de Extensão — packages/people

Defina e implemente contratos para validar documentos, buscar endereços, normalizar contatos e persistir atributos customizados de pessoas. As interfaces abaixo são o ponto de entrada para pacotes adicionais.

DocumentValidatorContract

Responsável por validar documentos específicos (CPF, CNPJ, NIF europeu, passaporte etc).

<?php

namespace Filament\Core\People\Contracts;

interface DocumentValidatorContract
{
    /**
     * Identificador único (ex.: "br.cpf", "pt.nif").
     */
    public function key(): string;

    /**
     * Regex padrão para validação preliminar.
     */
    public function pattern(): string;

    /**
     * Retorna true quando o documento é válido.
     */
    public function validate(string $document): bool;

    /**
     * Normaliza o documento (remove pontuação, aplica máscara customizada, etc).
     */
    public function normalize(string $document): string;
}

• Registre implementações via container (DocumentValidatorRegistry::register()).
• Armazene configurações no banco (expressões regulares, máscaras) para edição sem código.
• Permita múltiplos validadores por país/segmento; escolha no cadastro via key().

AddressLookupContract

Resolve endereços completos a partir de CEP/código postal ou coordenadas. Pode chamar APIs externas ou bancos locais.

<?php

namespace Filament\Core\People\Contracts;

interface AddressLookupContract
{
    /**
     * Código ISO do país coberto (ex.: "BR", "US", "PT").
     */
    public function countryCode(): string;

    /**
     * Recebe CEP/código postal e retorna DTO padronizado.
     */
    public function lookupByPostalCode(string $postalCode): AddressDto;

    /**
     * Opcional: resolve a partir de coordenadas.
     */
    public function lookupByCoordinates(float $lat, float $lng): AddressDto;
}

Recomendações:

• Implementar caching inteligente para reduzir chamadas externas.
• Permitir fallback manual via DTO vazio quando não houver resultado.
• Tornar os providers configuráveis (config/people.php).

ContactNormalizerContract

Padroniza telefones e e-mails antes de persistir ou divulgar para outros módulos.

<?php

namespace Filament\Core\People\Contracts;

interface ContactNormalizerContract
{
    public function supports(string $type): bool; // "phone", "email"

    public function normalize(string $value): string;

    public function isValid(string $value): bool;
}

Sugestões:

• Implementar normalizadores de telefone usando padrões E.164 e bibliotecas (ex.: libphonenumber).
• Para e-mails, executar verificação MX opcional e higienização (lowercase, trim).
• Encadear múltiplos normalizadores por tipo usando um ContactNormalizerPipeline.

Campos Customizados (PersonAttributeContract)

Permite acrescentar campos extras (ex.: student_id, loyalty_points) com validação específica.

interface PersonAttributeContract
{
    public function key(): string;

    public function rules(): array; // Regras Laravel Validator

    public function cast(mixed $value): mixed;
}

• Armazene metadados no banco (person_attributes).
• Forneça UI Filament para ativar/desativar atributos e editar descrições.

Próximos Passos

• Criar testes de contrato em tests/Contracts para cada interface com casos de sucesso/falha.
• Documentar implementações oficiais (CPF, CNPJ, Twilio phone normalizer) em páginas dedicadas.
• Expor eventos (DocumentValidated, ContactNormalized) para auditoria e integrações externas.