Passo a passo de um leaderboard: eventos de pontuação, um sorted set derivado e rankings reconstruíveis

Objetivo

Classificar membros por pontuação, com consultas rápidas de top-N e de "minha posição", rankings por período e a possibilidade de reconstruí-los a partir do histórico de eventos quando o armazenamento do ranking for perdido.

Pré-requisitos

Uma definição da pontuação de cada ranking (melhor resultado individual, soma acumulada ou último valor), uma regra de desempate, os períodos dos rankings (geral, semanal, diário) e um caminho no servidor que produza as pontuações; os clientes nunca enviam pontuações diretamente.

Passos

1. Restrições: o envio de pontuação é autoritativo no servidor; as consultas de posição dominam a carga; o ranking de um período fecha em um horário fixo; o armazenamento do ranking é um cache e os eventos são a fonte da verdade.
2. Componentes: um gravador de eventos de pontuação; um atualizador que aplica os eventos a uma estrutura ordenada por ranking; uma API de consulta (top N, posição e pontuação de um membro, vizinhos em torno de uma posição); um rotacionador de períodos que abre e fecha rankings; um job de reconstrução.
3. Modelo de dados: score_event(id, board, member, value, occurred_at, source, idempotency_key unique); board(id, period_start, period_end, aggregation, tie_rule, closed_at); derivado: um sorted set por ranking, indexado por membro e contendo a pontuação agregada. A documentação do Redis descreve sorted sets com consulta de posição em O(log(N)) no número de elementos e cita leaderboards como um caso de uso.
4. Empates: um sorted set ordena pontuações iguais pela string do membro, o que é arbitrário para os usuários. Codifique a regra de desempate na pontuação (por exemplo, score * K - seconds_since_period_start para "quem chegou antes vence", com K maior que a duração do período em segundos e o resultado dentro da faixa de inteiros exatos de um double) ou resolva os empates na camada de consulta, apenas para a página visível.
5. Agregação: "melhor resultado" mantém o máximo, "soma" incrementa, "último valor" sobrescreve. Fixe uma só por ranking, pois uma reconstrução precisa reproduzir os mesmos valores a partir dos eventos.
6. Modos de falha: eventos duplicados após uma nova tentativa (a chave de idempotência única os rejeita antes de chegarem ao atualizador); perda do armazenamento do ranking (reconstruir a partir dos eventos, começando pelo período atual, já que os rankings são independentes); fronteira de período cruzada enquanto há eventos em trânsito (rotear por occurred_at, não pela ordem de chegada); ranking global com milhões de membros (top N e posição individual continuam baratos; faixas de percentil são aproximadas depois); trapaça (validar as pontuações no servidor conforme as regras e manter source para auditoria).
7. Medir: atraso entre o evento e sua visibilidade, latência das consultas de posição, tempo de reconstrução por ranking, eventos duplicados rejeitados, disputas por período.
8. Não são prioridade no início: rankings de amigos e regionais, snapshots históricos, envio em tempo real de mudanças de posição, lógica de recompensas.

Resultado esperado

As consultas de top-N e de posição individual são respondidas pela estrutura ordenada, um ranking perdido é reconstruído a partir dos eventos com resultados idênticos e um período fecha de forma determinística.

Limites e base de verificação

Projeto proposto, sem medições. Uma estrutura ordenada em memória cresce com o número de membros por ranking; o projeto pressupõe rankings limitados por período ou divididos em shards por região.