Transfers

Este documento descreve todas as operações disponíveis para o agregado Transfer e seus sub-recursos, seguindo os padrões de Domain-Driven Design (DDD) e Command Query Responsibility Segregation (CQRS).

Índice

Transfers (Transferências)
TransferHistory (Histórico de Status)

Transfers (Transferências)

O agregado Transfer representa as transferências de pagamento para os profissionais após a conclusão de um serviço.

Status de Transferência

Status	Descrição
`Scheduled`	Transferência agendada para processamento futuro
`Processing`	Transferência em processamento no gateway de pagamento
`Completed`	Transferência concluída com sucesso
`Failed`	Transferência falhou durante o processamento
`Cancelled`	Transferência cancelada antes do processamento
`OnHold`	Transferência suspensa temporariamente
`Reversed`	Transferência revertida após conclusão

Fluxo de Status

Scheduled ──┬──> Processing ──┬──> Completed ──> Reversed
            │                 │
            │                 └──> Failed ──> Scheduled (reschedule)
            │
            └──> OnHold ──> Scheduled (release)
            │
            └──> Cancelled

Commands (Comandos)

1. Criação de Transferência (CreateTransfer)

Contrato: CreateTransferCommand

Campos Necessários:

ProfessionalUserId (Guid, obrigatório) - Identificador do profissional
OrderItemId (Guid, obrigatório) - Identificador do item do pedido
ProfessionalUserPaymentMethodId (Guid, obrigatório) - Identificador do método de pagamento do profissional
GrossAmount (decimal, obrigatório) - Valor bruto da transferência
Fee (decimal, obrigatório) - Taxa da transferência
ScheduledTransferDate (DateTime, obrigatório) - Data agendada para a transferência
Author (string, opcional) - Autor da operação
Observation (string, opcional) - Observações adicionais

Validações:

O profissional informado deve corresponder ao profissional do item do pedido
O método de pagamento deve pertencer ao profissional informado
NetAmount é calculado automaticamente: GrossAmount - Fee

Retorno: CreateTransferResponse

Eventos de Domínio:

TransferCreatedEvent - Disparado quando uma transferência é criada

Regras de Negócio:

A transferência é criada com status Scheduled
Um histórico de status é adicionado automaticamente

2. Iniciar Processamento (StartProcessing)

Contrato: StartProcessingTransferCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
Author (string, opcional) - Autor da operação
Observation (string, opcional) - Observações adicionais

Validações:

Transferência deve existir
Status atual deve ser Scheduled
A data agendada deve ter sido alcançada (DateTime.Now >= ScheduledTransferDate)

Retorno: Void

Regras de Negócio:

Status é alterado para Processing
ProcessedAt é definido com a data/hora atual

3. Completar Transferência (CompleteTransfer)

Contrato: CompleteTransferCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
ExternalTransactionId (string, obrigatório) - ID da transação no gateway externo
GatewayResponse (string, opcional) - Resposta do gateway
Author (string, opcional) - Autor da operação
Observation (string, opcional) - Observações adicionais

Validações:

Transferência deve existir
Status atual deve ser Processing

Retorno: Void

Eventos de Domínio:

TransferCompletedEvent - Disparado quando uma transferência é completada

Regras de Negócio:

Status é alterado para Completed
CompletedAt é definido com a data/hora atual
Reason é limpo

4. Falhar Transferência (FailTransfer)

Contrato: FailTransferCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
Reason (string, obrigatório) - Motivo da falha
GatewayResponse (string, opcional) - Resposta do gateway
Author (string, opcional) - Autor da operação

Validações:

Transferência deve existir
Status atual deve ser Processing

Retorno: Void

Eventos de Domínio:

TransferFailedEvent - Disparado quando uma transferência falha

5. Cancelar Transferência (CancelTransfer)

Contrato: CancelTransferCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
Reason (string, obrigatório) - Motivo do cancelamento
Author (string, opcional) - Autor da operação

Validações:

Transferência deve existir
Status atual deve ser Scheduled ou OnHold

Retorno: Void

Eventos de Domínio:

TransferCancelledEvent - Disparado quando uma transferência é cancelada

6. Colocar em Espera (PutTransferOnHold)

Contrato: PutTransferOnHoldCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
Reason (string, obrigatório) - Motivo da suspensão
Author (string, opcional) - Autor da operação

Validações:

Transferência deve existir
Status atual deve ser Scheduled ou Processing

Retorno: Void

Eventos de Domínio:

TransferOnHoldEvent - Disparado quando uma transferência é suspensa

7. Liberar da Espera (ReleaseTransferFromHold)

Contrato: ReleaseTransferFromHoldCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
Author (string, opcional) - Autor da operação
Observation (string, opcional) - Observações adicionais

Validações:

Transferência deve existir
Status atual deve ser OnHold

Retorno: Void

Eventos de Domínio:

TransferReleasedFromHoldEvent - Disparado quando uma transferência é liberada da espera

Regras de Negócio:

Status é alterado para Scheduled
Reason é limpo

8. Reverter Transferência (ReverseTransfer)

Contrato: ReverseTransferCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
Reason (string, obrigatório) - Motivo da reversão
Author (string, opcional) - Autor da operação

Validações:

Transferência deve existir
Status atual deve ser Completed

Retorno: Void

Eventos de Domínio:

TransferReversedEvent - Disparado quando uma transferência é revertida

9. Reagendar Transferência (RescheduleTransfer)

Contrato: RescheduleTransferCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
NewScheduledDate (DateTime, obrigatório) - Nova data agendada
Author (string, opcional) - Autor da operação
Observation (string, opcional) - Observações adicionais

Validações:

Transferência deve existir
Status atual deve ser Failed
Nova data deve ser no futuro

Retorno: Void

Eventos de Domínio:

TransferRescheduledEvent - Disparado quando uma transferência é reagendada

Regras de Negócio:

Status é alterado para Scheduled
ProcessedAt é limpo
Reason e GatewayResponse são limpos

10. Atualizar Método de Pagamento (UpdateTransferPaymentMethod)

Contrato: UpdateTransferPaymentMethodCommand

Campos Necessários:

TransferId (Guid, obrigatório) - Identificador da transferência
ProfessionalUserPaymentMethodId (Guid, obrigatório) - Novo método de pagamento
Author (string, opcional) - Autor da operação

Validações:

Transferência deve existir
Status atual deve ser Scheduled ou Failed
Método de pagamento deve pertencer ao profissional

Retorno: Void

Eventos de Domínio:

TransferPaymentMethodUpdatedEvent - Disparado quando o método de pagamento é atualizado

Queries (Consultas)

1. Buscar Transferência por ID (GetTransferById)

Contrato: GetTransferByIdQuery

Parâmetros:

Id (Guid, obrigatório) - Identificador da transferência

Retorno: GetTransferByIdResponse

2. Pesquisar Transferências (SearchTransfers)

Contrato: SearchTransfersQuery

Parâmetros:

ProfessionalUserId (Guid, opcional) - Filtrar por profissional
OrderItemId (Guid, opcional) - Filtrar por item do pedido
Status (TransferStatus, opcional) - Filtrar por status
StartDate (DateTime, opcional) - Data inicial de criação
EndDate (DateTime, opcional) - Data final de criação
PageNumber (int, padrão: 1) - Número da página
PageSize (int, padrão: 100) - Tamanho da página

Retorno: SearchTransfersResponse (lista paginada de transferências)

TransferHistory (Histórico de Status)

Entidade que registra todas as mudanças de status de uma transferência.

Propriedades

Campo	Tipo	Descrição
`Id`	Guid	Identificador único
`TransferId`	Guid	Referência à transferência
`Status`	TransferStatus	Status registrado
`Observation`	string	Observação sobre a mudança
`Created`	DateTime	Data/hora do registro
`AuthorCreated`	string	Autor da mudança

Regras de Negócio

O histórico é criado automaticamente a cada mudança de status
Não pode ser alterado após criação (imutável)
Permite auditoria completa do ciclo de vida da transferência

Relacionamentos

Transfer

ProfessionalUser (N:1) - Profissional que receberá a transferência
OrderItem (N:1) - Item do pedido relacionado
ProfessionalUserPaymentMethod (N:1) - Método de pagamento utilizado
TransferHistory (1:N) - Histórico de mudanças de status

Eventos de Domínio

Evento	Descrição
`TransferCreatedEvent`	Disparado quando uma transferência é criada
`TransferCompletedEvent`	Disparado quando uma transferência é completada
`TransferFailedEvent`	Disparado quando uma transferência falha
`TransferCancelledEvent`	Disparado quando uma transferência é cancelada
`TransferOnHoldEvent`	Disparado quando uma transferência é suspensa
`TransferReleasedFromHoldEvent`	Disparado quando uma transferência é liberada da espera
`TransferReversedEvent`	Disparado quando uma transferência é revertida
`TransferRescheduledEvent`	Disparado quando uma transferência é reagendada
`TransferPaymentMethodUpdatedEvent`	Disparado quando o método de pagamento é atualizado