Pular para conteúdo

Serviço de Hierarquia de Itens Pedagógicos

Este documento descreve em detalhes o Serviço de Hierarquia de Itens Pedagógicos do AT Learning Gap Engine, incluindo sua API, parâmetros, exemplos de uso e casos de teste.

Visão Geral

O Serviço de Hierarquia de Itens Pedagógicos é responsável por analisar o desempenho do estudante em diferentes tópicos e identificar áreas de melhoria prioritárias. O serviço utiliza um algoritmo sofisticado para calcular pontuações que representam a prioridade de cada assunto para recomendações personalizadas.

Fluxo de Processamento

O serviço segue o seguinte fluxo de processamento:

  1. Recebe uma mensagem com dados de desempenho do estudante
  2. Extrai métricas de origem e questões respondidas
  3. Analisa o desempenho do estudante usando o TopicAnalysisService
  4. Identifica os principais problemas por grupo pedagógico
  5. Gera uma hierarquia de itens pedagógicos ordenados por prioridade
  6. Retorna a hierarquia como resposta

API do Serviço

Endpoint

O serviço é acessado através da fila SQS, cujo nome é definido pela variável de ambiente SQS_QUEUE_ITEM_HIERARCHY_REQUEST. A comunicação segue o padrão Request-Reply, exigindo que a mensagem de requisição contenha o campo callbackQueueArn para o envio da resposta.

Formato da Requisição

{
  "contextId": "contexto-teste-123",
  "originMetrics": [
    {
      "pedagogicalTargetSegment": {
        "type": "SUBJECT",
        "id": 1001,
        "externalId": "SUB-1001",
        "title": "Álgebra"
      },
      "totalAnswers": 50,
      "correctAnswers": 30,
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      }
    },
    {
      "pedagogicalTargetSegment": {
        "type": "SUBJECT",
        "id": 1002,
        "externalId": "SUB-1002",
        "title": "Geometria"
      },
      "totalAnswers": 40,
      "correctAnswers": 15,
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      }
    }
  ],
  "config": {
    "pedagogicalTargetSegment": {
      "type": "SUBJECT",
      "itemsCount": 3,
      "fallbacks": ["SUB_SUBJECT"]
    },
    "pedagogicalTarget": "SCHOOL_SUBJECT",
    "maxSubjectsCount": 5,
    "priorityValues": {
      "difficulty": {
        "EASY": 1,
        "MEDIUM": 2,
        "HARD": 3
      }
    }
  },
  "list": [
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      },
      "questions": [
        {
          "questionId": 5001,
          "questionType": "MULTIPLE_CHOICE",
          "difficulty": "EASY",
          "evaluation": 80,
          "pedagogicalTargetSegments": [
            {
              "type": "SUBJECT",
              "id": 1001,
              "externalId": "SUB-1001",
              "title": "Álgebra"
            }
          ]
        },
        {
          "questionId": 5002,
          "questionType": "MULTIPLE_CHOICE",
          "difficulty": "MEDIUM",
          "evaluation": 65,
          "pedagogicalTargetSegments": [
            {
              "type": "SUBJECT",
              "id": 1001,
              "externalId": "SUB-1001",
              "title": "Álgebra"
            }
          ]
        }
      ]
    }
  ]
}

Atributos da Mensagem (Message Attributes)

Além do corpo da mensagem, a requisição deve conter os seguintes atributos de mensagem SQS:

Atributo Tipo Descrição Obrigatório
queue_arn_callback String ARN da fila SQS para onde a resposta deve ser enviada. Sim
correlation_id String ID de correlação para rastrear a requisição e a resposta. Não

Descrição dos Campos da Requisição

Campos Principais

Campo Tipo Descrição Obrigatório
contextId string Identificador único do contexto (estudante, turma, etc.) Sim
originMetrics array Lista de métricas de desempenho para cada segmento Sim
config object Configurações para o processo de hierarquização Sim
list array Lista de alvos pedagógicos com suas questões Sim

Campos de originMetrics

