Requests

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

Índice

Requests (Solicitações)
RequestItems (Itens de Solicitação)
RequestItemResponses (Respostas de Itens)

Requests (Solicitações)

Commands (Comandos)

1. Criação de Solicitação (CreateRequest)

Contrato: CreateRequestCommand

Campos Necessários:

Origin (string, obrigatório) - Origem da solicitação
StartDt (DateTime, obrigatório) - Data e hora de início desejada
Parameters (Dictionary, padrão: vazio) - Parâmetros customizados
Metadata (Dictionary, padrão: vazio) - Metadados adicionais
Details (CreateRequestDetails, opcional) - Detalhes da solicitação
Items (IEnumerable, opcional) - Itens da solicitação
UserId (Guid, opcional) - Identificador do usuário
Observation (string, opcional) - Observações adicionais
Author (string, opcional) - Autor da operação

Validações:

Origin: Não pode ser vazio; Tamanho máximo: 100 caracteres
StartDt: Não pode ser vazio
Observation: Tamanho máximo: 500 caracteres quando fornecido

Retorno: CreateRequestResponse

Eventos de Domínio:

RequestCreatedEvent - Disparado quando uma solicitação é criada

Regras de Negócio:

Pode criar um usuário automaticamente se não fornecido (implementa ICreateUserCommand)
Solicitação é criada com status Pending
Pode incluir itens na criação

2. Criação de Solicitação com Itens (CreateRequestWithItems)

Contrato: CreateRequestWithItemsCommand

Campos Necessários:

UserId (Guid, opcional) - Identificador do usuário
Origin (string, obrigatório) - Origem da solicitação
StartDt (DateTime, obrigatório) - Data e hora de início desejada
Parameters (Dictionary, padrão: vazio) - Parâmetros customizados
Metadata (Dictionary, padrão: vazio) - Metadados adicionais
Items (IEnumerable, obrigatório) - Itens da solicitação
Observation (string, opcional) - Observações adicionais
Author (string, opcional) - Autor da operação

Validações:

UserId: Deve ser válido quando fornecido
Origin: Não pode ser vazio; Tamanho máximo: 100 caracteres
Observation: Tamanho máximo: 500 caracteres quando fornecido
Items: Cada item deve passar pela validação RequestItemDtoValidator

Retorno: CreateRequestWithItemsResponse

Eventos de Domínio:

RequestCreatedEvent - Disparado quando uma solicitação é criada
RequestItemAddedEvent - Disparado para cada item adicionado

Regras de Negócio:

Pode criar um usuário automaticamente se não fornecido (implementa ICreateUserCommand)
Solicitação é criada com status Pending
Deve incluir pelo menos um item
Preços são calculados automaticamente com base nos itens

3. Processar Solicitação (ProcessRequest)

Contrato: ProcessRequestCommand

Campos Necessários:

Id (Guid, obrigatório) - Identificador da solicitação (JsonIgnore)
UserId (Guid, opcional) - Identificador do usuário
Code (string, opcional) - Código de verificação
Author (string, padrão: vazio) - Autor da operação

Validações:

Id: Solicitação deve existir
Solicitação deve estar com status Pending

Retorno: Void

Eventos de Domínio:

RequestProcessedEvent - Disparado quando uma solicitação é processada

Regras de Negócio:

Altera status da solicitação para Processed
Vincula usuário à solicitação se fornecido
Valida código de verificação se fornecido
Permite que profissionais vejam e respondam aos itens

4. Deletar Solicitação (DeleteRequest)

Contrato: DeleteRequestCommand

Campos Necessários:

Id (Guid, obrigatório) - Identificador da solicitação

Validações:

Id: Solicitação deve existir

Retorno: Void

Regras de Negócio:

Remove permanentemente a solicitação do banco de dados
Remove todos os itens associados
Operação irreversível

Queries (Consultas)

1. Buscar Solicitação por ID (GetRequestById)

Contrato: GetRequestByIdQuery

Parâmetros:

Id (Guid, obrigatório) - Identificador da solicitação

Retorno: GetRequestByIdResponse

Descrição:

Retorna todos os dados da solicitação especificada
Inclui detalhes de preços e datas

2. Pesquisar Solicitações (SearchRequests)

Contrato: SearchRequestsQuery

Parâmetros:

Status (RequestStatus enum, opcional) - Filtrar por status
JobTaskId (Guid, opcional) - Filtrar por tarefa de trabalho
CityId (Guid, opcional) - Filtrar por cidade
UserId (Guid, opcional) - Filtrar por usuário
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: SearchRequestsResponse (lista paginada de solicitações)

Descrição:

Retorna uma lista paginada de solicitações conforme os filtros aplicados

RequestItems (Itens de Solicitação)

Commands (Comandos)

1. Adicionar Item à Solicitação (AddRequestItem)

