ZepiGit/league-api-engineering

Engenharia de API de League of Legends

Selecione exatamente um modo primário. Para uma solicitação mista, declare o modo dominante e a entrega secundária antes de prosseguir.

Modo	Uso	Resultado exigido
implement	Adicionar ou alterar uma integração de dados	Decisão de fonte → contrato de adaptador → fixtures/testes sanitizados → plano de implementação ou código → gates
audit	Avaliar uma integração existente	Inventário → rótulos de evidência → matriz de risco → correções priorizadas e específicas por fonte
debug	Uma integração com falha ou enganosa	Reprodução → classe de falha → inspeção de transporte/esquema/cache/fallback → prova da correção
research	Escolher uma fonte ou verificar fatos atuais	Mapa de evidências datado → avaliação da fonte → decisão
policy	Verificar se o uso de dados ou o comportamento do produto é permitido	Revisão de produto/dados → gate de política → decisão de permitido, restrito ou bloqueado

Gates inegociáveis

Rejeite um design em vez de contornar um gate com falha:

• Segredos e privacidade: nunca incorpore, persista ou registre chaves da Riot, credenciais do LCU, tokens de portador, cookies, PII ou históricos reais de jogadores.
• Segurança do cliente local: sem injeção, hooks, acesso à memória de processo, varredura de memória, bypass de anti-cheat, extração de estado oculto ou alegações de controle exclusivo em tela cheia. A flexibilização de certificado de loopback é limitada a um cliente explicitamente vinculado a 127.0.0.1 ou localhost; nunca é reutilizável para HTTPS remoto.
• Autoridade e termos: não represente um endpoint ou provedor não documentado como oficialmente suportado. Verifique os termos aplicáveis, atribuição, redistribuição, autenticação e condições de limite de taxa antes do uso.
• Veracidade do fallback: um fallback deve preservar a semântica de população, escopo, atualização, patch, localidade, fila e proveniência. Dados materialmente diferentes são um resultado separado, não um substituto silencioso.
• Solicitações não suportadas: não invente estimativas de MMR/ELO, infira estado oculto ou exponha informações de jogador indisponíveis. Retorne policy_blocked ou unsupported_context com a restrição.

Fluxo de trabalho de decisão de fonte

1. Classifique os dados solicitados: sessão local, partida ativa, dados estáticos/versionados, dados remotos de conta/partida/ranqueadas, dados de tendência agregada ou estado oculto/não suportado.
2. Comece com source-decision-tree.md; escolha candidatos por autoridade, acesso, roteamento, atualização, estabilidade, cobertura de patch, latência, termos, privacidade, atribuição, limites de taxa e comportamento de falha.
3. Aplique os gates rígidos antes da pontuação. Uma fonte que precisa de uma chave de produção embutida, acesso local inseguro, dados proibidos, redistribuição não revisada ou um fallback incompatível é rejeitada.
4. Registre uma classe de evidência para cada afirmação material:
   • verified-current: diretamente suportado por uma fonte autoritativa datada ou observação reproduzível atual;
   • observed-undocumented: comportamento reproduzido não garantido por uma autoridade;
   • historical: anteriormente documentado ou observado, não seguro assumir como atual;
   • inference: uma conclusão fundamentada que precisa de validação antes da produção.
5. Escreva ou atualize um contrato de adaptador usando adapter-contract.md, em seguida, adote cache/fallback, testes e controles de canário.

Vocabulário de falha

Use uma classe de erro primária e mantenha diagnósticos sanitizados brutos separadamente: offline, unauthorized, rate_limited, not_found, no_data, unsupported_context, transport, http_status, parse, schema_drift ou policy_blocked.

Nunca tente novamente cegamente unauthorized, policy_blocked, parse ou schema_drift. Consulte caching-and-fallbacks.md.

Contrato de saída de auditoria

Uma auditoria emite um artefato datado com:

1. escopo, classes de dados e inventário de adaptadores;
2. mapa de fontes/endpoints com autoridade, estabilidade, classe de evidência e data de revisão de termos;
3. descobertas de credenciais, privacidade, acesso local, roteamento, versionamento e atribuição;
4. descobertas de cache, sem dados, repetição, drift e compatibilidade de fallback;
5. uma matriz de risco: gravidade, probabilidade, comportamento afetado, evidência e remediação concreta;
6. correções priorizadas, itens bloqueados e critérios de verificação.

Não rotule uma suposição como verificada. Não chame uma fonte de segura apenas porque funciona uma vez.

Divulgação progressiva

• Escolhas de fontes oficiais e locais: riot-web-apis.md, lcu.md, live-client-data.md, data-dragon.md, communitydragon.md.
• Fontes externas e política de produto: third-party-providers.md, policy-and-product-gates.md.
• Controles de engenharia: adapter-contract.md, caching-and-fallbacks.md, testing-and-canaries.md.
• Exemplo limitado opcional: case-study-lolcompanion.md.

Execute python scripts/validate.py . a partir da raiz do pacote antes de publicar quando o validador estiver presente.