Campo Tipo Descrição Obrigatório
pedagogicalTargetSegment object Segmento de alvo pedagógico (assunto, subassunto, etc.) Sim
totalAnswers number Número total de respostas para este segmento Sim
correctAnswers number Número de respostas corretas para este segmento Sim
pedagogicalTarget object Alvo pedagógico (disciplina, etc.) Não

Campos de config

Campo Tipo Descrição Obrigatório
pedagogicalTargetSegment object Configuração do segmento de alvo pedagógico Sim
pedagogicalTarget string Tipo de alvo pedagógico a ser usado Sim
maxSubjectsCount number Número máximo de assuntos a serem incluídos Não
priorityValues object Valores de prioridade para diferentes atributos Não

Formato da Resposta

{
  "contextId": "contexto-teste-123",
  "list": [
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      },
      "pedagogicalTargetSegments": [
        {
          "type": "SUBJECT",
          "id": 1002,
          "externalId": "SUB-1002",
          "title": "Geometria"
        },
        {
          "type": "SUBJECT",
          "id": 1001,
          "externalId": "SUB-1001",
          "title": "Álgebra"
        }
      ],
      "score": 999.99
    }
  ]
}

Descrição dos Campos da Resposta

Campo Tipo Descrição
contextId string Identificador único do contexto (mesmo da requisição)
list array Lista de itens de hierarquia
pedagogicalTarget object Alvo pedagógico (disciplina, etc.)
pedagogicalTargetSegments array Lista de segmentos de alvo pedagógico ordenados por prioridade
score number Pontuação do alvo pedagógico (0-1000, onde valores mais altos indicam maior prioridade)

Exemplos de Uso

Exemplo 1: Hierarquização de Assuntos de Matemática

Requisição

{
  "contextId": "estudante-123",
  "originMetrics": [
    {
      "pedagogicalTargetSegment": {
        "type": "SUBJECT",
        "id": 1001,
        "externalId": "SUB-1001",
        "title": "Álgebra"
      },
      "totalAnswers": 50,
      "correctAnswers": 30,
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      }
    },
    {
      "pedagogicalTargetSegment": {
        "type": "SUBJECT",
        "id": 1002,
        "externalId": "SUB-1002",
        "title": "Geometria"
      },
      "totalAnswers": 40,
      "correctAnswers": 15,
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      }
    },
    {
      "pedagogicalTargetSegment": {
        "type": "SUBJECT",
        "id": 1003,
        "externalId": "SUB-1003",
        "title": "Trigonometria"
      },
      "totalAnswers": 30,
      "correctAnswers": 25,
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      }
    }
  ],
  "config": {
    "pedagogicalTargetSegment": {
      "type": "SUBJECT",
      "itemsCount": 2,
      "fallbacks": []
    },
    "pedagogicalTarget": "SCHOOL_SUBJECT",
    "maxSubjectsCount": 3
  },
  "list": [
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      },
      "questions": [
        {
          "questionId": 5001,
          "questionType": "MULTIPLE_CHOICE",
          "difficulty": "EASY",
          "evaluation": 80,
          "pedagogicalTargetSegments": [
            {
              "type": "SUBJECT",
              "id": 1001,
              "externalId": "SUB-1001",
              "title": "Álgebra"
            }
          ]
        },
        {
          "questionId": 5002,
          "questionType": "MULTIPLE_CHOICE",
          "difficulty": "MEDIUM",
          "evaluation": 65,
          "pedagogicalTargetSegments": [
            {
              "type": "SUBJECT",
              "id": 1001,
              "externalId": "SUB-1001",
              "title": "Álgebra"
            }
          ]
        },
        {
          "questionId": 5003,
          "questionType": "TRUE_FALSE",
          "difficulty": "HARD",
          "evaluation": 90,
          "pedagogicalTargetSegments": [
            {
              "type": "SUBJECT",
              "id": 1002,
              "externalId": "SUB-1002",
              "title": "Geometria"
            }
          ]
        }
      ]
    }
  ]
}

Resposta

{
  "contextId": "estudante-123",
  "list": [
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      },
      "pedagogicalTargetSegments": [
        {
          "type": "SUBJECT",
          "id": 1002,
          "externalId": "SUB-1002",
          "title": "Geometria"
        },
        {
          "type": "SUBJECT",
          "id": 1001,
          "externalId": "SUB-1001",
          "title": "Álgebra"
        }
      ],
      "score": 999.99
    }
  ]
}

