Orders

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

Índice

Orders (Pedidos)
OrderItems (Itens de Pedido)
OrderPayments (Pagamentos)

Orders (Pedidos)

Commands (Comandos)

1. Criação de Pedido (CreateOrder)

Contrato: CreateOrderCommand

Campos Necessários:

RequestId (Guid, obrigatório) - Identificador da solicitação origem
UserId (Guid, obrigatório) - Identificador do usuário
Code (string, obrigatório) - Código do pedido
Author (string, opcional) - Autor da operação

Validações:

RequestId: Não pode ser vazio; Solicitação deve existir
UserId: Não pode ser vazio; Usuário deve existir
Code: Não pode ser vazio

Retorno: CreateOrderResponse

Eventos de Domínio:

OrderCreatedEvent - Disparado quando um pedido é criado

Regras de Negócio:

Pedido é criado a partir de uma solicitação processada
Pedido é criado com status Pending
Code é único e identifica o pedido
Preços são herdados da solicitação

2. Atualização de Pedido (UpdateOrder)

Contrato: UpdateOrderCommand

Campos Necessários:

Id (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
Status (OrderStatus enum, opcional) - Novo status do pedido
Observation (string, opcional) - Observações adicionais
Author (string, opcional) - Autor da operação

Validações:

Id: Pedido deve existir
Status: Deve ser um valor válido do enum quando fornecido

Retorno: Void

Eventos de Domínio:

OrderUpdatedEvent - Disparado quando um pedido é atualizado

Regras de Negócio:

Permite atualizar status e observações
Não permite atualizar pedidos cancelados ou finalizados

3. Processar Pedido (ProcessOrder)

Contrato: ProcessOrderCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido

Validações:

OrderId: Pedido deve existir
Pedido deve estar com status Pending

Retorno: Void

Eventos de Domínio:

OrderProcessedEvent - Disparado quando um pedido é processado

Regras de Negócio:

Altera status do pedido para Processed
Valida que todos os itens têm profissionais atribuídos
Libera o pedido para pagamento

4. Deletar Pedido (DeleteOrder)

Contrato: DeleteOrderCommand

Campos Necessários:

Id (Guid, obrigatório) - Identificador do pedido

Validações:

Id: Pedido deve existir

Retorno: Void

Regras de Negócio:

Remove permanentemente o pedido do banco de dados
Remove todos os itens e pagamentos associados
Operação irreversível

Queries (Consultas)

1. Buscar Pedido por ID (GetOrderById)

Contrato: GetOrderByIdQuery

Parâmetros:

Id (Guid, obrigatório) - Identificador do pedido

Retorno: GetOrderByIdResponse

Descrição:

Retorna todos os dados do pedido especificado
Inclui detalhes de preços, datas, status e itens

2. Pesquisar Pedidos (SearchOrders)

Contrato: SearchOrdersQuery

Parâmetros:

ProfessionalUserId (Guid, opcional) - Filtrar por profissional
UserId (Guid, opcional) - Filtrar por usuário
RequestId (Guid, opcional) - Filtrar por solicitação origem
Status (OrderStatus enum, opcional) - Filtrar por status
IsPaid (bool, opcional) - Filtrar por pedidos pagos (true) ou não pagos (false)
StartDt (DateTime, opcional) - Data inicial
EndDt (DateTime, opcional) - Data final
PageNumber (int, padrão: 1) - Número da página
PageSize (int, padrão: 30) - Tamanho da página

Retorno: SearchOrdersResponse (lista paginada de pedidos)

Descrição:

Retorna uma lista paginada de pedidos conforme os filtros aplicados
O filtro IsPaid permite buscar facilmente pedidos pagos ou pendentes de pagamento

Campos retornados em cada item (SearchOrdersResponseItem):

Id - Identificador do item do pedido
RequestItemId - Identificador do item da solicitação
ResponseId - Identificador da resposta do profissional (se houver)
Status - Status do item do pedido
TaskName - Nome da tarefa/serviço
Address - Endereço onde o serviço será realizado
BasePrice - Preço base para o cliente
FinalPrice - Preço final para o cliente
ProfessionalBasePrice - Preço base para o profissional
ProfessionalFinalPrice - Preço final para o profissional
Skills - Habilidades necessárias (Dictionary)
Professional - Dados do profissional atribuído (se houver)
StartDt - Data/hora de início do serviço
EndDt - Data/hora de término do serviço
Created - Data/hora de criação
Updated - Data/hora de atualização
Observation - Observações adicionais
AuthorCreated - Autor da criação
AuthorUpdated - Autor da última atualização

OrderItems (Itens de Pedido)

Commands (Comandos)

1. Adicionar Item ao Pedido (AddOrderItem)

Contrato: AddOrderItemCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
RequestItemId (Guid, obrigatório) - Identificador do item da solicitação
ProfessionalUserId (Guid, obrigatório) - Identificador do profissional
Observation (string, opcional) - Observações adicionais
Author (string, opcional) - Autor da operação

Validações:

OrderId: Não pode ser vazio; Pedido deve existir
RequestItemId: Não pode ser vazio; Item da solicitação deve existir
ProfessionalUserId: Não pode ser vazio; Profissional deve existir

Retorno: AddOrderItemResponse

Eventos de Domínio:

OrderItemAddedEvent - Disparado quando um item é adicionado

Regras de Negócio:

Adiciona um serviço ao pedido
Profissional deve ter aceitado a resposta do RequestItem
Herda dados do RequestItem (tarefa, endereço, atributos)
Atualiza preços do pedido
Item é criado com status Pending

2. Remover Item do Pedido (RemoveOrderItem)

Contrato: RemoveOrderItemCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido
OrderItemId (Guid, obrigatório) - Identificador do item

Validações:

Item deve existir para o pedido

Retorno: Void

Eventos de Domínio:

OrderItemRemovedEvent - Disparado quando um item é removido

Regras de Negócio:

Remove o item do pedido
Atualiza preços do pedido
Não pode remover itens já iniciados ou finalizados

3. Definir Profissional (SetProfessional)

Contrato: SetProfessionalCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
OrderItemId (Guid, obrigatório) - Identificador do item (JsonIgnore)
ProfessionalUserId (Guid, obrigatório) - Identificador do profissional
Author (string, opcional) - Autor da operação
Observation (string, opcional) - Observações adicionais

Validações:

Item deve existir para o pedido
Profissional deve existir
Profissional deve ter habilidades necessárias

Retorno: Void

Eventos de Domínio:

ProfessionalSetToOrderItemEvent - Disparado quando um profissional é definido

Regras de Negócio:

Define ou altera o profissional responsável pelo item
Profissional deve ter as habilidades necessárias para a tarefa
Pode substituir profissional se necessário

4. Adicionar Profissional por Busca (AddProfessionalByFind)

Contrato: AddProfessionalByFindCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
OrderItemId (Guid, obrigatório) - Identificador do item (JsonIgnore)
Author (string, opcional) - Autor da operação

Validações:

Item deve existir para o pedido
Item não deve ter profissional atribuído

Retorno: AddProfessionalByFindResponse (contém o profissional encontrado)

Regras de Negócio:

Sistema busca automaticamente um profissional disponível
Profissional deve ter:
Habilidades necessárias
Disponibilidade no horário
Atender na cidade do serviço
Profissional é atribuído automaticamente ao item

5. Definir Status do Item (SetOrderItemStatus)

Contrato: SetOrderItemStatusCommand

Campos Necessários:

Id (Guid, obrigatório) - Identificador do item (JsonIgnore)
OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
Status (OrderStatus enum, obrigatório) - Novo status
Observation (string, opcional) - Observações adicionais
Author (string, opcional) - Autor da operação

Validações:

Item deve existir para o pedido
Status: Deve ser um valor válido do enum
Transição de status deve ser válida

Retorno: Void

Eventos de Domínio:

OrderItemStatusChangedEvent - Disparado quando o status muda

Regras de Negócio:

Permite controlar o ciclo de vida do item
Status possíveis: Pending, InProgress, Completed, Cancelled
Não pode voltar status (ex: de Completed para InProgress)

Queries (Consultas)

1. Buscar Itens do Pedido (GetOrderItems)

Contrato: GetOrderItemsQuery

Parâmetros:

OrderId (Guid, obrigatório) - Identificador do pedido

Retorno: GetOrderItemsResponse (lista de itens)

Descrição:

Retorna todos os itens de um pedido
Inclui detalhes do profissional, tarefa, endereço e preços

2. Buscar Item por ID (GetOrderItemById)

Contrato: GetOrderItemByIdQuery

Parâmetros:

OrderId (Guid, obrigatório) - Identificador do pedido
OrderItemId (Guid, obrigatório) - Identificador do item

Retorno: GetOrderItemByIdResponse

Descrição:

Retorna um item específico do pedido com todos os detalhes

OrderPayments (Pagamentos)

Commands (Comandos)

1. Criar Pagamento (CreateOrderPayment)

Contrato: CreateOrderPaymentCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
CorrelationId (Guid, obrigatório) - Identificador de correlação (JsonIgnore)
ExpiresAt (DateTime, padrão: DateTime.Now.AddDays(2)) - Data de expiração
ExternalPaymentId (string, opcional) - ID do pagamento no sistema externo
Author (string, opcional) - Autor da operação

Validações:

OrderId: Não pode ser vazio; Pedido deve existir
CorrelationId: Não pode ser vazio
ExpiresAt: Deve ser no futuro

Retorno: CreateOrderPaymentResponse (contém URL de pagamento)

Eventos de Domínio:

OrderPaymentCreatedEvent - Disparado quando um pagamento é criado

Regras de Negócio:

Cria uma cobrança no sistema de pagamento externo
Pedido deve estar processado
Gera URL para pagamento
Pagamento é criado com status Pending
Expira automaticamente após a data definida

2. Marcar Pagamento como Pago (MarkPaymentAsPaid)

Contrato: MarkPaymentAsPaidCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
PaymentId (Guid, obrigatório) - Identificador do pagamento (JsonIgnore)
ExternalPaymentId (string, obrigatório) - ID do pagamento confirmado
Observation (string, opcional) - Observações adicionais
Author (string, opcional) - Autor da operação

Validações:

Pagamento deve existir para o pedido
Pagamento deve estar com status Pending
ExternalPaymentId: Não pode ser vazio

Retorno: Void

Eventos de Domínio:

OrderPaymentPaidEvent - Disparado quando um pagamento é confirmado

Regras de Negócio:

Confirma o pagamento
Altera status do pagamento para Paid
Altera status do pedido para Paid
Libera os serviços para execução

3. Atualizar URL de Pagamento (UpdatePaymentUrl)

Contrato: UpdatePaymentUrlCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido
PaymentId (Guid, obrigatório) - Identificador do pagamento
PaymentUrl (string, obrigatório) - Nova URL de pagamento
Author (string, opcional) - Autor da operação

Validações:

Pagamento deve existir para o pedido
PaymentUrl: Não pode ser vazio; Deve ser uma URL válida

Retorno: Void

Regras de Negócio:

Atualiza a URL de pagamento
Usado quando há renovação de link de pagamento

4. Cancelar Pagamento (CancelPayment)

Contrato: CancelPaymentCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
PaymentId (Guid, obrigatório) - Identificador do pagamento (JsonIgnore)
Reason (string, obrigatório) - Motivo do cancelamento
Author (string, opcional) - Autor da operação

Validações:

Pagamento deve existir para o pedido
Reason: Não pode ser vazio

Retorno: Void

Eventos de Domínio:

OrderPaymentCancelledEvent - Disparado quando um pagamento é cancelado

Regras de Negócio:

Cancela o pagamento
Altera status do pagamento para Cancelled
Cancela também no sistema de pagamento externo
Não pode cancelar pagamentos já pagos

5. Reembolsar Pagamento (RefundPayment)

Contrato: RefundPaymentCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
PaymentId (Guid, obrigatório) - Identificador do pagamento (JsonIgnore)
Reason (string, obrigatório) - Motivo do reembolso
Author (string, opcional) - Autor da operação

Validações:

Pagamento deve existir para o pedido
Pagamento deve estar com status Paid
Reason: Não pode ser vazio

Retorno: Void

Eventos de Domínio:

OrderPaymentRefundedEvent - Disparado quando um pagamento é reembolsado

Regras de Negócio:

Reembolsa o pagamento
Altera status do pagamento para Refunded
Processa reembolso no sistema de pagamento externo
Apenas pagamentos pagos podem ser reembolsados

6. Atualizar Pagamento (UpdateOrderPayment)

Contrato: UpdateOrderPaymentCommand

Campos Necessários:

OrderId (Guid, obrigatório) - Identificador do pedido (JsonIgnore)
OrderPaymentId (Guid, obrigatório) - Identificador do pagamento (JsonIgnore)
BillingAddress (BillingAddress, opcional) - Endereço de cobrança
PaymentDetails (PaymentDetails, opcional) - Detalhes do pagamento
ExternalPaymentId (string, opcional) - ID do pagamento externo
Author (string, opcional) - Autor da operação

Validações:

OrderId: Não pode ser vazio; Pedido deve existir
OrderPaymentId: Não pode ser vazio; Pagamento deve existir

Retorno: Void

Regras de Negócio:

Permite atualizar informações do pagamento
Registra alteração no histórico (OrderPaymentHistory)
Não pode atualizar pagamentos finalizados (Paid, Refunded)

Exemplo de Uso:

{
  "billingAddress": {
    "responsibleName": "João Silva",
    "responsibleDocument": "123.456.789-00",
    "street": "Rua Exemplo",
    "number": "123",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01234-567"
  },
  "externalPaymentId": "pay_abc123",
  "author": "admin@sistema.com"
}

Queries (Consultas)

1. Pesquisar Pagamentos (SearchPayments)

Contrato: SearchPaymentsQuery

Parâmetros:

OrderId (Guid, opcional) - Filtrar por pedido
UserId (Guid, opcional) - Filtrar por usuário
Status (PaymentStatus enum, opcional) - Filtrar por status
StartDate (DateTime, opcional) - Data inicial
EndDate (DateTime, opcional) - Data final
PageNumber (int, padrão: 1) - Número da página
PageSize (int, padrão: 100) - Tamanho da página

Retorno: SearchPaymentsResponse (lista paginada de pagamentos)

Descrição:

Retorna uma lista paginada de pagamentos conforme os filtros aplicados

2. Buscar Pagamento por ID (GetPaymentById)

Contrato: GetPaymentByIdQuery

Parâmetros:

OrderId (Guid, obrigatório) - Identificador do pedido
PaymentId (Guid, obrigatório) - Identificador do pagamento

Retorno: GetPaymentByIdResponse

Descrição:

Retorna um pagamento específico com todos os detalhes
Inclui URL de pagamento e informações do sistema externo

3. Buscar Histórico de Pagamento (GetPaymentHistory)

Contrato: GetPaymentHistoryQuery

Parâmetros:

OrderId (Guid, obrigatório) - Identificador do pedido
PaymentId (Guid, obrigatório) - Identificador do pagamento

Retorno: GetPaymentHistoryResponse (histórico de alterações)

Descrição:

Retorna todo o histórico de alterações do pagamento
Inclui mudanças de status, tentativas, etc.

Eventos de Domínio

Order

OrderCreatedEvent - Disparado quando um pedido é criado
OrderUpdatedEvent - Disparado quando um pedido é atualizado
OrderProcessedEvent - Disparado quando um pedido é processado

OrderItems

OrderItemAddedEvent - Disparado quando um item é adicionado
OrderItemRemovedEvent - Disparado quando um item é removido
ProfessionalSetToOrderItemEvent - Disparado quando um profissional é atribuído
OrderItemStatusChangedEvent - Disparado quando o status de um item muda

OrderPayments

OrderPaymentCreatedEvent - Disparado quando um pagamento é criado
OrderPaymentPaidEvent - Disparado quando um pagamento é confirmado
OrderPaymentCancelledEvent - Disparado quando um pagamento é cancelado
OrderPaymentRefundedEvent - Disparado quando um pagamento é reembolsado

Regras Gerais de Negócio

Pedido (Order)

Pedido é criado a partir de uma Request processada
Code é único e identifica o pedido
Status possíveis: Pending, Processed, Paid, InProgress, Completed, Cancelled
Pedido deve estar processado para aceitar pagamentos
Preços são calculados com base nos itens e descontos
OrderDetails contém: BasePrice, ProfessionalsBasePrice, FinalPrice, ProfessionalsFinalPrice

Itens de Pedido (OrderItems)

Cada item representa um serviço a ser executado
Item deve ter um profissional atribuído
Profissional pode ser atribuído manualmente ou automaticamente
Herda dados do RequestItem correspondente
Status possíveis: Pending, InProgress, Completed, Cancelled
Não pode remover itens já iniciados ou finalizados

Pagamentos (OrderPayments)

Pagamento expira em 2 dias por padrão
Integrado com sistema de pagamento externo
Status possíveis: Pending, Paid, Cancelled, Refunded, Expired
Apenas pagamentos pendentes podem ser cancelados
Apenas pagamentos pagos podem ser reembolsados
Webhook do sistema externo atualiza status automaticamente

Fluxo Completo

Fluxo do Pedido:

Criar Pedido → CreateOrder (a partir de uma Request)
Adicionar Itens → AddOrderItem (para cada RequestItem aceito)
Atribuir Profissionais → SetProfessional ou AddProfessionalByFind
Processar Pedido → ProcessOrder (valida e libera para pagamento)
Criar Pagamento → CreateOrderPayment (gera URL de pagamento)
Confirmar Pagamento → MarkPaymentAsPaid (após webhook)
Executar Serviços → SetOrderItemStatus (InProgress → Completed)

Fluxo de Pagamento:

Criar → Sistema cria cobrança e gera URL
Aguardar → Cliente realiza pagamento
Webhook → Sistema externo confirma pagamento
Marcar como Pago → Sistema atualiza status
Liberar Serviços → Profissionais podem iniciar trabalho

Fluxo de Cancelamento/Reembolso:

Antes do Pagamento → CancelPayment
Após o Pagamento → RefundPayment

Padrões Utilizados

CQRS (Command Query Responsibility Segregation)

Commands: Operações que modificam o estado (Create, Add, Remove, Set, Mark, Cancel, Refund)
Queries: Operações que apenas consultam dados (Get, Search)

DDD (Domain-Driven Design)

Agregados: Order é o agregado raiz
Entidades: OrderItem, OrderPayment
Value Objects: OrderDetails, Address, TaskAttribute
Domain Events: Eventos disparados quando ações importantes ocorrem
Invariantes: Regras de negócio mantidas pelo agregado

Repository Pattern

Acesso a dados abstraído através de interfaces de repositório

MediatR Pattern

Commands e Queries implementados como requests do MediatR
Handlers processam as requisições

FluentValidation

Validações declarativas para commands e queries

Integration Events

Integração com sistema de pagamento externo via webhooks

Observações Finais

Todos os campos marcados com [JsonIgnore] não aparecem no contrato JSON da API
Campos opcionais podem ser null
Enums devem ser valores válidos conforme definição
Validações de tamanho máximo referem-se aos valores numéricos especificados
Eventos de domínio são disparados de forma assíncrona
Operações que modificam estado são transacionais
Observation máximo: 500 caracteres
OrderDetails calcula automaticamente preços com e sem descontos
Pagamentos expiram em 2 dias por padrão
Sistema integrado com gateway de pagamento externo
Webhooks atualizam status de pagamento automaticamente