Nota ponderada sobre total

Informe cada categoria com os pontos obtidos, os possíveis e o peso, e defina out_of (por exemplo 20 para uma nota clássica sobre 20). O motor normaliza cada linha a uma razão, faz a média ponderada dessas razões, multiplica pelo seu total e devolve mark, mark_display e o detalhamento por categoria.

O que significa uma pontuação ponderada sobre um total

A matemática é a mesma em todo lugar: cada categoria contribui com score dividido por max_score, essa razão é multiplicada pelo peso da categoria, esses produtos são somados, a soma é dividida pelo peso total e o resultado é multiplicado por out_of. Exemplo: tarefas oitenta e cinco de cem com peso trinta, parcial dezesseis de vinte com peso trinta, final quarenta e dois de cinquenta com peso quarenta, out_of vinte. Quem busca nota ponderada sobre um total, nota sobre 20 ou marca por categorias em escala fixa quer essa conversão como resultado principal, com uma string mark_display clara que pode colar em um relatório ou mensagem aos responsáveis. Como cada categoria é normalizada pelo próprio max_score, você pode misturar um quiz sobre dez com um projeto sobre cem sem forçar tudo a um único poço de pontos brutos.

Contrato de entrada, arredondamento e comportamento de erro

O label opcional nomeia a categoria no detalhamento. Os pesos não precisam somar cem: o motor renormaliza automaticamente, então você pode informar trinta, trinta, quarenta ou 0.3, 0.3, 0.4 com as mesmas razões e a mesma marca. Envie por POST um corpo JSON com dois campos obrigatórios. categories é um array não vazio de até cinquenta objetos; cada objeto deve incluir score (pontos finitos não negativos obtidos), max_score (pontos possíveis estritamente positivos) e weight (peso relativo estritamente positivo). Os aliases items, rows e components mapeiam para categories. out_of é o total-alvo estritamente positivo da marca combinada; aceitam-se os aliases total, scale e max_mark. decimals opcional é um inteiro de zero a seis inclusive e o padrão é dois; aceita-se o alias precision. Em caso de sucesso a resposta inclui mark (arredondado half-up para decimals), out_of, mark_display como 16.62 / 20, weighted_percent, weighted_ratio, total_weight, category_count, decimals, um array categories com ratio, weight_share e contribution_to_mark por linha, além de formula e method weighted_category_scale para clientes estáveis. Se faltarem categories ou out_of, houver arrays vazios, não objetos na lista, scores negativos, max_score ou weight não positivos, out_of não positivo ou decimals fora de zero a seis, a chamada falha com invalid_input e mensagens que nomeiam o campo; falhas de validação não são cobradas.

Onde uma API de marca sobre N ponderada agrega valor

Docentes que avaliam com instrumentos mistos mas reportam em escala institucional fixa precisam de um oráculo em que alunos, responsáveis e planilhas confiem. Tutores podem percorrer com o aprendiz cada contribuição de categoria sem inventar aritmética customizada a cada sessão. Validação falha não consome saldo. Escritórios de orientação perto das parciais respondem dezenas de vezes quanto isso vale sobre vinte após os pesos; um endpoint determinístico compartilhado elimina o desvio de bots do Discord e erros de calculadora manual. Como a implementação é parse de nível A puro, cada chamada bem-sucedida custa o preço base publicado US$ 0,002 sem tokens de modelo nem rede de saída. Mantenha as requisições pequenas, fixe mark e mark_display nos testes, e você obtém marcas escaladas reproduzíveis para demos de sala, workers na borda e calculadoras de plano de ensino sem montar infraestrutura própria de avaliação.