Dados para gráfico de progresso e marcos de metas

Informe o valor inicial, o valor mais recente, o alvo e os percentuais dos marcos que você deseja exibir. O resultado mostra o progresso real, uma posição limitada adequada ao gráfico, os marcos já atingidos, o próximo marco quando houver e uma sequência ordenada de pontos. O cálculo funciona tanto para metas crescentes quanto para metas que precisam diminuir, como defeitos, despesas ou tempo de resposta.

Defina a meta com um ponto inicial explícito

Um percentual de progresso útil exige três valores, e não apenas o valor atual e o alvo. O valor inicial define zero por cento, o alvo define cem por cento e o valor atual mostra a situação mais recente. Essa distinção é importante sempre que o trabalho começa em uma base diferente de zero. Por exemplo, ao elevar uma pontuação de 20 para 100, o meio do caminho está em 60; não se trata de sessenta por cento apenas porque a pontuação atual é 60. Envie esses valores como números e forneça pelo menos um percentual de marco entre zero e cem. Os marcos podem ser enviados em qualquer ordem, e percentuais repetidos são consolidados para que o gráfico receba uma série crescente e limpa. O alvo precisa ser diferente do início, pois um intervalo de comprimento zero não possui uma razão de progresso válida. Se os dois valores forem iguais, a capacidade retorna um erro de entrada tipado, em vez de infinito, um percentual arbitrário ou dados aparentemente corretos. Cada solicitação aceita até cem itens de marco, o que mantém a execução e a saída limitadas e ainda atende a planos bastante detalhados.

Interprete metas crescentes e decrescentes da mesma forma

A mesma fórmula atende às duas direções: o progresso corresponde à distância percorrida desde o início dividida pela distância total entre o início e o alvo. Se o alvo for maior, o resultado identifica uma meta crescente. Se for menor, identifica uma meta decrescente; assim, sair de 100 incidentes em direção ao alvo de 20 conta como avanço, e não como resultado negativo. O percentual de progresso retornado não é limitado de propósito. Um valor abaixo de zero revela uma piora além do ponto inicial, enquanto um valor acima de cem registra que a meta foi superada. Para apresentação, chart_progress_percentage e chart_percentage do ponto atual são limitados ao intervalo de zero a cem. A verificação dos marcos usa o progresso verdadeiro, sem esse limite. Cada marco normalizado inclui percentual, valor correspondente no trajeto e indicador de alcance. A saída também informa a quantidade e os percentuais dos marcos atingidos e apresenta o próximo marco quando ainda houver algum pendente. Depois que todos os marcos solicitados forem alcançados, esse campo opcional é omitido em vez de retornar null.

Use os pontos em gráficos e visões de status

O array chart_points fornece um ponto inicial ordenado, um ponto para cada marco normalizado e um ponto final de alvo. Cada registro contém tipo, percentual, valor e estado de alcance, podendo alimentar gráficos de linha, trilhas de progresso, marcadores cronológicos e resumos textuais acessíveis. O objeto current_point preserva o valor atual e o progresso real, além de fornecer a coordenada limitada para o gráfico. Essa separação permite posicionar um marcador com segurança na extremidade quando a meta está atrasada ou superada e, ao mesmo tempo, exibir o número verdadeiro em um rótulo ou dica. Use reached_milestone_percentages para selos, comemorações ou eventos de auditoria e next_milestone para explicar o próximo passo sem pesquisar novamente no array. O cálculo é determinístico e não usa rede, horário, estado armazenado nem valores aleatórios; entradas iguais sempre geram saídas iguais. Você pode executá-lo gratuitamente no navegador durante o planejamento ou chamar a API por US$ 0,002 por solicitação ao criar relatórios, atualizar painéis ou processar registros de metas em um fluxo automatizado.