Roadmap de Aprimoramento — Filament Core Contracts

Inventário Atual

• Interfaces Financeiras: ProcessPaymentInterface, PaymentGatewayInterface, TaxCalculatorInterface, PdfGeneratorInterface.
• Comunicações: NotificationChannelInterface.
• Eventos Globais: PersonCreated, PersonUpdated, InvoiceCreated, PaymentCompleted, CommunicationSent.
• DTOs Existentes: Focado em faturas (valores monetários, identificadores, timestamps).

Lacunas Identificadas

• Ausência de contratos formais para:
  • Validação de Documentos (DocumentValidatorContract) e lookup de endereços (AddressLookupContract), hoje presentes apenas no plano do módulo People.
  • Normalização de Contatos (telefone/e-mail) e atributos customizados.
  • Eventos de auditoria (ex.: DocumentValidated, ContactNormalized, TemplateRendered).
• DTOs carecem de padronização de namespaces (ex.: Payments\DTO, People\DTO).
• Falta um manifesto público com compatibilidade por versão.

Estratégia de Versionamento

• Adotar versão semântica (v1.x, v2.0 para breaking changes).
• Manter changelog e tabela de compatibilidade com módulos (invoices, people, communications, starter-kit).
• Usar @deprecated com datas de remoção e links para substitutos.
• Criar branch next para protótipos antes de promover para main.

Testes de Contrato

• Publicar suíte mínima (tests/Contracts) que valide:
  • Implementações de PaymentGatewayInterface (autorização, captura, idempotência).
  • Validadores de documentos e normalizadores de contato (casos válidos/ inválidos, máscaras).
  • Serialização de DTOs (formato, timezone, precision).
  • Eventos: schema estável, chaves obrigatórias.
• Fornecer arquivos de fixture em JSON para garantir compatibilidade entre linguagens.

Plano de Evolução

1. Registrar contratos transversais: mover para filament-core-contracts as interfaces documentadas nos módulos (DocumentValidator, AddressLookup, ContactNormalizer, PersonAttribute).
2. Organizar namespaces: separar em domínios (Payments, People, Communications, Shared).
3. Definir DTOs base para pessoas, endereços e contatos que possam ser reutilizados por todos os pacotes.
4. Criar manifesto docs/contracts/compatibility.md com matriz de versões.
5. Automatizar validação: workflow que execute testes de contrato sempre que um pacote dependente abrir PR.

Próximos Passos Imediatos

• Levantar inventário real do repositório filament-core-contracts.
• Priorizar contratos necessários para o filament-core-starter-kit.
• Abrir RFCs internas para contratos que afetam vários times (ex.: auditoria e templates).