ZepiGit/league-api-engineering

Ingeniería de API de League of Legends

Selecciona exactamente un modo primario. Para una solicitud mixta, indica el modo dominante y el entregable secundario antes de proceder.

Modo	Uso para	Resultado requerido
implement	Agregar o modificar una integración de datos	Decisión de fuente → contrato de adaptador → fixtures/pruebas sanitizadas → plan de implementación o código → puertas de control
audit	Evaluar una integración existente	Inventario → etiquetas de evidencia → matriz de riesgos → correcciones priorizadas y específicas por fuente
debug	Una integración fallida o engañosa	Reproducción → clase de fallo → inspección de transporte/esquema/caché/fallback → prueba de corrección
research	Elegir una fuente o verificar hechos actuales	Mapa de evidencia fechado → evaluación de fuente → decisión
policy	Determinar si el uso de datos o el comportamiento del producto está permitido	Revisión de producto/datos → puerta de política → decisión de permitido, restringido o bloqueado

Puertas de control no negociables

Rechaza un diseño en lugar de sortear una puerta fallida:

• Secretos y privacidad: nunca incrustar, persistir o registrar claves de Riot, credenciales de LCU, tokens de portador, cookies, PII o historiales reales de jugadores.
• Seguridad del cliente local: sin inyección, hooks, acceso a memoria de procesos, escaneo de memoria, evasión de anti-trampas, extracción de estado oculto o afirmaciones de control exclusivo en pantalla completa. La relajación del certificado de bucle invertido se limita a un cliente explícitamente vinculado a 127.0.0.1 o localhost; nunca es reutilizable para HTTPS remoto.
• Autoridad y términos: no representes un endpoint o proveedor no documentado como oficialmente compatible. Verifica los términos aplicables, atribución, redistribución, autenticación y condiciones de límite de velocidad antes de su uso.
• Veracidad del fallback: un fallback debe preservar las semánticas de población, alcance, frescura, parche, configuración regional, cola y procedencia. Los datos materialmente diferentes son un resultado separado, no un sustituto silencioso.
• Solicitudes no compatibles: no inventes estimaciones de MMR/ELO, infieras estado oculto o expongas información de jugador no disponible. Devuelve policy_blocked o unsupported_context con la restricción.

Flujo de trabajo de decisión de fuente

1. Clasifica los datos solicitados: sesión local, partida activa, datos estáticos/versionados, datos remotos de cuenta/partida/clasificación, datos de tendencias agregadas o estado oculto/no compatible.
2. Comienza con source-decision-tree.md; elige candidatos según autoridad, acceso, enrutamiento, frescura, estabilidad, cobertura de parches, latencia, términos, privacidad, atribución, límites de velocidad y comportamiento ante fallos.
3. Aplica las puertas de control estrictas antes de puntuar. Se rechaza una fuente que necesite una clave de producción incrustada, acceso local inseguro, datos prohibidos, redistribución no revisada o un fallback incompatible.
4. Registra una clase de evidencia para cada afirmación material:
   • verified-current: directamente respaldado por una fuente autorizada fechada u observación reproducible actual;
   • observed-undocumented: comportamiento reproducido no garantizado por una autoridad;
   • historical: previamente documentado u observado, no se puede asumir como actual;
   • inference: una conclusión razonada que necesita validación antes de producción.
5. Escribe o actualiza un contrato de adaptador usando adapter-contract.md, luego adopta controles de caché/fallback, pruebas y canaries.

Vocabulario de fallos

Usa una clase de error primaria y conserva los diagnósticos sanitizados sin procesar por separado: offline, unauthorized, rate_limited, not_found, no_data, unsupported_context, transport, http_status, parse, schema_drift o policy_blocked.

Nunca reintentes ciegamente unauthorized, policy_blocked, parse o schema_drift. Consulta caching-and-fallbacks.md.

Contrato de salida de auditoría

Una auditoría emite un artefacto fechado con:

1. alcance, clases de datos e inventario de adaptadores;
2. mapa de fuentes/endpoints con autoridad, estabilidad, clase de evidencia y fecha de revisión de términos;
3. hallazgos de credenciales, privacidad, acceso local, enrutamiento, versionado y atribución;
4. hallazgos de compatibilidad de caché, sin datos, reintento, deriva y fallback;
5. una matriz de riesgos: severidad, probabilidad, comportamiento afectado, evidencia y remediación concreta;
6. correcciones priorizadas, elementos bloqueados y criterios de verificación.

No etiquetes una suposición como verificada. No llames segura a una fuente solo porque funciona una vez.

Divulgación progresiva

• Opciones de fuentes oficiales y locales: riot-web-apis.md, lcu.md, live-client-data.md, data-dragon.md, communitydragon.md.
• Fuentes externas y política de producto: third-party-providers.md, policy-and-product-gates.md.
• Controles de ingeniería: adapter-contract.md, caching-and-fallbacks.md, testing-and-canaries.md.
• Ejemplo acotado opcional: case-study-lolcompanion.md.

Ejecuta python scripts/validate.py . desde la raíz del paquete antes de publicar cuando el validador esté presente.