Carga GPS

TL;DR

Carga GPS centraliza la carga externa del plantel: importa datos desde CSV o Excel, calcula ACWR por jugador y métrica (distance, HSR, sprint, HMLD), predice la próxima sesión y compara contra la referencia de partido (%MD). Lo consumen el S&C, Sport Scientist y el HoP para decidir intensidad y rotaciones día a día. Para las definiciones de ACWR, HSR, HMLD, %MD, tiers T1/T2/T3 y EWMA, ver el glosario.

Para comercial

• Problema que resuelve: el cuerpo técnico recibe planillas GPS de Catapult, GPexe, STATSports u otros, y necesita interpretar rápidamente si un jugador está sobrecargado o sub-cargado respecto a su propia historia y al partido. CÉNIT unifica la importación, calcula ACWR multi-métrica y muestra %MD por jugador en una sola UI.
• Casos de uso típicos [NEEDS_USER: CASE_STUDY caso real de Nacional / Táchira]:
  • Lunes pos-partido: revisar quién pasó el 100 % de su referencia %MD en HMLD y planificar carga del martes.
  • Mié/jue: predecir la próxima sesión de MD-3 a partir del ACWR actual.
  • Viernes pre-partido: cruzar %MD acumulado de la semana con riesgo.
• Planes que lo incluyen: esencial, pro y enterprise tienen gps_acwr_basic, gps_csv_upload y gps_predictive_planning. El tab Comparaciones (feature flag season_comparisons) está declarado para pro/enterprise pero hoy se renderiza para todos — ver Limitaciones.
• Diferenciador: ACWR en m/día por las cuatro métricas relevantes (no solo distancia total), sistema de tiers T1/T2/T3 para %MD que no se rompe cuando faltan minutos, y predicción determinística sin IA — auditable.

Cómo lo usa el staff

Acceso y permisos

Roles con acceso a /dashboard/carga: hop, dir, sc, ss, rtp. Fisio/Médico/Nutri/Psi no tienen acceso a este módulo (consumen Riesgo y Fisio, que ya integran el ACWR).

Flujos paso a paso

Tabs del módulo (orden de izquierda a derecha):

1. Hoy — última sesión importada, top intensidad y tabla por jugador.
2. Predicción — multi-métrica con sub-tabs distance / HSR / sprint / HMLD. Distance se hidrata server-side; HSR, Sprint y HMLD se piden on-demand al abrir cada sub-tab.
3. Semana — tabla por jugador de la semana en curso (Dist / HSR / Sprint / HMLD) con toggle %MD vs Absoluto.
4. Comparaciones — comparativo semana actual vs semanas previas.
5. Subir — importadores CSV (Catapult / GPexe / formato genérico) y Tachira (Excel custom).

[NEEDS_USER: SCREENSHOT del tab Predicción con los cuatro sub-tabs]

Editor manual de minutos — cuando el proveedor GPS no reporta duration_min (caso documentado en Tachira), el staff lo carga a mano con updateMatchMinutes desde la grilla de partidos. Si los minutos quedan en NULL, ese partido cae al tier limited y participa solo del fallback de %MD.

Configuración relacionada

• organizations.md_max_window_days (Settings → Org): ventana de partidos considerada para la referencia %MD. Rango 90–360 días, default 90 (post migration-100). Orgs con valores legacy <90 se auto-bumpean a 90.
• organizations.acwr_method: rma (default) o ewma (opt-in, Williams 2017). Cambia cómo se ponderan los días dentro de la ventana, no los thresholds.
• organizations.microcycle_view: layout del microciclo usado en los agregados semanales.

FAQ / casos límite

• “El ACWR me cambió de un día para el otro sin sesión nueva” — el cálculo es rolling: cada día que pasa entra/sale del numerador y/o denominador. Es esperado.
• “%MD del jugador es NULL” — no tiene partidos suficientes en la ventana para llegar a tier T1/T2/T3 (cascada de fallback titular → rotativo → suplente → limited → null).
• “Player Load no aparece” — fue eliminado de la UI; HMLD lo reemplaza (migration-105). La columna player_load ya no existe en gps_player_data.

Cómo lo ve el jugador

