Pular para conteúdo

Skills

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

Índice

Skills (Habilidades)

Visão Geral

O agregado Skill representa as habilidades/competências disponíveis no sistema. As habilidades podem ser associadas a: - Tarefas de trabalho (JobTaskSkills) - Preferências de usuários (UserFavoriteSkills) - Habilidades de profissionais (ProfessionalUserSkills)

Commands (Comandos)

1. Criação de Habilidade (CreateSkill)

Contrato: CreateSkillCommand

Campos Necessários:

  • Name (string, obrigatório) - Nome da habilidade
  • Details (string, obrigatório) - Descrição detalhada da habilidade
  • IsActive (bool, obrigatório) - Indica se a habilidade está ativa
  • Observation (string, opcional) - Observações adicionais
  • Author (string, opcional) - Autor da operação

Validações:

  • Name: Não pode ser vazio; Tamanho máximo: 99 caracteres
  • Details: Não pode ser vazio; Tamanho máximo: 500 caracteres
  • IsActive: Não pode ser vazio
  • Observation: Tamanho máximo: 500 caracteres quando fornecido

Retorno: CreateSkillResponse - Id (Guid) - Identificador da habilidade criada

Handler: CreateSkillHandler

Eventos de Domínio:

  • SkillCreatedEvent - Disparado quando uma habilidade é criada (se implementado)

Regras de Negócio:

  • A habilidade é criada com status ativo ou inativo conforme especificado
  • Nome e detalhes são campos obrigatórios e devem ser descritivos
  • Habilidades inativas não aparecem em pesquisas padrão
  • O campo Observation permite contexto adicional sobre a habilidade

Exemplo de Uso:

{
  "name": "Instalação Elétrica Residencial",
  "details": "Capacidade de realizar instalações elétricas em residências, incluindo quadros de distribuição, circuitos e pontos de luz",
  "isActive": true,
  "observation": "Requer certificação NR-10",
  "author": "admin@sistema.com"
}

Exemplo de Resposta:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

2. Exclusão de Habilidade (DeleteSkill)

Contrato: DeleteSkillCommand

Campos Necessários:

  • Id (Guid, obrigatório) - Identificador da habilidade

Validações:

  • Id: Não pode ser vazio

Retorno: Void

Handler: DeleteSkillHandler

Regras de Negócio:

  • A habilidade deve existir no sistema
  • Verifica se há dependências antes de excluir:
  • JobTaskSkills associadas
  • UserFavoriteSkills associadas
  • ProfessionalUserSkills associadas
  • Se houver dependências, a exclusão pode ser impedida ou realizar exclusão em cascata

Exemplo de Uso:

DELETE /api/skills/{id}

Queries (Consultas)

1. Buscar Habilidade por ID (GetSkillById)

Contrato: GetSkillByIdQuery

Campos Necessários:

  • Id (Guid, obrigatório) - Identificador da habilidade

Retorno: GetSkillByIdResponse - Id (Guid) - Identificador da habilidade - Name (string) - Nome da habilidade - Details (string) - Descrição detalhada - IsActive (bool) - Status ativo/inativo - Observation (string) - Observações - CreatedAt (DateTime) - Data de criação - UpdatedAt (DateTime?) - Data da última atualização - AuthorCreated (string) - Autor da criação - AuthorUpdated (string) - Autor da última atualização

Handler: GetSkillByIdHandler

Mapper: GetSkillByIdMapper

Descrição:

  • Retorna todos os dados da habilidade especificada
  • Inclui informações de auditoria (datas e autores)
  • Se a habilidade não existir, lança exceção NotFound

Regras de Negócio:

  • Retorna todos os dados da habilidade
  • Inclui informações de auditoria (datas e autores)
  • Se a habilidade não existir, lança exceção NotFound

Exemplo de Resposta:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Instalação Elétrica Residencial",
  "details": "Capacidade de realizar instalações elétricas em residências, incluindo quadros de distribuição, circuitos e pontos de luz",
  "isActive": true,
  "observation": "Requer certificação NR-10",
  "createdAt": "2025-01-08T10:30:00Z",
  "updatedAt": "2025-01-08T15:45:00Z",
  "authorCreated": "admin@sistema.com",
  "authorUpdated": "admin@sistema.com"
}

2. Pesquisar Habilidades (SearchSkills)

Contrato: SearchSkillsQuery

Campos Opcionais: - Name (string, opcional) - Filtrar por nome da habilidade (busca parcial) - UserId (Guid?, opcional) - Filtrar habilidades favoritas de um usuário específico - ProfessionalUserId (Guid?, opcional) - Filtrar habilidades de um profissional específico - JobTaskId (Guid?, opcional) - Filtrar habilidades associadas a uma tarefa específica

