Plano do Módulo packages/people

Objetivo

Fornecer uma base independente para gestão de pessoas (físicas e jurídicas), papéis e sincronização de dados entre os demais módulos do ecossistema Filament Core dentro do monorepo.

Estrutura Inicial

packages/people/
├─ src/
│  ├─ Models/Person.php
│  ├─ Enums/PersonRole.php
│  ├─ DTOs/
│  ├─ Events/
│  └─ Actions/
│  ├─ Documents/
│  │  ├─ Contracts/
│  │  ├─ Validators/
│  │  └─ ValueObjects/
│  ├─ Addresses/
│  │  ├─ Contracts/
│  │  └─ Providers/
│  └─ Contacts/
│     ├─ Normalizers/
│     └─ Validators/
├─ database/
│  ├─ migrations/
│  └─ seeders/
├─ tests/
│  ├─ Feature/
│  └─ Unit/
└─ composer.json

Pontos-Chave

• Models e Enums: Person centraliza atributos; PersonRole define papéis múltiplos.
• DTOs: expõem dados normalizados (contato, endereço, documentos) para packages/invoices e packages/communications, incluindo metadados customizados.
• Eventos: publicar PersonCreated e PersonUpdated usando payloads definidos em packages/contracts.
• Ações: encapsular fluxos críticos (criação, atualização, sincronização externa) com Laravel Actions.
• Documentos: Value Objects por tipo (NationalId, TaxId, Passport) configuráveis via banco, com suporte a registradores de regex e algoritmos de verificação.
• Endereços: adaptadores para múltiplas APIs de CEP, normalização de países/estados e fallback manual.
• Contatos: pipelines para validar telefones (E.164, mascaramento) e e-mails (MX check, deduplicação).

Integrações

• Consumir contratos de endereço/documento de packages/contracts.
• Disponibilizar listeners de eventos externos (ex.: atualizar permissões quando pagamento for concluído).
• Permitir extensões via container para registrar validadores ou provedores customizados para cenários regionais.

Roadmap Técnico

1. Implementar migrations e seeds mínimos (papéis padrão, templates de documentos, campos customizados).
2. Criar factories e testes de contrato cobrindo eventos, DTOs, validadores e provedores de CEP.
3. Disponibilizar painéis Filament para gerenciar configurações (regex, campos extras, provedores).
4. Documentar APIs públicas dentro de docs/people/ e manter exemplos de extensões.

Referências

• Guia People
• Contratos de Extensão
• Exemplos Oficiais
• Roadmap Técnico
• Diagrama Monorepo