Contrato: AddRequestItemCommand

Campos Necessários:

RequestId (Guid, obrigatório) - Identificador da solicitação (JsonIgnore)
ProfessionalUserId (Guid, opcional) - Identificador do profissional (para solicitação direcionada)
JobTaskId (Guid, obrigatório) - Identificador da tarefa de trabalho
CityId (Guid, obrigatório) - Identificador da cidade
Address (Address, obrigatório) - Endereço completo do serviço
Street (string) - Rua
Number (string) - Número
Complement (string, opcional) - Complemento
City (string) - Cidade
Neighborhood (string) - Bairro
State (string) - Estado
PostalCode (string) - CEP
Attributes (Dictionary, obrigatório) - Atributos da tarefa (ex: quantidade de horas)
StartDt (DateTime, padrão: DateTime.Now) - Data e hora de início
Parameters (Dictionary, padrão: vazio) - Parâmetros customizados
Observation (string, opcional) - Observações adicionais
Author (string, opcional) - Autor da operação

Validações:

RequestId: Não pode ser vazio; Solicitação deve existir
JobTaskId: Não pode ser vazio; Tarefa deve existir
CityId: Não pode ser vazio; Cidade deve existir
Address: Deve ser válido conforme validações do Value Object Address
Street: Não pode ser vazio; Tamanho máximo: 150 caracteres
Number: Não pode ser vazio; Tamanho máximo: 10 caracteres
City: Não pode ser vazio; Tamanho máximo: 100 caracteres
Neighborhood: Não pode ser vazio; Tamanho máximo: 100 caracteres
State: Não pode ser vazio; Tamanho máximo: 2 caracteres; Deve ser um estado válido brasileiro (UF) - Estados aceitos: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO
PostalCode: Não pode ser vazio; Deve corresponder ao padrão XXXXX-XXX (formato brasileiro)
Complement: Tamanho máximo: 100 caracteres (opcional)
Attributes: Não pode ser vazio; Deve conter os atributos necessários para a tarefa

Retorno: AddRequestItemResponse

Eventos de Domínio:

RequestItemAddedEvent - Disparado quando um item é adicionado

Regras de Negócio:

Atualiza os preços da solicitação
Calcula preços base e preços para profissionais
Se ProfessionalUserId for fornecido, cria solicitação direcionada

2. Remover Item da Solicitação (RemoveRequestItem)

Contrato: RemoveRequestItemCommand

Campos Necessários:

RequestId (Guid, obrigatório) - Identificador da solicitação
RequestItemId (Guid, obrigatório) - Identificador do item

Validações:

Item deve existir para a solicitação

Retorno: Void

Eventos de Domínio:

RequestItemRemovedEvent - Disparado quando um item é removido

Regras de Negócio:

Atualiza os preços da solicitação
Remove todas as respostas associadas ao item

Queries (Consultas)

1. Buscar Itens da Solicitação (GetRequestItems)

Contrato: GetRequestItemsQuery

Parâmetros:

RequestId (Guid, obrigatório) - Identificador da solicitação

Retorno: GetRequestItemsResponse (lista de itens)

Descrição:

Retorna todos os itens de uma solicitação
Inclui detalhes de preços, endereço e atributos

RequestItemResponses (Respostas de Itens)

Commands (Comandos)

1. Criar Resposta para Item (CreateRequestItemResponse)

Contrato: CreateRequestItemResponseCommand

Campos Necessários:

RequestId (Guid, obrigatório) - Identificador da solicitação (JsonIgnore)
RequestItemId (Guid, obrigatório) - Identificador do item (JsonIgnore)
ProfessionalUserId (Guid, obrigatório) - Identificador do profissional
Attributes (Dictionary, padrão: vazio) - Atributos da resposta (ex: preços propostos)
Author (string, opcional) - Autor da operação
Observation (string, opcional) - Observações adicionais

Validações:

RequestId: Não pode ser vazio; Solicitação deve existir
RequestItemId: Não pode ser vazio; Item deve existir
ProfessionalUserId: Não pode ser vazio; Profissional deve existir
Profissional deve ter as habilidades necessárias para o item

Retorno: CreateRequestItemResponseResponse

Eventos de Domínio:

RequestItemResponseCreatedEvent - Disparado quando uma resposta é criada

Regras de Negócio:

Profissional responde propondo realizar o serviço
Não pode criar resposta duplicada
Solicitação deve estar processada (Processed)
Resposta é criada com status Pending

2. Aceitar Resposta (AcceptRequestItemResponse)

Contrato: AcceptRequestItemResponseCommand

Campos Necessários:

RequestId (Guid, obrigatório) - Identificador da solicitação
RequestItemId (Guid, obrigatório) - Identificador do item
ResponseId (Guid, obrigatório) - Identificador da resposta
Author (string, opcional) - Autor da operação