Player surface: N/A en este módulo. El jugador no ve cifras de ACWR ni %MD directamente. Sí ve en /player/agenda el día del microciclo (MD-N), que se calcula con get_microcycle_day y depende del calendario de partidos cargado.

Datos y métricas

Fórmulas y cálculos

• ACWR (RMA, default): acute_7d = SUM(métrica últimos 7d) / 7 y chronic_28d = SUM(métrica últimos 28d) / 28, ambos en m/día (migration-095). Aplica a distance, HSR, sprint y HMLD. El ratio es adimensional y se interpreta igual que antes del cambio de unidades.
• ACWR (EWMA, opt-in): promedios exponenciales con λ_acute = 0.25 y λ_chronic ≈ 0.069 (Williams 2017, migration-101). Activable por org en organizations.acwr_method.
• %MD — mean(top_3 partidos) por jugador y métrica dentro de la ventana md_max_window_days, con sistema de tiers:
  • T1 (≥75 min) — referencia preferida.
  • T2 (45–74 min).
  • T3 (15–44 min).
  • Excluido: <15 min. NULL duration_min → tier limited (fallback).
• Cascada de fallback: titular → rotativo → suplente → limited → null. RPC get_md_reference_per_player (migration-100).
• HMLD — High Metabolic Load Distance (Osgnach 2010): distancia cubierta a ≥25.5 W/kg. Incluye aceleraciones/deceleraciones, por eso reemplazó a player_load AU en la UI.
• HSR — High Speed Running: distancia >19.8 km/h (umbral por defecto, varía por proveedor).
• Sprint: distancia >25.2 km/h (umbral por defecto).
• Predicción multi-métrica: cómputo determinístico en TS sobre gps_player_data + gps_sessions. No usa IA — es auditable línea por línea (actions.ts:getPredictionByMetric).

Importadores y fuentes

• CSV genérico (csv-parser.ts): autodetecta formato Catapult, GPexe (ES/EN, separador ;), STATSports. Columnas esperadas: nombre del jugador, distancia total (m), HSR (m), sprint (m), HMLD (m), velocidad máxima (km/h), duración (min). Nombres de jugador no matcheados disparan flujo de creación masiva (createPlayersFromCsv).
• Tachira (Excel custom): parser dedicado en lib/parsers/tachira-gps.ts. Detecta Condición (NORMAL / SANIDAD / SELECCIÓN / OTROS) y genera session_absences automáticamente según corresponda. [NEEDS_USER: ANONYMIZED_DATA ejemplo de planilla anonimizada]

Tablas DB / RPCs / vistas materializadas

• Tablas: gps_sessions, gps_player_data (con hmld_m, accelerations, decelerations, duration_min).
• Vista materializada: weekly_gps_summary con splits total_*/training_*/match_* para distance/hsr/sprint/hmld (migration-105).
• RPCs: get_acwr_batch, get_acwr_ewma_batch, get_acwr_hsr_batch, get_acwr_sprint_batch, get_acwr_hmld_batch, get_md_reference_per_player, get_vmax_per_player, get_vmax_pct_batch, get_gps_weekly_aggregation.

Integraciones

• Riesgo consume los cinco ACWR (distance / HSR / sprint / HMLD + EWMA opcional) y persiste el snapshot diario en risk_snapshots.
• Calendario aporta los partidos y duraciones que alimentan %MD.
• Plantel aporta players.current_acwr denormalizado para el semáforo del dashboard.
• Informe HoP usa la agregación semanal (matchLoad) en el PDF.

Limitaciones / roadmap

• season_comparisons sin gate: el tab Comparaciones se renderiza para esencial aunque el plan promete la feature solo en pro/enterprise. Pendiente agregar canUse guard (PROJECT_STATE.md, deuda técnica #2).
• Integraciones nativas con wearables (Garmin / WHOOP / Catapult API): prometidas como wearables_integration en pro/enterprise, no implementadas. Hoy todo entra por CSV/Excel.
• API pública de lectura (api_read): prometida, no implementada.
• EWMA para Sprint/HMLD: hoy EWMA solo aplica a distancia; Sprint/HMLD se calculan en RMA. Roadmap post PR 1B.
• Player Load deprecado en este módulo: la columna ya no existe en gps_player_data tras migration-105. Otros módulos que la leían fueron migrados.