Exemplo 2: Hierarquização com Múltiplas Disciplinas

Requisição

{
  "contextId": "estudante-456",
  "originMetrics": [
    {
      "pedagogicalTargetSegment": {
        "type": "SUBJECT",
        "id": 1001,
        "externalId": "SUB-1001",
        "title": "Álgebra"
      },
      "totalAnswers": 50,
      "correctAnswers": 30,
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      }
    },
    {
      "pedagogicalTargetSegment": {
        "type": "SUBJECT",
        "id": 2001,
        "externalId": "SUB-2001",
        "title": "Mecânica"
      },
      "totalAnswers": 40,
      "correctAnswers": 15,
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 102,
        "externalId": "2",
        "title": "Física"
      }
    }
  ],
  "config": {
    "pedagogicalTargetSegment": {
      "type": "SUBJECT",
      "itemsCount": 1,
      "fallbacks": []
    },
    "pedagogicalTarget": "SCHOOL_SUBJECT",
    "maxSubjectsCount": 2
  },
  "list": [
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      },
      "questions": [
        {
          "questionId": 5001,
          "questionType": "MULTIPLE_CHOICE",
          "difficulty": "EASY",
          "evaluation": 80,
          "pedagogicalTargetSegments": [
            {
              "type": "SUBJECT",
              "id": 1001,
              "externalId": "SUB-1001",
              "title": "Álgebra"
            }
          ]
        }
      ]
    },
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 102,
        "externalId": "2",
        "title": "Física"
      },
      "questions": [
        {
          "questionId": 6001,
          "questionType": "MULTIPLE_CHOICE",
          "difficulty": "MEDIUM",
          "evaluation": 70,
          "pedagogicalTargetSegments": [
            {
              "type": "SUBJECT",
              "id": 2001,
              "externalId": "SUB-2001",
              "title": "Mecânica"
            }
          ]
        }
      ]
    }
  ]
}

Resposta

{
  "contextId": "estudante-456",
  "list": [
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 102,
        "externalId": "2",
        "title": "Física"
      },
      "pedagogicalTargetSegments": [
        {
          "type": "SUBJECT",
          "id": 2001,
          "externalId": "SUB-2001",
          "title": "Mecânica"
        }
      ],
      "score": 999.99
    },
    {
      "pedagogicalTarget": {
        "type": "SCHOOL_SUBJECT",
        "id": 101,
        "externalId": "1",
        "title": "Matemática"
      },
      "pedagogicalTargetSegments": [
        {
          "type": "SUBJECT",
          "id": 1001,
          "externalId": "SUB-1001",
          "title": "Álgebra"
        }
      ],
      "score": 999.95
    }
  ]
}

Tratamento de Erros

Erros de Validação

Se a requisição não contiver os campos obrigatórios ou se os campos tiverem valores inválidos, o serviço retornará um erro de validação.

Erros de Processamento

Se ocorrer um erro durante o processamento da requisição, o serviço registrará o erro nos logs e rejeitará a mensagem.

Considerações de Performance

  • O serviço utiliza cache para melhorar a performance em requisições frequentes
  • O processamento é otimizado para lidar com grandes volumes de dados
  • Os logs são estruturados em formato JSON para facilitar a análise

Integração com Outros Serviços

O Serviço de Hierarquia de Itens Pedagógicos pode ser integrado com:

  • Serviço de Recomendação de Questões: Para recomendar questões com base na hierarquia gerada
  • Sistemas de Gestão de Aprendizagem (LMS): Para obter dados de desempenho dos estudantes
  • Dashboards de Análise: Para visualizar as hierarquias geradas

Conclusão

O Serviço de Hierarquia de Itens Pedagógicos é uma ferramenta poderosa para personalizar o processo de aprendizagem, identificando com precisão as áreas que mais precisam de atenção. Ao combinar análise de desempenho, cálculos de prioridade e distribuição inteligente de questões, o serviço oferece recomendações altamente personalizadas que maximizam o potencial de aprendizagem de cada estudante.