RFC Business::CPI::{Base|Role}::Receiver

ideias

Comecei a implementar a solução do problema que descrevo abaixo aqui:

https://github.com/andrewalker/p5-business-cpi/blob/master/lib/Business/CPI/Role/Receiver.pm

=============

Atualmente:

  my $cpi = Business::CPI->new(
      gateway => 'PayPal',
      receiver_id => 'meu@email.com',
  );

  # ou
  my $cpi = Business::CPI->new(
      gateway => 'PayPal',
      receiver_email => 'meu@email.com',
  );

===

Problemas:

   - não deveria haver receiver_email, pois nem todos os gateways utilizam
     e-mail como chave de identificação do usuário — foi uma falha de design;
   - pode haver vários receivers por pagamento

===

Ideia:

Criar uma classe Business::CPI::Base::Receiver (todas as classes auxiliares
foram movidas para ::Base), com os atributos:

   - gateway_id
   - name (ou não?)
   - email (ou não?)
   - is_primary (boolean)
   - fixed_amount (valor fixo a ser recebido por pagamento)
   - percent_amount (porcentagem a ser recebido por pagamento)

A instanciação poderia permanecer:

  my $cpi = Business::CPI->new(
      gateway => 'PayPal',
      receiver_id => 'meu@email.com',
  );

Mas aí a gente mexeria no BUILDARGS pra remover receiver_id, e construir um
objeto 'receiver':

  # around BUILDARGS
  $self->$orig({
      ...,
      receiver => Receiver->new(gateway_id => $receiver_id, is_primary => 1)
  });

Ou algo assim.

Ao construir um cart, o usuário poderia setar vários receivers, do tipo:

  $cpi->new_cart({
      ...,
      receivers => [
          {
              gateway_id => 'receiver1@gmail.com',
              percent_amount => 30.2
          },
          {
              gateway_id => 'receiver2@gmail.com',
              percent_amount => 10
          },
          {
              gateway_id => 'receiver3@gmail.com',
              fixed_amount => 5
          },
      ],
  });

Isso resolve Chained Payments do PayPal, por exemplo. Mas e Parallel Payments?
Poderia haver uma chave is_parallel, com default false, no Cart.

Ou então, toda vez que são definidos receivers, tem que definir explicitamente
também o primary (aquele que foi passado na instanciação via receiver_id) com
is_primary => 1. Se definir, é Chained, senão, parallel.

Terceira possibilidade é verificar as porcentagens e valores fixos contra o
valor total a ser cobrado. Se totalizar 100%, não precisa incluir o primary.
Senão, inclua com o restante.

===

Outra questão:

Um receiver é-um Account? Ou tem um Account? Ou é composto pelo role Account?

Veja:

https://metacpan.org/pod/release/ANDRE/Business-CPI-0.909-TRIAL/lib/Business/CPI/Role/Account.pm

e

https://metacpan.org/pod/release/ANDRE/Business-CPI-0.909-TRIAL/lib/Business/CPI/Base/Account.pm

Não vou manter os atributos "name" e "email" no Receiver. Não faz sentido.

Vou criar um atributo "account", que já contém esses campos. Isso já resolve a última questão também.