Validações:

Resposta deve existir para o item
Resposta deve estar com status Pending

Retorno: Void

Eventos de Domínio:

RequestItemResponseAcceptedEvent - Disparado quando uma resposta é aceita

Regras de Negócio:

Aceita a resposta e vincula o profissional ao item
Altera status da resposta para Accepted
Rejeita automaticamente todas as outras respostas pendentes para o mesmo item
Cria um OrderItem automaticamente

3. Rejeitar Resposta (RejectRequestItemResponse)

Contrato: RejectRequestItemResponseCommand

Campos Necessários:

RequestId (Guid, obrigatório) - Identificador da solicitação
RequestItemId (Guid, obrigatório) - Identificador do item
ResponseId (Guid, obrigatório) - Identificador da resposta
Reason (string, opcional) - Motivo da rejeição
Author (string, opcional) - Autor da operação

Validações:

Resposta deve existir para o item
Resposta deve estar com status Pending

Retorno: Void

Eventos de Domínio:

RequestItemResponseRejectedEvent - Disparado quando uma resposta é rejeitada

Regras de Negócio:

Rejeita a resposta
Altera status da resposta para Rejected

Queries (Consultas)

1. Buscar Respostas de Item (GetRequestItemResponses)

Contrato: GetRequestItemResponsesQuery

Parâmetros:

RequestId (Guid, obrigatório) - Identificador da solicitação
RequestItemId (Guid, obrigatório) - Identificador do item

Retorno: GetRequestItemResponsesResponse (lista de respostas)

Descrição:

Retorna todas as respostas de profissionais para um item específico
Inclui detalhes do profissional e atributos propostos

2. Buscar Resposta por ID (GetRequestItemResponseById)

Contrato: GetRequestItemResponseByIdQuery

Parâmetros:

RequestId (Guid, obrigatório) - Identificador da solicitação
RequestItemId (Guid, obrigatório) - Identificador do item
ResponseId (Guid, obrigatório) - Identificador da resposta

Retorno: GetRequestItemResponseByIdResponse

Descrição:

Retorna uma resposta específica com todos os detalhes

Eventos de Domínio

Request

RequestCreatedEvent - Disparado quando uma solicitação é criada
RequestProcessedEvent - Disparado quando uma solicitação é processada
RequestItemAddedEvent - Disparado quando um item é adicionado
RequestItemRemovedEvent - Disparado quando um item é removido

RequestItemResponses

RequestItemResponseCreatedEvent - Disparado quando uma resposta é criada
RequestItemResponseAcceptedEvent - Disparado quando uma resposta é aceita
RequestItemResponseRejectedEvent - Disparado quando uma resposta é rejeitada

Regras Gerais de Negócio

Solicitação (Request)

Solicitação começa com status Pending
Deve ser processada antes que profissionais possam ver e responder
Origin identifica a fonte da solicitação (ex: "Mobile App", "Website")
Preços são calculados automaticamente com base nos itens
Pode criar usuário automaticamente se não fornecido

Itens de Solicitação (RequestItems)

Cada item representa um serviço específico a ser realizado
Atributos variam conforme a tarefa (ex: horas, metros quadrados)
Endereço é obrigatório para cada item
Pode ser direcionado a um profissional específico
Preços são calculados com base na tarefa e atributos

Respostas de Itens (RequestItemResponses)

Apenas profissionais com habilidades compatíveis podem responder
Solicitação deve estar processada para receber respostas
Profissional propõe valores nos atributos da resposta
Aceitar uma resposta cria automaticamente um OrderItem
Aceitar uma resposta rejeita automaticamente as demais
Status possíveis: Pending, Accepted, Rejected

Fluxo Completo

Fluxo de Criação e Processamento:

Criar Solicitação → CreateRequestWithItems (usuário cria solicitação com itens)
Processar Solicitação → ProcessRequest (solicitação é validada e liberada para profissionais)
Profissionais Respondem → CreateRequestItemResponse (profissionais propõem realizar os serviços)
Usuário Aceita/Rejeita → AcceptRequestItemResponse ou RejectRequestItemResponse
Criação Automática de Pedido → Ao aceitar uma resposta, um OrderItem é criado automaticamente

Padrões Utilizados

CQRS (Command Query Responsibility Segregation)

Commands: Operações que modificam o estado (Create, Add, Remove, Accept, Reject, Process)
Queries: Operações que apenas consultam dados (Get, Search)

DDD (Domain-Driven Design)

Agregados: Request é o agregado raiz
Entidades: RequestItem, RequestItemResponse
Value Objects: RequestDetails, Address, Attributes
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

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
Origin máximo: 100 caracteres
Observation máximo: 500 caracteres
RequestDetails armazena preços calculados: BasePrice, FinalPrice, PriceForProfessionals
Attributes são dicionários flexíveis que variam por tarefa