Filament Core People

Propósito

Fornecer uma fonte única de verdade para pessoas físicas e jurídicas utilizadas pelos demais módulos. Padroniza papéis (aluno, cliente, instrutor) e publica eventos para manter sincronização entre módulos do monorepo.

Modelo de Dados

• Entidade Person com campos name, document, contact, address e metadados personalizáveis via esquema JSON.
• Coleção roles[] baseada em enum para representar múltiplas funções simultâneas, com suporte a taxonomias definidas em banco.
• Estrutura preparada para dados sensíveis (CPF/CNPJ e equivalentes internacionais) com camadas de encriptação configuráveis.

Estrutura da Entidade

Person
 ├─ name
 ├─ document
 │   ├─ type
 │   └─ value
 ├─ contact
 │   ├─ emails[]
 │   └─ phones[]
 ├─ address
 │   ├─ street
 │   ├─ number
 │   ├─ district
 │   ├─ city
 │   ├─ state
 │   ├─ postal_code
 │   └─ country
 └─ roles[]

Eventos

• PersonCreated: dispara atualizações em Invoices (faturamento inicial) e Communications (mensagens de boas-vindas).
• PersonUpdated: mantém cadastros e notificações alinhados entre módulos.

Integrações Notáveis

• Sincroniza atributos derivados (por exemplo, limites de crédito) com packages/invoices.
• Expõe DTOs de contato para que packages/communications decida canais disponíveis.
• Disponibiliza APIs para lookup de CEP/códigos postais pluggáveis (Brasil, EUA, UE) e validação de telefone via serviços externos.

Validações e Personalização

• Documentos são compostos por Value Objects especializados (NationalId, BusinessId, PassportId) avaliados por expressões regulares configuráveis em banco.
• Pacotes adicionais podem registrar validadores (DocumentValidatorContract) para tratar regras locais ou algoritmos de checksum.
• Campos customizados devem ser mapeados no esquema person_attributes com migrações versionadas.
• Endereços utilizam adaptadores (AddressLookupContract) para consumir APIs de CEP diferentes, com fallback manual.
• Telefones e e-mails passam por pipelines assíncronas para normalizar e higienizar dados.

Recomendações

• Centralize validações em Value Objects e validadores registrados dinamicamente para evitar duplicação em serviços externos.
• Adicione migrações e seeders de papéis e documentos em páginas dedicadas (docs/people/seeding.md) conforme forem criadas.

Leitura Complementar

• Roadmap Técnico
• Plano do Módulo People
• Contratos de Extensão do Módulo People
• Exemplos Oficiais de Validadores e Normalizadores
• Guia de Contracts
• Guia de Communications