Retorno: SearchSkillsResponse - Lista de habilidades que atendem aos critérios de filtro - Cada item contém os dados completos da habilidade Descrição:

  • Retorna uma lista de habilidades conforme os filtros aplicados
  • Permite busca por nome, usuário, profissional e tarefa

Handler: SearchSkillsHandler

Mapper: SearchSkillsMapper

Regras de Negócio:

  • Quando nenhum filtro é fornecido, retorna todas as habilidades ativas
  • Name: Realiza busca case-insensitive e parcial (LIKE)
  • UserId: Retorna apenas habilidades marcadas como favoritas pelo usuário
  • ProfessionalUserId: Retorna habilidades cadastradas no perfil do profissional
  • JobTaskId: Retorna habilidades requeridas para uma tarefa específica
  • Os filtros podem ser combinados para buscas mais específicas

Exemplo de Uso:

// Buscar habilidades de um profissional específico
{
  "professionalUserId": "123e4567-e89b-12d3-a456-426614174000"
}

// Buscar habilidades por nome
{
  "name": "elétrica"
}

// Buscar habilidades favoritas de um usuário
{
  "userId": "987fcdeb-51a2-43f9-9876-543210fedcba"
}

Exemplo de Resposta:

{
  "skills": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Instalação Elétrica Residencial",
      "details": "Capacidade de realizar instalações elétricas em residências",
      "isActive": true,
      "observation": "Requer certificação NR-10",
      "createdAt": "2025-01-08T10:30:00Z"
    },
    {
      "id": "456e7890-e12b-34d5-b678-901234567890",
      "name": "Manutenção Elétrica Preventiva",
      "details": "Inspeção e manutenção preventiva de instalações elétricas",
      "isActive": true,
      "observation": null,
      "createdAt": "2025-01-08T11:00:00Z"
    }
  ]
}

Conceitos de DDD e CQRS

Domain-Driven Design (DDD)

Aggregate Root: - Skill é um agregado raiz independente - Mantém consistência interna de suas propriedades - Possui coleções de entidades relacionadas (JobTaskSkills, UserFavoriteSkills, ProfessionalUserSkills)

Value Objects: - Author - Representa o autor da operação (criação/atualização) - Observation - Observações sobre a habilidade

Domain Events: - Eventos podem ser disparados quando uma habilidade é criada ou modificada - Permite reações em outros contextos delimitados

Invariantes: - Nome não pode exceder 99 caracteres - Detalhes não podem exceder 500 caracteres - Nome e detalhes são obrigatórios

CQRS (Command Query Responsibility Segregation)

Commands (Comandos): - CreateSkillCommand - Cria uma nova habilidade - DeleteSkillCommand - Remove uma habilidade existente - Todos os comandos passam por validação (FluentValidation) - Cada comando tem um handler dedicado que executa a lógica de negócio

Queries (Consultas): - GetSkillByIdQuery - Busca uma habilidade específica - SearchSkillsQuery - Pesquisa habilidades com filtros - Queries são otimizadas para leitura - Não modificam o estado do sistema - Cada query tem um handler e mapper dedicados

Validators: - CreateSkillValidator - Valida dados de criação - DeleteSkillValidator - Valida dados de exclusão - Utilizam FluentValidation para regras declarativas

Relacionamentos

JobTaskSkill

Representa a associação entre uma habilidade e uma tarefa de trabalho. - Uma tarefa pode requerer múltiplas habilidades - Cada associação possui um score (nível de importância/proficiência)

UserFavoriteSkill

Representa habilidades marcadas como favoritas por usuários. - Usuários podem indicar preferências de serviços - Facilita matchmaking entre usuários e profissionais

ProfessionalUserSkill

Representa habilidades que um profissional possui. - Define as competências do profissional - Pode incluir nível de proficiência - Usado para matching de serviços

Observações Importantes

  1. Auditoria: Todas as operações registram autor e data (campos AuthorCreated, AuthorUpdated, CreatedAt, UpdatedAt)
  2. Validação em Camadas:
  3. Validação de aplicação (FluentValidation nos validators)
  4. Validação de domínio (invariantes na entidade Skill)
  5. Soft Delete: Considere usar inativação em vez de exclusão física para manter histórico
  6. Nomenclatura: Use nomes descritivos e padronizados para facilitar buscas
  7. Detalhes: O campo Details deve conter informação suficiente para usuários entenderem o escopo da habilidade